Migrating Appium Tests to W3C

As of January 2022, Sauce Labs is incorporating support for the W3C WebDriver specification for real device tests using Appium. Sauce Labs will also update the Chrome version on the Android Emulators, which means the W3C protocol may be required on some Android versions. At this time, Sauce Labs supports both JSON Wire Protocol (JWP) or W3C in all currently supported Appium versions, but when Appium 2.0 becomes available in 2022, it will deprecate support for the JWP, so Sauce Labs advises migrating your tests to W3C to take advantage of the upcoming features and functionality and avert any disruption to your development cycle and testing.  

Do I need to make changes now?

If you need access to Appium features that require the W3C protocol or want to prepare for Appium 2.0 then yes, you should start using the W3C protocol. Your Appium tests may already use the W3C protocol for Android Emulator and iOS Simulator tests, so this change would just bring W3C to all tests.

If you are not aware of any specific Appium features that require W3C then you are safe to continue using the JWP protocol you're already using. Until Appium 2.0 is released JWP should be supported by Appium.

Differences between JWP and W3C

The main difference between JWP and W3C is the format required to specify your test capabilities. In JWP, all capabilities are defined within the desiredCapabilities node, while in W3C, all capabilities are defined under the capabilities node within the firstMatch property. Each capability uses a namespace to indicate one of the following three categorizations:

• WebDriver standard capabilities have no namespace
• Appium specific capabilities require the prefix appium:
• Sauce Labs custom capabilities are set within the sauce:options node. 

The following table illustrates this difference in the respective specifications.

"desiredCapabilities": {
    "platformName": "android";
    "app": "./apps/mda-1.0.6-8.apk";
    “deviceName": "Samsung.*Galaxy.*”;
    “orientation”: “PORTRAIT”;
    “platformVersion": "8.1";
    "appiumVersion": "1.21.0";
 }

"capabilities": {
    "firstMatch": [
      {
        "platformName": "android",                    #standard capability
        "appium:app": "./apps/mda-1.0.6-8.apk";       #Appium capabilities
        “appium:deviceName": "Samsung.*Galaxy.*”;
        “appium:orientation”: “PORTRAIT”;
        “appium:platformVersion": "8.1";
        "sauce:options": {                           #Sauce custom capabilities
           "appiumVersion": "1.21.0";
           "sessionCreationRetry": "2",
           "sessionCreationTimeout": "300000",
           "name": "MobileWebsiteTest (w3c)"
        }
      }
    ]
}

NOTE: You can avoid having to add the `appium:` prefix to Appium specific capabilities by upgrading your Appium client library to a version that automatically applies the prefix or installing the relaxed-caps plugin.

Application on Sauce Labs

When Sauce Labs executes your test configuration, it looks for the presence of certain indicators in the session creation request to determine whether it should apply the JWT or W3C protocol. The following table shows how Sauce Labs determines which protocol to use.

We have implemented this flexibility to allow customers to control their transition to the new protocol, but it is important to make sure your capabilities don’t contradict one another and cause the wrong protocol to be applied.

What you need to look out for

The following examples highlight two examples where the capabilities configuration may cause unintended contradiction. Sauce Labs recommends that you do not have both JWT and W3C protocols within the same test specification, but if your transition from JWT to W3C requires it, make sure you are clearly designating which protocol to use.

desiredCapabilities + Empty sauce:options

The following code sample sets the Sauce Labs custom settings in JWT format (desiredCapabilities), but also includes the W3C sauce:options node with no settings. In this case, Sauce Labs ignores the settings in desiredCapabilities because the presence of sauce:options defaults to W3C, which has no settings, so none will be configured, which is likely not the intended scenario.

{
  "desiredCapabilities": {
    "name": "MobileWebsiteTest (w3c)",
    "testobject_session_creation_timeout": "300000",
    "platformName": "Android",
    "testobject_session_creation_retry": "2"
  },
  "capabilities": {
    "firstMatch": [
      {
        "platformName": "android",
        "sauce:options": { }
      }
    ]
  }
}

Mixed Protocol Capabilities

This code sample shows configuration for both JWP and W3C populated with the same capabilities. Again, since the sauce:options  node is present, W3C is used for the test.

{
  "desiredCapabilities": {
    "name": "MobileWebsiteTest (w3c)",
    "testobject_session_creation_timeout": "300000",
    "platformName": "Android",
    "testobject_session_creation_retry": "2"
  },
  "capabilities": {
    "firstMatch": [
      {
        "platformName": "android",
        "sauce:options": {
          "sessionCreationRetry": "2",
          "sessionCreationTimeout": "300000",
          "name": "MobileWebsiteTest (w3c)"
        }
      }
    ]
  }
}

No sauce:options

The following code sample again shows configuration for both JWP and W3C populated with the same capabilities, except the sauce:options  node is omitted, so JWP is used for the test.

{
  "desiredCapabilities": {
    "name": "MobileWebsiteTest (w3c)",
    "testobject_session_creation_timeout": "300000",
    "platformName": "Android",
    "testobject_session_creation_retry": "2"
  },
  "capabilities": {
    "firstMatch": [
      {
        "platformName": "android"
        "sessionCreationRetry": "2",
        "sessionCreationTimeout": "300000",
        "name": "MobileWebsiteTest (w3c)
      }
    ]
  }
}

sauce:options within the desiredCapabilities node

The capabilities given in the sauce:options node will be ignored. In this example no Sauce Connect tunnel will be initiated for the test. What you need to do is move the nested capabilities out of the sauce:options node and delete the sauce:options.

{
  "desiredCapabilities": {
    "name": "MobileWebsiteTest (w3c)",
    "testobject_session_creation_timeout": "300000",
    "platformName": "Android",
     "sauce:options": {
         "tunnelIdentifier": "sc-proxy-tunnel"
	},
    "testobject_session_creation_retry": "2"
}

Supported capabilities

The following table provides a list of the most commonly used capabilities in Sauce Labs device testing and identifies each as  Standard, Appium, or Sauce to help you accurately configure them in your tests. More details and examples for each of these capabilities is available on the Test Configuration Options documentation page.

Deprecated JWP capabilities

These are capabilities that are supported by the JWP protocol but are no longer available when using W3C.