Webdriver Containers

Testcontainers can be used to automatically instantiate and manage containers that include web browsers, such as those from SeleniumHQ's docker-selenium project.


  • Fully compatible with Selenium 2/Webdriver tests, by providing a RemoteWebDriver instance
  • No need to have specific web browsers, or even a desktop environment, installed on test servers. The only dependency is a working Docker installation and your Java JUnit test suite.
  • Browsers are always launched from a fixed, clean image. This means no configuration drift from user changes or automatic browser upgrades.
  • Compatibility between browser version and the Selenium API is assured: a compatible version of the browser docker images will be automatically selected to match the version of selenium-api-*.jar on the classpath
  • Additionally the use of a clean browser prevents leakage of cookies, cached data or other state between tests.
  • VNC screen recording: Testcontainers can automatically record video of test runs (optionally capturing just failing tests)

Creation of browser containers is fast, so it's actually quite feasible to have a totally fresh browser instance for every test.


The following field in your JUnit UI test class will prepare a container running Chrome:

public BrowserWebDriverContainer<?> chrome = new BrowserWebDriverContainer<>()
    .withCapabilities(new ChromeOptions())

Now, instead of instantiating an instance of WebDriver directly, use the following to obtain an instance inside your test methods:

RemoteWebDriver driver = chrome.getWebDriver();

You can then use this driver instance like a regular WebDriver.

Note that, if you want to test a web application running on the host machine (the machine the JUnit tests are running on - which is quite likely), you'll need to replace any references to localhost with an IP address that the Docker container can reach. Use the getTestHostIpAddress() method, e.g.:

String hostIpAddress = chrome.getTestHostIpAddress();
driver.get("http://" + hostIpAddress + ":" + localPort);


Other browsers

At the moment, Chrome and Firefox are supported. To switch, simply change the first parameter to the rule constructor:

public BrowserWebDriverContainer<?> chrome = new BrowserWebDriverContainer<>()
    .withCapabilities(new ChromeOptions())
public BrowserWebDriverContainer<?> firefox = new BrowserWebDriverContainer<>()
        .withCapabilities(new FirefoxOptions())

Recording videos

By default, no videos will be recorded. However, you can instruct Testcontainers to capture videos for all tests or just for failing tests.

// To do this, simply add extra parameters to the rule constructor:
BrowserWebDriverContainer<?> chrome = new BrowserWebDriverContainer<>()
    .withCapabilities(new ChromeOptions())
    .withRecordingMode(RECORD_ALL, target)
// or if you only want videos for test failures:
BrowserWebDriverContainer<?> chrome = new BrowserWebDriverContainer<>()
    .withCapabilities(new ChromeOptions())
    .withRecordingMode(RECORD_FAILING, target)

Note that the seconds parameter to withRecordingMode should be a directory where recordings can be saved.

If you would like to customise the file name of the recording, or provide a different directory at runtime based on the description of the test and/or its success or failure, you may provide a custom recording file factory as follows:

BrowserWebDriverContainer<?> chrome = new BrowserWebDriverContainer<>()

    .withRecordingFileFactory(new CustomRecordingFileFactory())

Note the factory must implement org.testcontainers.containers.RecordingFileFactory.

More examples

A few different examples are shown in ChromeWebDriverContainerTest.java.

Adding this module to your project dependencies

Add the following dependency to your pom.xml/build.gradle file:

testCompile "org.testcontainers:selenium:1.15.1"


Adding this Testcontainers library JAR will not automatically add a Selenium Webdriver JAR to your project. You should ensure that your project also has suitable Selenium dependencies in place, for example:

compile "org.seleniumhq.selenium:selenium-remote-driver:3.141.59"

Testcontainers will try and match the version of the Dockerized browser to whichever version of Selenium is found on the classpath