Browser Container Management

The BrowserWebDriverContainer class is the core component for creating and managing Selenium browser containers. It provides containerized instances of Chrome, Firefox, and Edge browsers with full configuration control.

Imports

import org.testcontainers.containers.BrowserWebDriverContainer;
import org.testcontainers.utility.DockerImageName;
import org.openqa.selenium.Capabilities;
import org.openqa.selenium.chrome.ChromeOptions;
import org.openqa.selenium.firefox.FirefoxOptions;
import org.openqa.selenium.edge.EdgeOptions;
import org.openqa.selenium.remote.RemoteWebDriver;
import java.net.URL;

Container Creation

Default Constructor

Creates a browser container with default Chrome configuration.

public BrowserWebDriverContainer();

Usage:

BrowserWebDriverContainer<?> container = new BrowserWebDriverContainer<>();

Custom Image Constructor

Creates a browser container with a specific Docker image.

public BrowserWebDriverContainer(String dockerImageName);
public BrowserWebDriverContainer(DockerImageName dockerImageName);

Parameters:

• dockerImageName: Docker image name (e.g., "selenium/standalone-firefox:4.15.0")

Usage:

// Using string image name
BrowserWebDriverContainer<?> firefox = new BrowserWebDriverContainer<>("selenium/standalone-firefox");

// Using DockerImageName
DockerImageName image = DockerImageName.parse("selenium/standalone-edge:4.15.0");
BrowserWebDriverContainer<?> edge = new BrowserWebDriverContainer<>(image);

Browser Configuration

Capabilities Configuration

Set browser-specific capabilities for the container.

public SELF withCapabilities(Capabilities capabilities);

Parameters:

• capabilities: Selenium Capabilities object (ChromeOptions, FirefoxOptions, EdgeOptions)

Usage:

ChromeOptions chromeOptions = new ChromeOptions();
chromeOptions.addArguments("--headless");
chromeOptions.addArguments("--no-sandbox");

BrowserWebDriverContainer<?> chrome = new BrowserWebDriverContainer<>()
    .withCapabilities(chromeOptions);

Deprecated Capabilities Method

@Deprecated
public SELF withDesiredCapabilities(DesiredCapabilities capabilities);

Note: Use withCapabilities(Capabilities) instead.

Container Access

Selenium WebDriver Endpoint

Get the URL endpoint for connecting RemoteWebDriver instances.

public URL getSeleniumAddress();

Returns: URL pointing to the Selenium WebDriver endpoint (typically http://host:port/wd/hub)

Usage:

BrowserWebDriverContainer<?> container = new BrowserWebDriverContainer<>()
    .withCapabilities(new ChromeOptions());
container.start();

URL seleniumUrl = container.getSeleniumAddress();
RemoteWebDriver driver = new RemoteWebDriver(seleniumUrl, new ChromeOptions());

VNC Access

Get the VNC connection string for debugging and monitoring.

public String getVncAddress();

Returns: VNC connection string (format: "vnc://vnc:secret@host:port")

Usage:

String vncUrl = container.getVncAddress();
// Connect with VNC client: vnc://vnc:secret@localhost:32768

Deprecated WebDriver Method

@Deprecated
public synchronized RemoteWebDriver getWebDriver();

Note: Use getSeleniumAddress() to create your own RemoteWebDriver instances instead.

Static Utility Methods

Docker Image Selection

@Deprecated
public static String getDockerImageForCapabilities(Capabilities capabilities, String seleniumVersion);

Note: This method is deprecated. Use the constructor with withCapabilities() instead.

Supported Browser Images

The container supports the following browser images:

• Chrome: selenium/standalone-chrome, selenium/standalone-chrome-debug
• Firefox: selenium/standalone-firefox, selenium/standalone-firefox-debug
• Edge: selenium/standalone-edge (Selenium 4+ only)

Container Lifecycle

The container integrates with JUnit test lifecycle:

public void afterTest(TestDescription description, Optional<Throwable> throwable);

This method is automatically called when using JUnit rules and handles cleanup including video recording retention based on test results.

Network Configuration

Legacy Container Linking

@Deprecated
public SELF withLinkToContainer(LinkableContainer otherContainer, String alias);

Note: Links are deprecated. Use Network features instead.

Container Lifecycle and Management

Container Stopping

The container properly manages resources during shutdown:

public void stop();

This method automatically handles cleanup of both the browser container and any associated VNC recording containers.

Test Integration

public void afterTest(TestDescription description, Optional<Throwable> throwable);

Automatic integration with JUnit test lifecycle for proper cleanup and video recording management based on test results.

Container Ports and Defaults

The container uses standard ports and defaults:

• Selenium Port: 4444 (default WebDriver endpoint port)
• VNC Port: 5900 (for VNC access and recording)
• Default VNC Password: "secret"

These values are used internally by the container and are accessible through the appropriate getter methods.