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, the following steps are required:

• Use Selenium version 3.11 or higher.

• Switch completely from using the older JWP to the newer W3C 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 (e.g., name, build) in your Sauce Labs test scripts.

  • Here's an example:
    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"

    }
  Click here to see a full list of sauce:options capabilities.

  • 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

Sauce Labs Web Protocol Support

Browser	W3C Support	JWP Support
Chrome	75 and above	Still supported
Firefox	55 and above	Still supported
Safari	12 and above	Removed in 12.1
Edge	All	Still supported
Internet Explorer	All	Still supported

W3C WebDriver Compliance

Browser Compatibility

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

• Firefox version 53 and higher.
• Google Chrome version 61 and higher.
• 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 Google 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.

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 version 3.11 or higher, 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.

W3C DriverOptions()

FireFoxOptions mozOpts = new FirefoxOptions();

JWP DesiredCapabilities()

DesiredCapabilities caps = new DesiredCapabilities.firefox();

NOTE: Using JWP legacy formatting in a Selenium 3.11+ script, like in the example above, will yield the following message:

"INFO: Using `new FirefoxOptions()` is preferred

to `DesiredCapabilities.firefox()"

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(). Below are some examples.

For more information, see the DriverOptions class Selenium documentation.

W3C MutableCapabilities()

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);

JWP DesiredCapabilities()

DesiredCapabilities caps = new DesiredCapabilities();

caps.setCapability("username", "someuser");

caps.setCapability("accessKey", "00000000-0000-0000-0000-000000000000");

caps.setCapability("name", "my test case");

caps.setCapability("browser", "firefox");

caps.setCapability("platform", "Windows 10");

caps.setCapability("version", "latest");

WebDriver driver = new RemoteWebDriver(new URL("https://ondemand.saucelabs.com/wd/hub"), caps);

NOTE: Using JWP legacy formatting in a Selenium 3.11+ script, like in the example above, will yield the following message:

"INFO: Using `new FirefoxOptions()` is preferred

to `DesiredCapabilities.firefox()"

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.

Java

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.

   java/testng/W3CChromeTest.java

   loading...

   See full example on GitHub

3. Resolve any dependencies:

   $ mvn dependency:resolve

4. Export your Sauce Labs Username and Access Key:

   export SAUCE_USERNAME=my-sauce-username

   export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx

5. Run the following command:

   $ mvn clean test -Dtest=TestNGW3CChromeTest

JUnit Jupiter 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.

   java/junit5/W3CChromeTest.java

   loading...

   See full example on GitHub

3. Resolve any dependencies:

   $ mvn dependency:resolve

4. Export your Sauce Labs Username and Access Key:

   export SAUCE_USERNAME=my-sauce-username

   export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxxx

5. Run the following command:

   $ mvn clean test -Dtest=JUnit5W3CChromeTest

Python

PyTest Example Walkthrough

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

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

   Click here to see an example PyTest test script.

   python/test_pytest_chrome.py

   loading...

   See full example on GitHub

3. Resolve any dependencies:

   $ pip install -r w3c-examples/requirements.txt

4. Export your Sauce Labs Username and Access Key:

   export SAUCE_USERNAME=my-sauce-username

   export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4

5. Run the following command:

   $ pytest w3c-examples/pytest/*.py

unittest Example Walkthrough

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

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

   Click here to see an example unittest test script.

   python/test_unittest_chrome.py

   loading...

   See full example on GitHub

3. Install any dependencies:

   $ pip install -r w3c-examples/requirements.txt

4. Export your Sauce Labs Username and Access Key:

   export SAUCE_USERNAME=my-sauce-username

   export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4

5. Run the following command:

   $ python -m unittest w3c-examples/unittest/*.py

NodeJS

WebdriverIO Example Walkthrough

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

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

   Click here to see an example WebdriverIO test script.

   webdriverio/webdriver/examples/w3c/test/configs/wdio.saucelabs.conf.js

   loading...

   See full example on GitHub

3. Install node package dependencies:

   $ npm --prefix ./w3c-example install ./w3c-example

4. Export your Sauce Labs Username and Access Key:

   export SAUCE_USERNAME=my-sauce-username

   export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4

5. Run the following command:

   $ npm --prefix ./w3c-example test

Ruby

Rspec Example Walkthrough

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

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

   Click here to see an example Ruby test script.

   ruby/rspec/chrome_example_spec.rb

   loading...

   See full example on GitHub

3. Install gemfile/package dependencies:

   $ gem install bundler

   $ bundle init

   $ bundle install --path .bundle

4. Export your Sauce Labs Username and Access Key:

   export SAUCE_USERNAME=my-sauce-username

   export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4

5. Run the following command:

   $ bundle exec rspec

C#

NUnit Example Walkthrough

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

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

   Click here to see an example C# test script.

   csharp/NUnitExamples.cs

   loading...

   See full example on GitHub

3. In Visual Studio, open the solution.

4. Export your Sauce Labs Username and Access Key:

   export SAUCE_USERNAME=my-sauce-username

   export SAUCE_ACCESS_KEY=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx2cy8f4

5. In Visual Studio Test Explorer, run tests in Selenium3.Nunit.Scripts.SimpleExamples.W3CExamplesOnSelenium3.cs.

Quickstart

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

Desktop Web

webdriverio/webdriver/examples/w3c/test/configs/wdio.saucelabs.conf.js

loading...

See full example on GitHub

Appium Web

webdriverio/appium-web/examples/w3c/test/configs/wdio.saucelabs.conf.js

loading...

See full example on GitHub

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

• Sauce Labs Supports the W3C WebDriver Protocol: run compliant tests on every browser.
• Test Configuration Options: Sauce Labs capabilities for Selenium and Appium.
• Useable code examples for your tests: public GitHub repo with language-specific bindings that leverage our new sauce:options capability.