Sauce Labs now supports the W3C WebDriver-compliant capabilities and protocol featured in Selenium versions 3.11 and higher. Please note that some extended capabilities are not backwards-compatible with versions prior to 4.0. This article 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 and shift away from JSON Wire Protocol (JWP), it’s important to update your tests accordingly.

See the following sections for more information:

Sauce Labs Web Protocol Support

BrowserW3C SupportJWP Support
Chrome75 and aboveStill supported
Firefox

55 and above

Still supported
Safari12 and aboveRemoved in 12.1
EdgeAllStill supported
Internet ExplorerAllStill supported

What You'll Need

To ensure W3C WebDriver compliance, you'll need to:

Getting Started

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


W3C WebDriver Browser Compatibility

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

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

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

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

Verifying Capabilities for W3C WebDriver Compliance

Here's how to verify if your tests are running under the new W3C WebDriver protocol:

  1. Go to the Test Details page for your test in Sauce Labs.
  2. Click the Commands tab.
  3. Select the first Post command, which will be Post /session.
  4. Under the Parameters section, check the capabilities that are used in the test. 

W3C WebDriver-Compliant 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. Here is an example:

In Selenium version 3.11 and higher, be sure to input the new DriverOptions() class, which is used to manage options specific to each browser web driver.

Example: Selenium 3.11+, with DriverOptions() (tick)

FireFoxOptions mozOpts = new FirefoxOptions();

Example: Legacy, with DesiredCapabilities() (error)

DesiredCapabilities caps = new DesiredCapabilities.firefox();

Using legacy formatting in Selenium 3.11+ script will yield the following message:

"INFO: Using `new FirefoxOptions()` is preferred to `DesiredCapabilities.firefox()"

You can now set capabilities using the MutableCapabilities() class instead of using DesiredCapabilities().

MutableCapabilities() is the preferred method; it implements all interfaces, including DriverOptions() and DesiredCapabilities(). For more information, see the DriverOptions class Selenium documentation.

These two Java snippets show a comparison between a legacy script and a version edited to use the new W3C WebDriver capabilities:

Example: Selenium 3.11+, with MutableCapabilities() (tick)

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

Example: Legacy, with DesiredCapabilities() (error)

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

Instantiating WebDriver with W3C WebDriver-Compliant Capabilities

Select a code snippet below in the programming language of your choice, then follow the instructions. You can find more sample code in the Sauce Labs training repository on GitHub.


TestNG Example Walkthrough

  1. Download or clone the script from GitHub.

  2. Ensure you have the prerequisite software.

  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. Download or clone the script from this GitHub repository.

  2. Ensure you have the prerequisite software.

  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

PyTest Example Walkthrough

  1. Download or clone the script from the Sauce Labs GitHub repository.
  2. Ensure you have the prerequisite software.
  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. Download or clone the script from the Sauce Labs GitHub repository.
  2. Ensure you have the prerequisite software.
  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 commands:

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

WebdriverIO Example Walkthrough

  1. Download or clone the script from this GitHub repository.

  2. Ensure you have the prerequisite software.

  3. Ins$tall 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

    You should see the following output (or something similar) in the console:

     mocha "test/async-await-test.js"
    
    
    
      headless chrome test
    Page Title is: Swag Labs
        ✓ get-title-test (2594ms)
    
    
      1 passing (13s)                                                              

Rspec Example Walkthrough

  1. Download or clone the script from the Sauce Labs GitHub repository.

  2. Ensure you have the prerequisite software.

  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

NUnit Example Walkthrough

  1. Download or clone the script from the Sauce Labs GitHub repository.
  2. Ensure you have the prerequisite software.
  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.

Common Test Script Configuration Errors to Avoid

Here are some things to keep in mind when configuring your test script capabilities.

Don't Mix W3C Capabilities with JWP Capabilities

It's important not to mix W3C WebDriver-compliant capabilities with legacy JWP capabilities. This will result in a system error when you're spinning up a WebDriver session:

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'} 

See https://wiki.saucelabs.com/display/docs/w3c+capabilities+support for more details.


To fix this particular error, you'd need to change platform to platformName and then 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