Skip to main content

W3C WebDriver Capabilities Support

Sauce Labs supports and encourages our users to update their code to take advantage of the W3C WebDriver Protocol, which is currently the default protocol used by all major browsers, is fully supported in WebdriverIO 6 and higher, Selenium versions 3.11 and higher, and is required for Selenium 4.0. Using the WebDriver protocol on Sauce Labs requires setting specific capabilities in your code.

note

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

What You'll Need#

W3C WebDriver Protocol Compliance#

To ensure W3C WebDriver compliance:

  • Use Selenium version 3.11 or higher or WebdriverIO 5 or higher.

  • 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 naming differences between legacy JWP and W3C WebDriver-compliant capabilities. 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
    • 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

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.

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:

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

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

Recommended Code (Selenium 4)
FirefoxOptions options = new FirefoxOptions();options.setPlatformName("Windows 10");options.setBrowserVersion("latest");

W3C Sauce Labs Options#

Sauce Labs specific capabilities used to be able to go in the top-level Capabilities. To be W3C-compliant, users must now put Sauce Labs configurations inside a sauce:options key.

Deprecated Code
caps.setCapability("username", "someuser");caps.setCapability("accessKey", "00000000-0000-0000-0000-000000000000");caps.setCapability("name", testName.getMethodName());caps.setCapability("build", getBuildName());caps.setCapability("seleniumVersion", "3.141.59");
Recommended Code (Selenium 4)
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 putting credentials in the URL instead of the options. We currently recommend putting them in the options, so you might want to change your code from the first example here to the second:

Outdated Code
String username = System.getenv("SAUCE_USERNAME");String accessKey = System.getenv("SAUCE_ACCESS_KEY");String sauceUrl = "https://" + username + ":" + accessKey + "@ondemand.saucelabs.com:443/wd/hub";WebDriver driver = new RemoteWebDriver(new URL(sauceUrl), caps);
Recommended Code
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.

Creating Sauce Sessions#

Basic examples of w3c compliant sessions can be created using 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.

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: testName(),  build: buildName(),  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.