Skip to main content

W3C WebDriver Capabilities Support

Sauce Labs supports and encourages updating your code to take advantage of the W3C WebDriver Protocol, which is currently the default protocol used by all major browsers. W3C is fully supported in WebdriverIO 6 and higher, Selenium versions 3.11 and higher, Appium 1.6.5 and higher, and is required for Selenium 4.0 and Appium 2.0 (in beta).

Using the W3C WebDriver protocol on Sauce Labs requires setting specific capabilities in your code. The syntax is different from its predecessor, JSON Wire Protocol (JWP).

What You'll Need​

W3C WebDriver-Compliant Protocol​

To ensure W3C WebDriver compatibility:

  • Use Selenium version 3.11 or higher, WebdriverIO 6 or higher, or an Appium client that supports W3C.

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

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

  • Learn the differences between legacy JWP and W3C WebDriver-compliant capability syntax. For example, W3C uses platformName and browserVersion, while JWP uses platform and version, respectively. 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
    • tunnelName
    • tunnelOwner
    • username
    • videoUploadOnPass

Browser Compatibility​

BrowserW3C SupportJWP Support
Chrome75 and aboveStill supported
Firefox60 and aboveStill supported
Safari12 and aboveRemoved in 12.1
Edge (Chromium)AllStill supported
Internet ExplorerAllStill supported

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.

Selenium Browser Options​

At one point, Selenium tried to differentiate between "Required Capabilities" and "Desired Capabilities", but everyone essentially used "Desired Capabilities" as if they were required, and this caused confusion. Selenium has moved away from this syntax to Browser Options syntax. Using the provided methods available on the Browser Options classes will make it easier to ensure you are getting the session you expect.

Browser Options classes are used to manage both browser specific functionality as well as top-level W3C defined commands.

Here is a comparison of deprecated Java code that needs to be replaced with recommended code:

DesiredCapabilities caps = new DesiredCapabilities.firefox();
caps.setCapability("platform", "Windows 10");
caps.setCapability("version", "latest");
note

This deprecated code is no longer available in Selenium 4.0+.

Writing W3C Sauce Labs Sessions​

You can generate basic code snippets for W3C-compliant sessions using the Sauce Labs Platform Configurator in the Selenium 4 or Selenium 3 tabs. Complete code examples for starting a Sauce Labs Session can be found in our Selenium Documentation.

note

WebdriverIO has been W3C-compliant by default since v5.0.

Use sauce:options​

To be W3C-compliant, you'll need to put your Sauce-specific configurations inside of a sauce:options key, whereas with JWP they were added to the top-level capabilities.

Map<String, Object> sauceOptions = new HashMap<>();
sauceOptions.put("username", System.getenv("SAUCE_USERNAME"));
sauceOptions.put("accessKey", System.getenv("SAUCE_ACCESS_KEY"));
sauceOptions.put("name", testInfo.getDisplayName());
sauceOptions.put("build", getBuildName());
sauceOptions.put("seleniumVersion", "4.0.0");

caps.setCapability("sauce:options", sauceOptions);

Many early Sauce Labs examples show credentials being defined in the sauceUrl instead of the options. We currently recommend putting your credentials in sauce:options - as described in the previous example - and just use sauceUrl to define your Sauce Labs Data Center:

URL sauceUrl = "https://ondemand.us-west-1.saucelabs.com/wd/hub";
WebDriver driver = new RemoteWebDriver(new URL(sauceUrl), caps);
note

Your endpoint URL will depend on which Sauce Labs Data Center you are using.

Test Compatibility​

To confirm that your Sauce Labs tests are adhering to W3C WebDriver protocol, go to Automated > Test Results > Click on your test > METADATA tab > Look for WebDriver Protocol: W3C.
Mobile

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

In this example, you'd need to change platform to platformName and change version to browserVersion.

browserName: 'chrome',
platformName: 'Windows',
browserVersion: '80'
sauce:options: {
  name: testName(),
  build: buildName(),
  username: "SAUCE_USERNAME",
  accessKey: "SAUCE_ACCESS_KEY"
  seleniumVersion: "3.141.59"
}

Additional Resources​