A distributed test environment consists of a grid hub and a number of test nodes. The hub listens to calls from test runners and delegates them to the grid nodes. Different nodes can run on different operating system platforms and have different browsers installed.

A basic distributed installation was covered in Section 20.2.2, “A Distributed Testing Environment”.

Remote tests are just like locally executed JUnit tests, except instead of using a browser driver, you use a RemoteWebDriver that can connect to the hub. The hub delegates the connection to a grid node with the desired capabilities, that is, which browsers are installed in a suitable node. The capabilities are described with a DesiredCapabilities object.

For example, in the example tests given in the example folder, we create and use a remote driver as follows:

@Test
public void testRemoteWebDriver() throws MalformedURLException {
    // Require Firefox in the test node
    DesiredCapabilities capability =
        DesiredCapabilities.firefox();

    // Create a remote web driver that connects to a hub
    // running in the local host
    WebDriver driver = TestBench.createDriver(
        new RemoteWebDriver(new URL(
            "http://localhost:4444/wd/hub"), capability));

    // Then use it to run a test as you would use any web driver
    try {
        driver.navigate().to(
            "http://demo.vaadin.com/sampler#TreeActions");
        WebElement e = driver.findElement(By.xpath(
            "//div[@class='v-tree-node-caption']"+
            "/div[span='Desktops']"));
        new Actions(driver).moveToElement(e).contextClick(e)
            .perform();
    } finally {
        driver.quit();
    }
}

Please see the API documentation of the DesiredCapabilities class for a complete list of supported capabilities.

Running the example requires that the hub service and the nodes are running. Starting them is described in the subsequent sections. Please refer to Selenium documentation for more detailed information.

Test nodes can be configured with command-line options, as described later, or in a configuration file in JSON format. If no configuration file is provided, a default configuration is used.

A node configuration file is specified with the -nodeConfig parameter to the node service, for example as follows:

$ java -jar vaadin-testbench-standalone-3.1.0.jar
       -role node -nodeConfig nodeConfig.json

See Section 20.7.4, “Starting a Grid Node” for further details on starting the node service.

The browser capabilities are defined as a list of associative maps as the value of the capabilities key. The capabilities can also be given from command-line using the -browser parameter, as described in Section 20.7.4, “Starting a Grid Node”.

The keys in the map are the following:

platform
The operating system platform of the test node. Can be WINDOWS, LINUX, or MAC.
browserName
A browser identifier, any of: android, chrome, firefox, htmlunit, internet explorer, iphone, opera.
maxInstances
The maximum number of browser instances of this type open at the same time for parallel testing.
version
The major version number of the browser.
seleniumProtocol
This should be WebDriver for WebDriver use, or Selenium for tests in the HTML format.
firefox_binary
Full path and file name of the Firefox executable. This is typically needed if you have Firefox ESR installed in a location that is not in the system path.

A TestBench grid node listens to calls from the hub and is capable of opening a browser. The grid node service is included in the Vaadin TestBench JAR and you can start it with the following command:

$ java -jar \
       vaadin-testbench-standalone-3.1.0.jar \
       -role node \
       -hub http://localhost:4444/grid/register

The node registers itself in the grid hub. You need to give the address of the hub either with the -hub parameter or in the node configuration file as described in Section 20.7.3, “Node Service Configuration”.

You can run one grid node in the same host as the hub, as is done in the example above with the localhost address. In such case notice that, at least in OS X, you may need to duplicate the JAR to a separate copy to use it to run a grid node service.

The browsers installed in the node can be defined either with a command-line parameter or with a configuration file in JSON format, as described in Section 20.7.3, “Node Service Configuration”.

On command-line, you can issue a -browser option to define the browser capabilities. It must be followed by a comma-separated list of property-value definitions, such as the following:

-browser "browserName=firefox,version=10,firefox_binary=/path/to/firefox10" \
-browser "browserName=firefox,version=16,firefox_binary=/path/to/firefox16" \
-browser "browserName=chrome,maxInstances=5" \
-browser "browserName=internet explorer,maxInstances=1,platform=WINDOWS"

The configuration properties are described in Section 20.7.3, “Node Service Configuration”.