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.

Benefits

• Fully compatible with Selenium 3 & 4 tests for Chrome and Firefox and Selenium 4 tests for Edge, 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.

Example

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

Chrome

public BrowserWebDriverContainer chrome = new BrowserWebDriverContainer("selenium/standalone-chrome:4.13.0")

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

RemoteWebDriver

RemoteWebDriver driver = new RemoteWebDriver(chrome.getSeleniumAddress(), new ChromeOptions());

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 use the host exposing feature of Testcontainers, e.g.:

Open Web Page

Testcontainers.exposeHostPorts(localPort);
driver.get("http://host.testcontainers.internal:" + localPort);

Options

Other browsers

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

Chrome

public BrowserWebDriverContainer chrome = new BrowserWebDriverContainer("selenium/standalone-chrome:4.13.0")

Firefox

public BrowserWebDriverContainer firefox = new BrowserWebDriverContainer("selenium/standalone-firefox:4.13.0")

Edge

public BrowserWebDriverContainer edge = new BrowserWebDriverContainer("selenium/standalone-edge:4.13.0")

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.

Record all Tests

// To do this, simply add extra parameters to the rule constructor, so video will default to FLV format:
BrowserWebDriverContainer chrome = new BrowserWebDriverContainer("selenium/standalone-chrome:4.13.0")
    .withRecordingMode(VncRecordingMode.RECORD_ALL, target)

Record failing Tests

// or if you only want videos for test failures:
BrowserWebDriverContainer chrome = new BrowserWebDriverContainer("selenium/standalone-chrome:4.13.0")
    .withRecordingMode(VncRecordingMode.RECORD_FAILING, target)

Note that the second parameter of withRecordingMode should be a directory where recordings can be saved.

By default, the video will be recorded in FLV format, but you can specify it explicitly or change it to MP4 using withRecordingMode method with VncRecordingFormat option:

Video Format in MP4

// Set MP4 format for recorded video:
BrowserWebDriverContainer chrome = new BrowserWebDriverContainer("selenium/standalone-chrome:4.13.0")
    .withRecordingMode(VncRecordingMode.RECORD_ALL, target, VncRecordingFormat.MP4)

Video Format in FLV

// Set (explicitly) FLV format for recorded video:
BrowserWebDriverContainer chrome = new BrowserWebDriverContainer("selenium/standalone-chrome:4.13.0")
    .withRecordingMode(VncRecordingMode.RECORD_ALL, target, VncRecordingFormat.FLV)

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:

CustomRecordingFileFactory

BrowserWebDriverContainer chrome = new BrowserWebDriverContainer("selenium/standalone-chrome:4.13.0")

⋯

    .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:

GradleMaven

testImplementation "org.testcontainers:testcontainers-selenium:2.0.5"

<dependency>
    <groupId>org.testcontainers</groupId>
    <artifactId>testcontainers-selenium</artifactId>
    <version>2.0.5</version>
    <scope>test</scope>
</dependency>

Hint

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:

GradleMaven

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

<dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-remote-driver</artifactId>
    <version>3.141.59</version>
</dependency>

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