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
- A Sauce Labs account (Log in or sign up for a free trial license).
- Your Sauce Labs Username and Access Key.
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
andbrowserVersion
, while JWP usesplatform
andversion
, 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
Browser | W3C Support | JWP Support |
Chrome | 75 and above | Still supported |
Firefox | 60 and above | Still supported |
Safari | 12 and above | Removed in 12.1 |
Edge (Chromium) | All | Still supported |
Internet Explorer | All | Still 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:
- Deprecated Code
- Recommended Code (Selenium 4)
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+.
FirefoxOptions options = new FirefoxOptions();
options.setPlatformName("Windows 10");
options.setBrowserVersion("latest");
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.
- Deprecated Code
- Recommended Code (Selenium 4)
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");
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:
- Outdated Code
- Recommended Code (Selenium 4)
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);
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.
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:
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
- Upgrading to Selenium 4 for Sauce Labs Testing
- Migrating Appium Real Device Tests to W3C
- A Comprehensive Guide to Selenium 4: run compliant tests on every browser
- W3C-Compliant Selenium 4 Code
- Test Configuration Options: Sauce Labs capabilities for Selenium and Appium