Download

The first step for driver management is to download the proper driver. Table 2-1 shows the online websites to obtain the drivers for the main browsers. You need to find the correct driver version and platform (Windows, Linux, Mac OS) for the browser you plan to use. Regarding the version, the Chrome and Edge (although not Firefox, unfortunately) maintainers follow the same versioning schema for drivers and browsers to ease this process. So, for instance, if you use Chrome or Edge 91.x, you also need to use chromedriver and msedgedriver 91.x. You will find the specific driver version in the documentation provided on the websites above. For instance, to use Chrome 91, you need to download ChromeDriver 91.0.4472.19.

Setup

Once you have the required driver for your WebDriver script, you need to set it up correctly. There are two ways to carry out this process. The first one is adding the driver location (the full path or the parent folder which contains the driver) to your PATH environmental variable (env). The PATH env is standard in Unix-like (e.g., Linux and Mac OS) and Windows operating systems. This environmental variable allows specifying a set of folders in which the operating system locates executable programs. The way we configure PATH (and other environmental variables) depends on the specific operating system. For example, in Windows systems, we can do it using its GUI (Control Panel → System → Advanced → Environment Variables). In a Unix-like system, we can use the command line to carry out this process, for instance, using the following command (or equivalent):

export PATH=$PATH:/path/to/drivers >> ~/.profile

The second way to set up the driver is using Java system properties, which are configuration attributes (in the form of name/value) passed to the JVM. Table 2-2 summarizes the names for the main drivers in Selenium WebDriver. The value for these properties is the full path of a given driver (e.g., /path/to/drivers/chromedriver).

There are two ways to configure these properties: the command line (passing the system property using the -Dname=value syntax) or Java code. For example, Example 2-1 shows the Maven and Gradle commands to execute all the tests of a given project while passing the properties to set up the drivers for Chrome, Edge, and Firefox. Then, Example 2-2 shows how to make the same configuration, but this time using Java.

mvn test -Dwebdriver.chrome.driver=/path/to/drivers/chromedriver
mvn test -Dwebdriver.edge.driver=/path/to/drivers/msedgedriver
mvn test -Dwebdriver.gecko.driver=/path/to/drivers/geckodriver

gradle test -Dwebdriver.chrome.driver=/path/to/drivers/chromedriver
gradle test -Dwebdriver.edge.driver=/path/to/drivers/msedgedriver
gradle test -Dwebdriver.gecko.driver=/path/to/drivers/geckodriver

System.setProperty("webdriver.chrome.driver", "/path/to/drivers/chromedriver");
System.setProperty("webdriver.edge.driver", "/path/to/drivers/msedgedriver");
System.setProperty("webdriver.gecko.driver", "/path/to/drivers/geckodriver");

Maintenance

Last but not least, the final step of driver management is to maintain these drivers. This maintenance is necessary because evergreen browsers (such as Chrome, Edge, or Firefox) upgrade themselves automatically. Although appealing from a user perspective, this automated upgrade is problematic for Selenium WebDriver scripts where the driver management is manual. In this case, the driver and browser compatibility is not guaranteed in the long run.

A specific driver (e.g., chromedriver version 84.0.4147.30) is typically compatible with a given browser version (e.g., Chrome 84). Eventually, and because of the automatic upgrade, this compatibility is not guaranteed. As a result, a Selenium WebDriver script based on this driver stops working. In practice, Selenium WebDriver developers experience this problem when tests fail because of driver and browser incompatibility. For instance, when using Chrome as a browser, a decayed test due to driver incompatibility reports the following error message: “this version of chromedriver only supports chrome version N” (where N is the latest version of Chrome supported by a particular version of chromedriver). To illustrate this problem, Figure 2-1 shows the worldwide search interest of that error message on Google during 2019 and 2020, together with the release date of the different Chrome versions in this period. As you can see, the interest over time concerning this error message is related to some Chrome releases.

Figure 2-1. Worldwide relative interest overtime of the search term “this version of chromedriver only supports chrome version” in Google Trends together with the release dates of Chrome during 2019 and 2020

WebDriverManager Methodology

WebDriverManager internally executes a resolution algorithm to manage the drivers required by Selenium WebDriver. This algorithm aims to discover, download, set up, and maintain these drivers automatically. Figure 2-3 represents this algorithm in the context of the methodology implemented by WebDriverManager. You can find the details of this methodology next.

Figure 2-3. WebDriverManager methodology

For a given manager (e.g., chromedriver()), the most relevant parts of the resolution algorithm are:

