Upgrade to Selenium 4

Selenium 4 uses the W3C WebDriver standard. This mainly affects capabilities and the actions class. The Selenium 4 documentation at www.selenium.dev has all the details.

Upgrading to Selenium 4 from an earlier version of Selenium requires changes to the dependencies in your test project's pom.xml file and to your test scripts. This article provides detailed instructions, including some Perfecto-specific changes.

We suggest that you start by watching the video, which explains how to use Selenium 4 for desktop web testing, and then read through the procedures for step-by-step instructions.

Tip: You can download the tests used in the video by clicking here. To use those tests, edit them to include your security token and cloud name.

Prerequisites

For desktop web testing, make sure you work with:

  • Selenium 4.0.0 or later

For testing on real mobile devices, make sure you work with:

  • Selenium 4.4.0 or later

  • Appium Java client 8.1.1 or later

Upgrade dependencies

The pom.xml file handles all of your project's dependencies. This is where you need to update the Selenium version.

To update the pom.xml file:

  1. Open your project's pom.xml file.

  2. For the following dependencies, change the Selenium version to 4.x.x. For example:

    Copy 
    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-java</artifactId>
        <version>4.0.0></version
    <dependency>
    <dependency>
        <groupId>org.seleniumhq.selenium</groupId>
        <artifactId>selenium-api</artifactId>
        <version>4.0.0></version
    <dependency>

  3. (Optional) Change the version of the Appium Java client to 8.x. For example:

    Copy 
    <dependency>
        <groupId>io.appium</groupId>
        <artifactId>java-client</artifactId>
        <version>8.1.0></version
    <dependency>

  4. Save your file.

Update the test scripts

In Selenium 4, DesiredCapabilities and capabilities.setCapability have changed. You need to update your test scripts accordingly. The changes slightly differ for each browser, operating system version, or mobile device.

Important: These instructions do not include changes for Mozilla Firefox and Google Chrome on MacOS.

