A short guide on how to configure ChromeDriver in Serenity BDD

John Ferguson Smart | Mentor | Author | Speaker - Author of 'BDD in Action'.
Helping teams deliver more valuable software soonerMay 22, 2017

Serenity BDD is an open source library that makes it easier to write high quality, maintainable automated acceptance tests. Serenity BDD has strong WebDriver integration, and manages the WebDriver instances for you. You almost never need to create or close your own WebDriver instance.

Chrome gives WebDriver developers a great deal of control, with many different options available. Now Serenity tries to make configuring your WebDriver instance as simple as possible. In the rest of this article, we will see a few tips and guidelines on how to use these options with Serenity BDD.

Setting the driver path

One rule of thumb is to never hard-code the path to the driver. Many projects I see set the webdriver.chrome.driver system property to some hard-coded value. For example, this could be a local Windows path such as “C:\Drivers\chromedriver.exe”. More sophisticated projects might prefer a local path, such as “src/test/resources/drivers/chromedriver.exe”. But both of these approaches should be avoided.

Hard-coded paths make your tests environment-dependent and difficult to run on other machines. For example, the examples shown above would not run on a linux build server. Instead, just make sure the chromedriver binary is on the system path. WebDriver will figure out the rest. If you must hard-code the path to the executable, do it as a command-line property:

$ mvn verify -Dwebdriver.chrome.driver=/path/to/driver

ChromeDriver gives you a few ways to configure it’s options, which are described here. Serenity lets you configure most of these options via the Serenity properties. We will see how to do this in the rest of the article.

Chrome arguments

When you create a ChromeDriver instance by hand, you can pass in arguments to the ChromeDriver using the addArguments() method:

ChromeOptions options = new ChromeOptions();

In Serenity, the —test-type switch is provided automatically. For the others, you would pass them in using the chrome.switches property, e.g.


Chrome preferences

You can also provide more advanced options using the setExperimentalOption() method:

Map<String, Object> chromePrefs = new HashMap<String, Object>();
chromePrefs.put("download.default_directory", downLoadDirectory);
chromePrefs.put("profile.default_content_settings.popups", 0);
chromePrefs.put("pdfjs.disabled", true);
ChromeOptions options = new ChromeOptions();
options.setExperimentalOption("prefs", chromePrefs);

In Serenity, you would pass these using properties prefixed with the chrome_preferences prefix, e.g.

chrome_preferences.download.default_directory = /my/download/directory
chrome_preferences.profile_default_content_settings.popups = 0

If you are using the TypeSafe configuration file format, you could write the following:

chrome_preferences {
    download.default_directory = /my/download/directory
    profile_default_content_settings.popups = 0

General capabilities

You can also add custom capabilities like this:

DesiredCapabilities cap = DesiredCapabilities.chrome();
cap.setCapability(CapabilityType.ACCEPT_SSL_CERTS, true);
cap.setCapability(CapabilityType.SUPPORTS_ALERTS, true);

Serenity lets you pass arbitrary capability properties to the Chrome driver using the chrome.capabilities. prefix, e.g

chrome.capabilities.acceptSslCerts = true
chrome.capabilities.handlesAlerts = true


You can usually configure most of the Chrome options you need using the Serenity properties. This avoids having to create a custom driver, which in turn makes your Serenity tests simpler and easier to maintain.

© 2019 John Ferguson Smart