Skip to main content

W3C WebDriver Capabilities Support

Sauce Labs now supports the W3C WebDriver-compliant capabilities and protocol featured in Selenium versions 3.11 and higher. This doc will help ensure that your tests are W3C WebDriver-compliant and can successfully execute on Sauce Labs.

We early adopted the W3C WebDriver specification when it achieved the W3C standard level as the automation protocol for web browsers. As browser vendors update to support W3C WebDriver protocol and shift away from JSON Wire Protocol (JWP), this can bring increased stability in your Selenium tests across different browsers. It’s important to update your tests accordingly.

note

Some extended capabilities are not backwards-compatible with Selenium versions below 4.0.

What You'll Need#

To ensure W3C WebDriver compliance:

  • Use Selenium version 3.11 or higher.

  • Switch from using JWP (legacy) to the newer W3C WebDriver Protocol. Mixing JWP with W3C will result in an error.

  • Learn the name changes effective with the W3C protocol capabilities. For example, W3C uses platformName, while JWP uses platform. W3C uses browserVersion, while JWP uses version. We recommend reviewing our Test Configuration Options and the official W3C Recommendations website.

  • Include our custom sauce:options W3C WebDriver-compliant capabilities in your Sauce Labs test scripts.

    Click here to see the full list of sauce:options capabilities. See Test Configuration Options for guidance on which are required and optional.
    • accessKey
    • appiumVersion
    • avoidProxy
    • build
    • captureHtml
    • chromedriverVersion
    • commandTimeout
    • crmuxdriverVersion
    • customData
    • disablePopupHandler
    • extendedDebugging
    • firefoxAdapterVersion
    • firefoxProfileUrl
    • idleTimeout
    • iedriverVersion
    • maxDuration
    • name
    • parentTunnel
    • passed
    • prerun
    • preventRequeue
    • priority
    • proxyHost
    • public
    • recordLogs
    • recordScreenshots
    • recordVideo
    • restrictedPublicInfo
    • screenResolution
    • seleniumVersion
    • source
    • tags
    • timeZone
    • tunnelIdentifier
    • username
    • videoUploadOnPass
    Click here to see an example code snippet containing sauce:options capabilities.
      browserName: 'firefox',  platformName: 'macOS 10.15',  browserVersion: 'latest'  sauce:options: {    name: 'My test name',    build: 'My build',    username: "SAUCE_USERNAME",    accessKey: "SAUCE_ACCESS_KEY"    seleniumVersion: "3.141.59"  }

W3C WebDriver Protocol Compliance#

Sauce Labs WebDriver Protocol Support#

BrowserW3C SupportJWP Support
Chrome75 and aboveStill supported
Firefox55 and aboveStill supported
Safari12 and aboveRemoved in 12.1
EdgeAllStill supported
Internet ExplorerAllStill supported

Browser Compatibility#

The following browser versions are compatible with the W3C WebDriver protocol:

  • Firefox version 53 and above.
  • Chrome version 61 and above.
  • Internet Explorer 11.

By default, Sauce Labs uses older versions of Firefox, IE, and Safari. This is important to know since newer commands and configurations may not be supported in those versions.

chromeOptions()#

For tests on Chrome versions 74 and lower, the chromeOptions() W3C WebDriver capability must be set as an experimental option. ChromeDriver version 75 runs in W3C WebDriver standard compliant mode by default, so setting this capability won't be necessary in the future.

w3c must be set as a boolean value (e.g., true in Java and True in Python) – not a string (e.g., "true"). Example:

ChromeOptions chOpts = new ChromeOptions();chOpts.setExperimentalOption("w3c", true);

Verifying Your Tests for Compliance#

To confirm that your Sauce Labs tests are adhering the new W3C WebDriver protocol:

  1. Go to Test Details and click on the line item for your test.
  2. Click the Commands tab.
  3. Click the POST /session command to expand its details.
  4. Go the PARAMETERS section and check the capabilities that were used in your test. If the code begins with capabilities, you're running the new W3C WebDriver-compliant protocol. If it begins with desiredCapabilities, you're running the legacy, non-W3C WebDriver protocol.Check W3C compliance in your test results