1. WebDriverManager tries to find the browser version (e.g., Chrome) installed in the local machine. For that, it uses an internal knowledge database called commands database. This database contains a list of shell commands (in different operating systems) that allow discovering the browser versions (e.g., google-chrome --version in Linux).

2. Using the found major browser version (e.g., Chrome 89), WebDriverManager determines the correct driver version (e.g., chromedriver 89.0.4389.23). I call this process version resolution. To ease this process, several driver maintainers (i.e., chromedriver and msedgedriver) publish the specific driver version in their online repositories using simple text files (e.g., https://chromedriver.storage.googleapis.com/LATEST_RELEASE_89). Unfortunately, this information is not available for other drivers, such as geckodriver or operadriver. For this reason, WebDriverManager uses another internal knowledge database (called versions database) to keep the association between the versions of browsers and drivers. Both versions and commands databases synchronize their values using an online master reference stored on GitHub.

3. WebDriverManager downloads the specific driver for the local operating system (Windows, Linux, or Mac OS) and stores it in the local filesystem in the driver cache (by default, in the path ~/.cache/selenium).

4. Finally, WebDriverManager exports the downloaded driver path using the proper Java system property (e.g., webdriver.chrome.driver).

For the sake of performance and maintainability, WebDriverManager internally uses a resolution cache. This cache (by default stored in the driver cache as a properties file) keeps the relationship between the resolved driver versions. This relationship is valid following a time-to-live (TTL) approach. The default value of this TTL is one day for drivers (e.g., chromedriver 89.0.4389.23) and one hour for browsers (e.g., Chrome 89). The resolution algorithm resolves drivers using the cached files in the subsequent invocations (this usually happens in a Selenium WebDriver test suite). Then, when a TTL expires, the resolution algorithm tries to resolve a new driver release. Finally, when a different browser version is detected, WebDriverManager downloads the new driver (if required). Thanks to this process, the version compliance of browser and driver is warranted even for evergreen browsers.

JUnit 4

JUnit is a unit testing framework for Java created by Erich Gamma and Kent Beck in 1999. It is considered by many as the de facto standard framework for developing tests in Java. In JUnit, a test is a method within a Java class used for testing. As of JUnit 4, the building blocks for developing JUnit tests are Java annotations. The fundamental annotation of JUnit 4 is @Test since it allows identifying the method(s) which contain the test logic (i.e., the code used to exercise and verify a piece of software). In addition, there are other annotations to identify the methods used for the setup (i.e., what happens before the tests) and the teardown (i.e., what happens after the tests).

• @BeforeClass is executed once before all tests.

• @Before is excuted before each test.

• @After is excuted after each test.

• @BeforeClass is executed once after all tests.

Figure 2-4 shows a graphical representation of the basic test lifecycle in JUnit 4.

Figure 2-4. JUnit 4 test lifecycle

Following this approach, Example 2-3 contains the structure I recommend for using Selenium WebDriver and WebDriverManager in a JUnit 4 test.

package io.github.bonigarcia.webdriver.junit4.ch2.skeletons;

import org.junit.After;
import org.junit.Before;
import org.junit.BeforeClass;
import org.junit.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import io.github.bonigarcia.wdm.WebDriverManager;

public class SkeletonChromeJUnit4Test {

    private WebDriver driver; 

    @BeforeClass
    public static void setupClass() {
        WebDriverManager.chromedriver().setup(); 
    }

    @Before
    public void setup() {
        driver = new ChromeDriver(); 
    }

    @After
    public void teardown() {
        driver.quit(); 
    }

    @Test
    public void test() {
        // TODO: use variable "driver" to call the Selenium WebDriver API 
    }

}

We declare a Java attribute using the interface WebDriver. We use this variable in tests to control web browsers with Selenium WebDriver.

In the setup for all tests within this class (i.e., executed once), we call WebDriverManager to manage the required driver. In this example, since we use Chrome as a browser, we need to resolve chromedriver.

In the setup for each test, we instantiate some specific WebDriver object, in this case, ChromeDriver, since we use Chrome¹.

The test logic will use the Selenium WebDriver API through the driver variable. This part is pending so far.

At the end of each test, we need to close the browser. To that aim, ew can invoke the method quit() of the driver object (you can see more info about how to close WebDriver objects in Chapter 3).

JUnit 5

Due to several limitations in JUnit 4 (such as monolithic architecture or impossibility to compose JUnit runners), the JUnit team released a new major version (i.e., JUnit 5) in 2017. JUnit has been redesigned entirely in version 5, following a modular architecture consisting of three components (see in Figure 2-5). The first component is the JUnit Platform, which is the foundation of the whole framework. The goal of the JUnit Platform is two-folded:

1. It allows the discovery and execution (sequential or parallel) of tests in the JVM through the test launcher API. This API is typically used by programmatic clients such as build tools and IDEs.

2. It defines the test engine API for developing tests that run on the JUnit Platform. This API is typically used by frameworks that provide programming models for testing.

Figure 2-5. JUnit 5 architecture

Thanks to the test engine API, third-party test frameworks can execute tests on top of the JUnit Platform. Some examples of existing testing frameworks that have implemented test engines for JUnit 5 are Cucumber or Spock. In addition, JUnit 5 provides two implementations of the test engine API out-of-the-box. These engines are the remaining components of the JUnit 5 architecture, namely:

• Vintage: test engine that provides backward compatibility with legacy JUnit tests (i.e., versions 3 and 4).

• Jupiter: test engine that provides a new programming and extension model.

Jupiter is a relevant component of JUnit 5 since it provides a brand-new API to develop tests using a robust programming model. Some of the features of this programming model are:

• Parameterized tests.

• Parallel execution.

• Tagging and filtering.

• Ordered and tests.

• Repeated and nested tests.

• Rich capabilities to disable tests (ignored in execution).

Like JUnit 4, Jupiter also uses Java annotations to declare test cases. For instance, the annotation to identify methods with testing logic is also @Test. The name of the rest of the annotations for the basic test lifecycle is a bit different in Jupiter: @BeforeAll, @BeforeEach, @AfterEach, and @AfterAll. As you can see in Figure 2-6, each of these annotations follows the same workflow of JUnit 4.

Figure 2-6. JUnit 5 test lifecycle

Thus, the structure of a Jupiter test using Selenium WebDriver and WebDriverManager is quite similar in JUnit 4 and JUnit 5. In addition to the change in the setup and teardown annotation names, the test methods (and their lifecycle) are not required to be public in the Jupiter programming model. Example 2-4 provides an example of a Jupiter test, this time using Edge as the browser.

package io.github.bonigarcia.webdriver.jupiter.ch2.skeletons;

import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.edge.EdgeDriver;
import io.github.bonigarcia.wdm.WebDriverManager;

class SkeletonEdgeJupiterTest {

    private WebDriver driver;

    @BeforeAll
    static void setupClass() {
        WebDriverManager.edgedriver().setup();
    }

    @BeforeEach
    void setup() {
        driver = new EdgeDriver();
    }

    @AfterEach
    void teardown() {
        driver.quit();
    }

    @Test
    void test() {
        // TODO: use variable "driver" to call the Selenium WebDriver API
    }

}

JUnit 5 with Selenium-Jupiter

The extension model of Jupiter allows adding custom features to the default programming model. To that aim, Jupiter provides an API that developers can extend (using interfaces called extension points) to provide custom functionality. The categories of these extension points are the following:

• Test lifecycle callbacks: to include custom logic in different moments of the test lifecycle

• Parameter resolution: to implement dependency injection (i.e., parameters injected in test methods or constructors).

• Test templates: to repeat the tests based on a given context.

• Conditional test execution: to enable or disable tests depending on custom conditions.

• Exception handling: to manage Java exceptions during the test and its lifecycle.

• Test instance: to create and process test class instances.

• Intercepting invocations: to intercept calls to test code (and decide whether or not these calls proceed).

As a Jupiter developer, you can implement your custom extension or using the existing ones. Table 2-5 shows some examples of Jupiter extensions.

Selenium-Jupiter is an attractive option in the context of this book since it enables using Selenium WebDriver in Jupiter tests seamlessly. The bases of Selenium-Jupiter are the following:

• Reduced boilerplate code in test cases. Thanks to the parameter resolution feature provided by the Jupiter programming model, Selenium-Jupiter allows declaring an object of the WebDriver hierarchy (e.g., ChromeDriver, FirefoxDriver, etc.) to control web browsers from tests as a constructor or test parameters.

• Automated driver management through WebDriverManager. Thanks to the test lifecycle callbacks provided by the extension model, the usage of WebDriverManager is entirely transparent for Selenium-Jupiter users.

• Advanced capabilities for end-to-end testing. For instance, seamless integration with Docker, test templates (for cross-browser testing), or troubleshooting and monitoring capabilities (e.g., session recordings or configurable screenshots).

Example 2-4 provides the structure of a test using JUnit 5 and Selenium-Jupiter. As you can see, to use Selenium-Jupiter, first, you need to declare its usage in a Jupiter test using the annotation @ExtendWith. Then, you need to select a type of the WebDriver hierarchy (FirefoxDriver in this example) and declare it as a test (or constructor) parameter. Internally, Selenium-Jupiter resolves the proper driver (geckodriver in this example) using WebDriverManager and instantiates the WebDriver object before each test. Finally, when the test finishes, Selenium-Jupiter disposes of the WebDriver object gracefully.

package io.github.bonigarcia.webdriver.seljup.ch2.helloworld;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.openqa.selenium.firefox.FirefoxDriver;
import io.github.bonigarcia.seljup.SeleniumJupiter;

@ExtendWith(SeleniumJupiter.class)
class SkeletonFirefoxSelJupTest {

    @Test
    void test(FirefoxDriver driver) {
        // TODO: use variable "driver" to call the Selenium WebDriver API
    }

}

TestNG

The last unit testing framework I use in this book is TestNG. Some of the more significant features that provide TestNG are the following:

• It provides parallel execution of tests.

• It allows assigning priority to tests.

• It allows the grouping of tests.

• It supports parameterizing tests.

• It allows data-driven testing using custom annotations.

• It provides a rich set of assertions.

• It enables the creation of detailed HTML reports.

In the same way as JUnit 4 and Jupiter, TestNG also use Java annotations to declare tests and their lifecycle (i.e., what happens before and after each test). Again, the annotation @Test is used to designate test methods. Then, it provides the annotations @BeforeClass and @BeforeMethod to specify the test setup, and @AfterMethod and @AfterClass for the teardown (see Figure 2-7). In addition, TestNG allows to group the tests contained in Java classes using the following terminology:

• Suite, which consists of one or more tests.

• Test, which consists of one or more classes.

• Class, which is a Java class with testing method(s), e.g., annotated with @Test.

Following this notation, and as represented in Figure 2-7, TestNG provides additional annotations to execute custom logic before and after the suite and the test(s).

Figure 2-7. TestNG test lifecycle

All in all, the structure of a test using TestNG, Selenium WebDriver, and WebDriverManager, is again quite similar to the JUnit 4 and Jupiter tests. Example 2-6 shows a test skeleton using TestNG and Chrome.

package io.github.bonigarcia.webdriver.testng.ch2.mainbrowsers;

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.testng.annotations.AfterMethod;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.BeforeMethod;
import org.testng.annotations.Test;
import io.github.bonigarcia.wdm.WebDriverManager;

public class SkeletonChromeNGTest {

    private WebDriver driver;

    @BeforeClass
    public void setupClass() {
        WebDriverManager.chromedriver().setup();
    }

    @BeforeMethod
    public void setup() {
        driver = new ChromeDriver();
    }

    @AfterMethod
    public void teardown() {
        driver.quit();
    }

    @Test
    public void test() {
        // TODO: use variable "driver" to call the Selenium WebDriver API
    }

}

Examples Repository Layout

The example repository is a vital ingredient of this book since it contains all the covered examples. Furthermore, it has the complete configuration of Maven and Gradle. Figure 2-10 shows the schematic representation of the examples repository layout. Since I am providing each example in four flavors (JUnit 4, JUnit 5, JUnit 5 plus Selenium-Jupiter, and TestNG), the configuration in both Maven and Gradle is based on multi-projects. This way, the examples repository has four modules, each one per testing framework, namely: selenium-webdriver-junit4, selenium-webdriver-junit5, selenium-webdriver-junit5-seljup, and selenium-webdriver-testng. In Maven, the multi-project setup is in the pom.xml located in the root folder, while in the file settings.gradle in Gradle.

Figure 2-10. Layout of the examples repository (hosted on GitHub)

As you can see in Figure 2-10, each module has the same structure. You can find the test source code in the folder src/test/java. I use Java packages to divide the examples per chapter (e.g., io.github.bonigarcia.webdriver.junit4.ch2.skeletons). Then, each project needs its own Logback configuration file. Although these subprojects do not contain application logic (only tests), I use the general configuration file (i.e., logback.xml) placed under the folder src/main/resources. I follow this convention since it is quite usual to use logging also for the application, and in case you plan to reuse this project structure, this is the standard approach. Finally, at the root of each subproject, you can find the specific configuration file for Maven (pom.xml) and Gradle (build.gradle). In these files, you can find the declaration for the dependencies, as explained below.

Common Setup

Example 2-10 contains the common part of the Maven configuration.

<properties>
    <java.version>11</java.version> 
    <maven.compiler.target>${java.version}</maven.compiler.target>
    <maven.compiler.source>${java.version}</maven.compiler.source>
</properties>

<dependencies> 
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>${slf4j.version}</version>
    </dependency>
    <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>${logback.version}</version>
    </dependency>

    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>${selenium.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>org.assertj</groupId>
        <artifactId>assertj-core</artifactId>
        <version>${assertj.version}</version>
        <scope>test</scope>
    </dependency>
    <dependency>
        <groupId>io.github.bonigarcia</groupId>
        <artifactId>webdrivermanager</artifactId>
        <version>${wdm.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

The Java version for this project (11 in this case).

The common dependencies. On the one hand, we declare Selenium WebDriver, AssertJ, and WebDriverManager using the test scope. This way, we can use these dependencies only from the test logic (i.e., Java classes under the src/test/java folder). On the other hand, the scope of SLF4J and Logback is missing, and therefore, Maven uses the default one, which is compile. This fact means we can use these dependencies both from the application and the test logic. Finally, notice we use Maven properties to declare the dependencies versions (e.g., ${selenium.version}). You can find the precise version in the online repository.

JUnit 4

In a Maven project using JUnit 4 as the unit testing framework, we need to declare also the following dependency:

<dependency>
    <groupId>junit</groupId>
    <artifactId>junit</artifactId>
    <version>${junit4.version}</version>
    <scope>test</scope>
</dependency>

JUnit 5

Although JUnit 5 is a modular framework, we can declare a single dependency to use the Jupiter programming model in a Maven project. As you can see in ???, this artifact is called junit-jupiter, and it transitively pulls the following JUnit 5’s artifacts:

• junit-jupiter-api: For developing tests.

• junit-jupiter-engine: For executing tests in the JUnit Platform.

• junit-jupiter-params: For developing parameterized tests (see Chapter 4).

Besides, we need to declare a specific version of maven-surefire-plugin. As explained in Table 2-7, the version used for this plugin is defined internally by Maven. In Maven 3.x, this version is not compatible with JUnit 5, and therefore, we need to specify a newer version, as you can see next.

<dependencies>
    <dependency>
        <groupId>org.junit.jupiter</groupId>
        <artifactId>junit-jupiter</artifactId>
        <version>${junit5.version}</version>
        <scope>test</scope>
    </dependency>
</dependencies>

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-surefire-plugin</artifactId>
            <version>${maven-surefire-plugin.version}</version>
        </plugin>
    </plugins>
</build>

JUnit 5 with Selenium-Jupiter

When using Jupiter in conjunction with Selenium-Jupiter, in addition to the previous artifacts (junit-jupiter and maven-surefire-plugin), we need to include the coordinates of Selenium-Jupiter (see below). In this case, we can remove the coordinates of WebDriverManager since Selenium-Jupiter transitively pulls it.

<dependency>
    <groupId>io.github.bonigarcia</groupId>
    <artifactId>selenium-jupiter</artifactId>
    <version>${selenium-jupiter.version}</version>
    <scope>test</scope>
</dependency>

TestNG

Finally, the coordinates we need to include in our pom.xml to use TestNG are the following:

<dependency>
    <groupId>org.testng</groupId>
    <artifactId>testng</artifactId>
    <version>${testng.version}</version>
    <scope>test</scope>
</dependency>

JUnit 4

The specific dependency for JUnit 4 is the following:

dependencies {
    testImplementation("junit:junit:${junit4Version}")
}

JUnit 5

When using JUnit 5, we need to specify the junit-jupiter artifact (like in Maven, it depends on junit-jupiter-api junit-jupiter-engine, and junit-jupiter-params). In addition, the need to select the JUnit Platform for executing by using the clause useJUnitPlatform() in the test task setup.

test {
    useJUnitPlatform()
}

dependencies {
    testImplementation("org.junit.jupiter:junit-jupiter:${junit5Version}")
}

JUnit 5 with Selenium-Jupiter

If we use Selenium-Jupiter, in addition to the previous configuration for JUnit 5, we need to include the following dependency. In this case, we can remove WebDriverManager since it is pulled transitively by Selenium-Jupiter.

dependencies {
    testImplementation("io.github.bonigarcia:selenium-jupiter:${selJupVersion}")
}

TestNG

Finally, for using TestNG as the unit testing framework, we need to include the following dependency:

dependencies {
    testImplementation("org.testng:testng:${testNgVersion}")
}

Legacy Browsers

Although not recommended, it is possible to drive legacy browsers (such as Internet Explorer, PhantomJS, and HtmlUnit) with Selenium WebDriver. The following table summarizes the Java system properties (for manual driver management), the WebDriverManager calls (for automatic driver management), and the required dependencies (if any) to use these legacy browsers.