You can also use Serenity to run your WebDriver tests on a remote machine, such as a Selenium Grid or a remote service such as provided by SauceLabs or BrowserStack. This allows you to run your web tests against a variety of different browsers and operating systems, and also benefit from faster test execution when running the tests in parallel.

In all cases, you tell Serenity to run tests remotely by using the Selenium Remote driver,

Running tests against a Selenium Grid server

Selenium Grid allows you to run tests on a number of remote machines. It is open source, and relatively easy to set up and configure.

To run your Serenity tests on a Selenium Grid, you need to provide the URL of the Selenium Hub using the webdriver.remote.url property. You may also want to provide more information about how and where you want to run your tests, using the following properties: webdriver.remote.driver:: What driver to use remotely ('firefox','chrome','iexplorer' etc.) webdriver.remote.browser.version:: What version of the remote browser to use webdriver.remote.os:: What operating system the tests should be run on.

For example, if you were running a Selenium Hub locally on port 4444 (the default),

mvn verify -Dwebdriver.remote.url=http://localhost:4444/wd/hub -Dwebdriver.remote.driver=chrome -Dwebdriver.remote.os=WINDOWS

If you are running PhantomJS remotely, you may need to specify what port PhantomJS is to run on using the phantomjs.webdriver property.

mvn verify -Dphantomjs.webdriver=5555 -Dwebdriver.remote.url=http://seleniumgrid:4444/wd/hub

You can also pass the usual driver-specific capabilities to the remote browser

mvn verify -Dwebdriver.remote.url=http://localhost:4444/wd/hub -Dwebdriver.remote.driver=chrome -Dwebdriver.remote.os=WINDOWS -Dchrome.switches="--no-sandbox,--ignore-certificate-errors,--homepage=about:blank,--no-first-run"

Running tests on Appium

Serenity supports running tests on mobile devices/emulators out of the box with Appium.

You just need to install Appium:

(sudo) npm install -g appium --chromedriver_version="2.16"

Afterwards Appium is available as command and can be started by invoking the following command:


Then adopt to run on an Android device:

webdriver.driver= appium
webdriver.base.url =
appium.hub =
appium.platformName = Android
appium.platformVersion = 5.1.1
appium.deviceName = e2f5c460
appium.browserName = Chrome

Here’s an example for iOS:

webdriver.driver= appium
webdriver.base.url =
appium.hub =
appium.platformName = iOS
appium.platformVersion = 8.1
appium.deviceName = iPhone 5
appium.browserName = Safari

All properties which are starting with appium in will be forwarded to appium driver. e.g. setting appium.automationName = XCUITest in will have as end effect setting the property automationName = XCUITest in appium driver capabilities.

Besides the properties file you can also use commandline switches:

mvn test -Dappium.hub= -Dwebdriver.driver=appium -Dappium.platformName=iOS -Dappium.browserName=Safari -Dappium.deviceName="iPhone 5"

All properties starting with appium.* will be forwarded to the appium driver as appium desired capabilities. For example, setting the property appium.automationName=myAutomationName will have as effect setting the capability automationName in the appium driver to myAutomationName.

Following annotations are supported for a PageObject element:

private WebElement loginButton;
private WebElement loginButton;
private WebElement loginButton;

Sometimes it may be necessary in a PageObject to use specific methods of the underlying driver

