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.
The TestBench grid hub listens to calls from test runners and delegates them to the grid nodes. The grid hub 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 hub
You can open the control interface of the hub also with a web
browser. Using the default port, just open URL
http://localhost:4444/
. Once you have started one or more grid
nodes, as instructed in the next section, the "console" page displays a
list of the grid nodes with their browser capabilities.
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 -nodeConfignodeConfig.json
See Section 20.7.4, “Starting a Grid Node” for further details on starting the node service.
The test node configuration file follows the JSON format, which
defines nested associative maps. An associative map is defined as a
block enclosed in curly braces ({}
). A mapping is a
key-value pair separated with a colon (:
). A key is
a string literal quoted with double quotes
("key"
). The value can be a string literal, list,
or a nested associative map. A list a comma-separated sequence
enclosed within square brackets ([]
).
The top-level associative map should have two associations:
capabilities
(to a list of associative maps) and
configuration
(to a nested associative map).
{
"capabilities":
[
{
"browserName": "firefox
",
...
},
...
],
"configuration":
{
"port": 5555,
...
}
}
A complete example is given later.
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
WINDOWS
, LINUX
, or
MAC
.
browserName
android
,
chrome
, firefox
,
htmlunit
, internet explorer
,
iphone
, opera
.
maxInstances
version
seleniumProtocol
WebDriver
for WebDriver use, or
Selenium
for tests in the HTML format.
firefox_binary
The node service configuration is defined as a nested associative map
as the value of the configuration
key. The
configuration parameters can also be given as command-line parameters
to the node service, as described in Section 20.7.4, “Starting a Grid Node”.
See the following example for a typical server configuration.
{ "capabilities": [ { "browserName": "firefox
", "maxInstances":5
, "seleniumProtocol": "WebDriver
", "version": "10
", "firefox_binary": "/path/to/firefox10
" }, { "browserName": "firefox
", "maxInstances":5
, "version": "16
", "firefox_binary": "/path/to/firefox16
" }, { "browserName": "chrome
", "maxInstances":5
, "seleniumProtocol": "WebDriver
" }, { "platform": "WINDOWS
", "browserName": "internet explorer
", "maxInstances":1
, "seleniumProtocol": "WebDriver
" } ], "configuration": { "proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy", "maxSession": 5, "port": 5555, "host": ip, "register": true, "registerCycle": 5000, "hubPort": 4444 } }
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 \ -hubhttp://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”.
If you use Chrome or Internet Explorer, their remote driver
executables must be in the system path (in the PATH
environment variable) or be given with a command-line parameter to the
node service:
-Dwebdriver.ie.driver=C:\path\to\IEDriverServer.exe
-Dwebdriver.chrome.driver=/path/to/ChromeDriver
Vaadin TestBench includes an iPhone and an Android driver, with which you can test on mobile devices. The tests can be run either in a device or in an emulator/simulator.
The actual testing is just like with any WebDriver, using either the
IPhoneDriver
or the
AndroidDriver
. The Android driver assumes that the
hub (android-server
) is installed in the emulator and
forwarded to port 8080 in localhost, while the iPhone driver assumes port
3001. You can also use the RemoteWebDriver
with
either the iphone()
or the
android()
capability, and specify the hub URI
explicitly.
The mobile testing setup is covered in detail in the Selenium documentation for both the IPhoneDriver and the AndroidDriver.