Language Changes in Selenium 3.11+#

There are some changes to specific Selenium language bindings you should be aware of when migrating to the W3C WebDriver protocol.

W3C DriverOptions()#

When using Selenium versions 3.11 and above, we recommend inputting the W3C WebDriver-compliant DriverOptions() class, which is used to manage options specific to each browser web driver. Below are some examples.

FireFoxOptions mozOpts = new FirefoxOptions();

W3C MutableCapabilities()#

We recommend setting your capabilities using the W3C Webdriver-compliant MutableCapabilities() class over the legacy DesiredCapabilities().

MutableCapabilities() implements all interfaces, including DriverOptions() and DesiredCapabilities(). Examples:

MutableCapabilities sauceCaps = new MutableCapabilities();sauceCaps.setCapability("username", "someuser");sauceCaps.setCapability("accessKey", "00000000-0000-0000-0000-000000000000");sauceCaps.setCapability("name", "my test case");
MutableCapabilities caps = new MutableCapabilities();caps.setCapability("sauce:options", sauceCaps);caps.setCapability("platformName", "Windows 10");caps.setCapability("browserName", "firefox");caps.setCapability("browserVersion", "latest");
WebDriver driver = new RemoteWebDriver(new URL("https://ondemand.saucelabs.com/wd/hub"), caps);

For more information, see the DriverOptions class Selenium documentation.

tip

Use our Platform Configurator to autogenerate the W3C capabilities needed to run a test on your local environment.

Instantiating WebDriver#

To instantiate WebDriver with W3C WebDriver-compliant capabilities, select a code snippet below in the programming language of your choice and then follow the instructions. You can find more sample code in our GitHub training repository.

TestNG Example Walkthrough#

  1. Ensure you have the prerequisite software to run a Java test on Sauce.

  2. Download or clone one of the below example test scripts from our GitHub repo:

    Click here to see an example TestNG test script.
    TestNG Example
    loading...

  3. Resolve any dependencies:

    $ mvn dependency:resolve

  4. Export your Sauce Labs Username and Access Key:

    export SAUCE_USERNAME=my-sauce-usernameexport SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx

  5. Run the following command:

    $ mvn clean test -Dtest=TestNGW3CChromeTest

JUnit 5 Example Walkthrough

  1. Ensure you have the prerequisite software to run a Java test on Sauce.

  2. Download or clone the below example test script from our GitHub repo:

    Click here to see the JUnit Jupiter example test script.
    JUnit 5 Example
    loading...

  3. Resolve any dependencies:

    $ mvn dependency:resolve

  4. Export your Sauce Labs Username and Access Key:

    export SAUCE_USERNAME=my-sauce-usernameexport SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx

  5. Run the following command:

    $ mvn clean test -Dtest=JUnit5W3CChromeTest

Quickstart#

Below are mobile and web test script examples you can use to get up and running quickly in JavaScript:

Desktop Web Example
loading...

Common Errors#

W3C WebDriver-compliant capabilities and JWP Capabilities are not compatible. Using both in the same test script will result in a system error when spinning up a WebDriver session:

Mixed Capabilities Error
selenium.common.exceptions.WebDriverException: Message: Misconfigured -- Mixed Capabilities Error.
W3C keys (platformName/browserVersion) were detected alongside JWP keys (platform/version). To fix this, replace all JWP keys with W3C keys.
The following desired capabilities were received:{'browserName': 'chrome', 'browserVersion': '80', 'platform': 'Windows'}

Solution:

  1. Change platform to platformName.
  2. Change version to browserVersion.
browserName: 'chrome',platformName: 'Windows',browserVersion: '80'sauce:options: {  name: 'My test name',  build: 'My build',  username: "SAUCE_USERNAME",  accessKey: "SAUCE_ACCESS_KEY"  seleniumVersion: "3.141.59"}

Additional Resources#

© 2021 Sauce Labs Inc., all rights reserved. SAUCE and SAUCE LABS are registered trademarks owned by Sauce Labs Inc. in the United States, EU, and may be registered in other jurisdictions.