AndroidDriver<AndroidElement> androidDriver() {
    return (AndroidDriver<AndroidElement>)
            ((WebDriverFacade) getDriver()).getProxiedDriver();

You can also add Appium to an existing grid. See the Appium documentation for more details about the node-config option.

Running tests on SauceLabs

Serenity has special support for running tests on the Cloud-based testing platform SauceLabs. The general approach is the same as discussed above, but there are a few extra Saucelabs-specific properties:


Usually of the form http://<my_id>:<my_API Key>




The name of the test as it will appear on the Saucelabs site


Your Saucelabs API key, optional, used to generate links to the Saucelabs results

Your Saucelabs User ID, optional, used to generate links to the Saucelabs results saucelabs.record.screenshots::Saucelabs records screenshots as well as videos by default. Since Serenity also records screenshots, this feature is disabled by default. It can be reactivated using this system property


Override the default implicit timeout value for the Saucelabs driver

An example of running tests on Saucelabs is shown here:

mvn verify -Dwebdriver.driver=chrome -Dsaucelabs.driver.version=26 -Dsaucelabs.url=http://<my_id>:<my_API Key> -Dsaucelabs.access.key=<My_API_Key><my_id> -Dwebdriver.base.url= -Dmaven.test.failure.ignore=true

In case if you need to define an OS-Browser Combination, you should change serenity.driver.capabilities as follows:

serenity.driver.capabilities="browserName:iphone; deviceName:iPad Retina; version:9.2"

Running Serenity Tests on BrowserStack

Serenity provides integrated support for running tests on BrowserStack.

First of all, add the serenity-browserstack dependency to your project:


Next, in your serenity.conf configuration file, add a browserstack section with your BrowserStack username and API key, like this:

browserstack {
    user = <your-username>
    key = <your-api-key>
    server =
    browser = chrome

In the webdriver section, you need to configure a remote driver like this:

webdriver {
    driver = remote
    remote.url = "http://<your-username>:<your-api-key>"

You can also do the same thing in your file, e.g.

browserstack.server =
browserstack.browser = chrome

webdriver.driver = remote;
webdriver.remote.url = "http://<your-username>:<your-api-key>"


If your BrowserStack account is limited to a certain number of parallel tests, BrowserStack will add your tests to a queue. If your queue reaches a maximum size, BrowserStack will refuse to run your tests until a spot frees up. Serenity allows for this by delaying the test execution for 30 seconds before retrying. Serenity will retry up to 30 times by default; you can configure the maximum number of retries Serenity will attempt with the webdriver.creation.retry.max.times system property.

BrowserStack system properties

The following system properties are available:


BrowserStack Hub URL if running the tests on BrowserStack Cloud


OS type (e.g. WINDOWS, OS X)


OS version (e.g. Windows: XP, 7, 8 and 8.1; OS X: Snow Leopard, Lion, Mountain Lion, Mavericks, Yosemite, El Capitan)


Browser type (e.g. Firefox, Safari, IE, Chrome, Opera)


Browser version (defaults to latest stable; check list of available browsers)


BrowserStack mobile device name on which tests should be run


Set the screen orientation of BrowserStack mobile device (portrait or landscape, default: portrait)


Specify a name for a logical group of builds on BrowserStack

Specify a name for a logical group of tests on BrowserStack

Specify an identifier for the test run on BrowserStack


For Testing against internal/local servers on BrowserStack


Specify an identifier for the local BrowserStack connection check


Generates screenshots at various steps in tests on BrowserStack


Sets resolution of VM on BrowserStack


Disable flash on Internet Explorer on BrowserStack

Specify the Internet Explorer webdriver version on BrowserStack

Enable the popup blocker in Internet Explorer on BrowserStack

Running Serenity on Zalenium

In this section, we look at how you can run Serenity BDD tests on a Zalenium server using Docker. Zalenium is an open source tool based on Docker that makes it easy to start up and run a Selenium Grid. The rest of this tutorial assumes that you have Docker installed on your machine.

Starting Zalenium

You can start a Zalenium server using the following commands (see the Zalenium Documentation for more details or for the latest version of these instructions):

# Pull docker-selenium
docker pull elgalu/selenium

# Pull Zalenium
docker pull dosel/zalenium

# Run it!
docker run --rm -ti --name zalenium -p 4444:4444 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /tmp/videos:/home/seluser/videos -e WAIT_FOR_AVAILABLE_NODES=false \
  --privileged dosel/zalenium start --desiredContainers 4

You should end up seeing an output like the following:

08:42:05.272 [main] INFO  org.openqa.grid.web.Hub - Selenium Grid hub is up and running
08:42:05.272 [main] INFO  org.openqa.grid.web.Hub - Nodes should register to
08:42:05.272 [main] INFO  org.openqa.grid.web.Hub - Clients should connect to
Selenium Hub started!
Sauce Labs not enabled...
Browser Stack not enabled...
TestingBot not enabled...
Zalenium is now ready!

You can see if the Zalenium server is running correctly by checking out the Grid Console.

Configuring your Serenity tests

To run your tests on the Selenium grid, you now just need to use the remote driver instead of the usual one. For example, in your serenity.conf file, you can configure your tests to run on the Zalenium server using Chrome like this:

webdriver {
  driver = remote
  remote {

If you are using the file, the configuration would look like this:

webdriver.driver = remote
webdriver.remote.url = "http://localhost:4444/wd/hub"
webdriver.remote.driver = chrome

Zalenium even has a Dashboard where you can see a recording of the tests you executed.

Advanced Zalenium Integration

Serenity also supports more advanced integration with Zalenium, including the ability to pass custom capabilities to the Zalenium server, and displaying the test results correctly. You can enable these features by adding the serenity-zalenium dependency to your project. If you are using Maven, you would add the following dependency:


And in Gradle, you would add the equivalent dependency like this:

testCompile 'net.serenity-bdd:serenity-zalenium:${serenity.version}'

When you add this dependency, unsuccessful tests (those with an outcome of failed, broken or compromised) will be marked as failures in Zalenium.

zalenium {
    screenResolution = "1280x720"
    idleTimeout = 150