To view the steps, expand the relevant section.

  1. In your Windows test scripts:

    • Change Desired.Capabilities depending on the browser.

      Browser

      Old notation

      New notation

      Chrome
      Copy 
      DesiredCapabilities capabilities = new DesiredCapabilities();
      Copy 
      ChromeOptions browserOptions = new ChromeOptions();

      Firefox
      Copy 
      FirefoxOptions browserOptions = new FirefoxOptions();

      Edge
      Copy 
      EdgeOptions browserOptions = new EdgeOptions();

    • Add browserOptions. There is a 1:1 ratio between capabilities.setCapability and browserOptions.set<option-name>. The following table provides an example.

      Old notation

      New notation
      Copy 
      capabilities.setCapability("platformName", "Windows");
      capabilities.setCapability("browserName", "Chrome");
      Copy 
      browserOptions.setPlatformName("Windows");
      browserOptions.setBrowserVersion("latest");

    • For capabilities that are not included in this Selenium-specified list, add the vendor prefix perfectoOptions. Any Perfecto-built function for browser- or cloud-specific parameters requires this notation.

      The following table provides an example.

      Old notation

      New notation
      Copy 
      capabilities.setCapability("platformVersion", "11");
      capabilities.setCapability("resolution", "1920x1080");
      capabilities.setCapability("securityToken", "<your-token>");
      capabilities.setCapability("scriptName", "Windows-Chrome-Webtest");
      Copy 
      perfectoOptions.put("platformVersion", "11");
      perfectoOptions.put("resolution", "1920x1080");
      perfectoOptions.put("securityToken", "<your-token");
      perfectoOptions.put("scriptName", "Windows-Chrome-Webtest-S4");
      browserOptions.setCapability("perfecto:options", perfectoOptions);

    • For Egde, you also need to specify the browser name, as shown in the following code snippet. This is necessary because unlike the other capabilities, EdgeOptions tries to pass the browserName as MicrosoftEdge, which is not supported in Perfecto. Perfecto expects the value Edge. By adding this additional line, you override the default value passed on by Selenium.

      Copy 
      perfectoOptions.put("browserName", "Edge");

  1. In your MacOS test scripts:

    • Change Desired.Capabilities for Safari.

      Old notation

      New notation
      Copy 
      DesiredCapabilities capabilities = new DesiredCapabilities();
      Copy 
      SafariOptions browserOptions = new SafariOptions();

    • Add browserOptions. There is a 1:1 ratio between capabilities.setCapability and browserOptions.set<option-name>. The following table provides an example.

      Old notation

      New notation
      Copy 
      capabilities.setCapability("platformName", "MAC");
      capabilities.setCapability("browserName", "Safari");
      Copy 
      browserOptions.setPlatformName("MAC");
      browserOptions.setBrowserVersion("15");

    • For capabilities that are not included in this Selenium-specified list, add the vendor prefix perfectoOptions. Any Perfecto-built function for browser- or cloud-specific parameters requires this notation.

      The following table provides an example.

      Old notation

      New notation
      Copy 
      capabilities.setCapability("platformVersion", "macOS Monterey");
      capabilities.setCapability("resolution", "1440x900");
      capabilities.setCapability("securityToken", "<your-token>");
      capabilities.setCapability("scriptName", "MAC-Monterey-Webtest");
      Copy 
      perfectoOptions.put("platformVersion", "macOS Monterey");
      perfectoOptions.put("resolution", "1440x900");
      perfectoOptions.put("securityToken", "<your-token");
      perfectoOptions.put("scriptName", "MAC-Monterey-Webtest-S4");
      browserOptions.setCapability("perfecto:options", perfectoOptions);

    • For Safari, you also need to specify the browser name, as shown in the following code snippet. Without this declaration, you may get an 'Invalid capability" message.

      Copy 
      perfectoOptions.put("browserName", "Safari");

  1. In your iOS test scripts:

    • Change Desired.Capabilities for XCUITest.

      Old notation

      New notation
      Copy 
      DesiredCapabilities capabilities = new DesiredCapabilities();
      Copy 
      XCUITESTOptions xcuiTestOptions = new XCUITestOptions();

    • Add xcuiTestOptions. There is a 1:1 ratio between capabilities.setCapability and xcuiTestOptions.setCapability<option-name>. The following table provides an example.

      Old notation

      New notation
      Copy 
      capabilities.setCapability("platformName", "ios");
      Copy 
      xcuiTestOptions.setCapability("platformName", "ios");

    • For capabilities that are not included in this Selenium-specified list, add the vendor prefix perfectoOptions. Any Perfecto-built function for device- or cloud-specific parameters requires this notation.

      The following table provides an example.

      Old notation

      New notation
      Copy 
      capabilities.setCapability("securityToken", "<your-token>");
      capabilities.setCapability("deviceName", "<device-name>");
      capabilities.setCapability("bundleId", "<bundleID>");
      capabilities.setCapability("appiumVersions", "2.0.0");
      capabilities.setCapability("automationVersion", "3.52.0");
      Copy 
      Map<String, Object> perfectoOptions = new HashMap<>();
      perfectoOptions.put("securityToken", SECURITYTOKEN);
      perfectoOptions.put("deviceName", "DEVICENAME");
      //perfectoOptions.put("bundleId", "");
      perfectoOptions.put("appiumVersion", "2.0.0");
      perfectoOptions.put("automationVersion", "3.52.0");        
      xcuiTestOptions.setCapability("perfecto:options", perfectoOptions);

    • Initialize the driver as follows.

      Old notation

      New notation
      Copy 
      IOSDriver driver = new IOSDriver<>(new URL("<cloud-url"), capabilities);
      Copy 
      driver = new IOSDriver(<cloud-url>, xcuiTestOptions);

  1. In your iOS test scripts:

    • Change Desired.Capabilities for UiAutomator2.

      Old notation

      New notation
      Copy 
      DesiredCapabilities capabilities = new DesiredCapabilities();
      Copy 
      UiAutomator2Options uiAutomator2Options = new UiAutomator2Options();

    • Add uiAutomator2Options. There is a 1:1 ratio between capabilities.setCapability and uiAutomator2Options.setCapability<option-name>. The following table provides an example.

      Old notation

      New notation
      Copy 
      capabilities.setCapability("platformName", "android");
      Copy 
      uiAutomator2Options.setCapability("platformName", "android"); 

    • For capabilities that are not included in this Selenium-specified list, add the vendor prefix perfectoOptions. Any Perfecto-built function for device- or cloud-specific parameters requires this notation.

      The following table provides an example.

      Old notation

      New notation
      Copy 
      capabilities.setCapability("securityToken", "<your-token>");
      capabilities.setCapability("deviceName", "<device-name>");
      capabilities.setCapability("appPackage", "<appPackage>");
      capabilities.setCapability("appActivity", "<app-activity>");
      capabilities.setCapability("appiumVersions", "2.0.0");
      capabilities.setCapability("automationVersion", "3.52.0");
      Copy 
      perfectoOptions.put("securityToken", SECURITYTOKEN);
      perfectoOptions.put("deviceName", "DEVICENAME");
      //perfectoOptions.put("appPackage", "");
      //perfectoOptions.put("appActivity", "");
      perfectoOptions.put("appiumVersion", "2.0.0");
      perfectoOptions.put("automationVersion", "3.52.0");
      uiAutomator2Options.setCapability("perfecto:options", perfectoOptions);

    • Initialize the driver as follows.

      Old notation

      New notation
      Copy 
      driver = new AndroidDriver<>(new URL("<cloud-url"), capabilities);
      Copy 
      driver = new AndroidDriver(url, uiAutomator2Options);

Identify Selenium 4 in reports

You can identify a test's execution framework by using the Details option inside the single test report (STR).

To identify the execution framework in a report:

  1. In the Report Library, click the report in the table to open the STR.

  2. In the STR, click the Report Details button .

  3. In the Report Details dialog box, on the Device tab, click Show Desired Capabilities.

  4. Scroll down to verify the seleniumVersion field. It should display a value of 4.0.0.

Related articles