Skip to main content

Test Configuration Options

This page provides a reference for the valid test configuration options (capabilities) you can set to specify the variable settings for your automated tests running on Sauce Labs.

Try our Sauce Labs Platform Configurator! It provides a graphical user interface where you can specify your settings using option buttons and drop-down menus, then automatically generates the corresponding capabilities code based on your selections. For examples, see Examples of Test Configuration Options for Website Tests.

What You'll Need​

Terminology​

When setting up your test, you'll need to configure your script with settings called capabilities that align with your test environment (e.g., desktop browser, mobile web browser, mobile app). While each environment has its own set of capabilities, they can also be combined. Some are required for a test to run in a given environment, while some are optional.

You'll need to add these configurations to the capabilities or options classes.

  • W3C WebDriver Capabilities: Required for any test using Selenium or Appium to communicate with the browser. W3C WebDriver capabilities are universal capabilities for any test, and are usually combined with additional capabilities. See the official W3C Recommendations website for more information.
  • Sauce Labs Capabilities: Needed for running a test on the Sauce Labs Cloud, with different possible sets for different environments. Though there aren't any capabilities required, you will need to configure the endpoint URL and should pass the test name and status as capabilities to the remote webdriver.
  • Appium Capabilities: Required for tests using Appium on mobile apps and Appium on mobile web browsers.
  • Browser-Specific Capabilities: Optional, browser-specific Sauce Labs capabilities.
  • Browser Vendor Capabilities: Each browser also has its own set of pre-defined options you can set to help you test. You can add these in regular capabilities or options, or use the browser-defined capabilities (browser options classes) to configure your browser tests:

W3C WebDriver Capabilities – Required​

Sauce Labs determines W3C sessions with the presence of sauce:options capabilities and generic W3C WebDriver-compliant capabilities in your code. See W3C Capabilities Support for more information.

Below are the W3C WebDriver primary test configuration settings for Sauce Labs desktop browser tests and mobile tests.

tip

Use the latest version of the Selenium library in your code for the most up-to-date support.

browserName​

| STRING |

Identifies the user agent. See the WebDriver W3C Specification for more information. This setting also applies to emulators, simulators and real devices when automating with a mobile browser. It must be set when App Name is not set.

  • For Android v5 and below, the value needs to be "Browser", v6 and above, it is "Chrome".
  • For iOS, the value needs to be "Safari".
  • For mobile native or hybrid apps, the value needs to be an empty String.
"browserName": "firefox"

browserVersion​

| STRING |

Identifies the version of the browser you want to use in your test. See the WebDriver W3C Specification for more information.

To use the latest stable version of Chrome or Firefox that we support, you can use "browserVersion": "latest". You can also use "browserVersion": "latest-1" or "browserVersion": "latest-2", etc., to request the next most recent versions of a browser.

For example, if the latest stable version of Chrome is 73, you can request "latest-2" to use Chrome 71.Note that the latest version for Safari browsers will depend on the chosen "platformName".

See the Sauce Labs Platform Configurator for valid options.

note

This setting cannot be used for mobile browsers, as your test will use the default browser installed for the given Appium version.

"browserVersion": "latest"

platformName​

| STRING |

Identifies the name of the operating system the browser or mobile device should be running on. You can use this for dynamic device allocation. Values are not case-sensitive (i.e., "ios" is the same as "iOS"). See the WebDriver W3C Specification for more information.

"platformName": "macOS 10.13"

W3C WebDriver Browser Capabilities – Optional​

Optional, Sauce-compatible W3C WebDriver specification capabilities you can add to your tests. To view their descriptions, see the W3C WebDriver Specification Capabilities.

acceptInsecureCerts​

| BOOLEAN |

Indicates whether untrusted and self-signed TLS certificates are implicitly trusted on navigation for the duration of the session. The default value is false. See the WebDriver W3C Specification for more information.

"acceptInsecureCerts": true

pageLoadStrategy​

| STRING |

Defines the current session’s page load strategy. See the WebDriver W3C Specification for more information. For allowed values and their associated required document readiness state, see WebDriver W3C Specification Page Load Strategies Table.

"pageLoadStrategy": "eager"

proxy​

| OBJECT |

Defines the current session’s proxy configuration. See the WebDriver W3C Specification for more information.

"proxy": {"proxyType": "manual",
          "httpProxy": "myproxy.com:3128"}

timeouts​

| OBJECT |

Describes the timeouts imposed on certain session operations. Applicable timeouts can be found on the WebDriver W3C Specification Timeouts Table. See the WebDriver W3C Specification for more information.

"timeouts": {"script": 20000,
             "pageLoad": 400000,
             "implicit": 1000}

strictFileInteractability​

| BOOLEAN |

Defines the current session’s strict file interactability. This indicates that interactabilty checks will be applied to File type input elements. The default is false. See the WebDriver W3C Specification for more information.

"strictFileInteractability": true

unhandledPromptBehavior​

| STRING |

Describes the current session’s user prompt handler. The default value is "dismiss and notify". For a list of the allowed options, see WebDriver W3C Specification User Prompt Handler Table. See the WebDriver W3C Specification for more information.

"unhandledPromptBehavior": "ignore"

webSocketUrl​

| BOOLEAN | Desktop Only | BETA |

Enables W3C WebDriver BiDi support. This allows Selenium 4 clients to use Bi-Directional functionality. It also enables BiDi for other test frameworks, like WebDriverIO. In particular, this capability exposes the WebSocket endpoint which is available under webSocketUrl field in session startup response body. This endpoint can be used to issue WebDriver BiDi commands as described by the specification. The default value is false.

The webSocketUrl capability is not compatible with extendedDebugging capability.

"webSocketUrl": true

Desktop Browser Capabilities: Sauce-Specific – Optional​

Browser-specific optional capabilities you can add to the sauce:options block of your test session creation code.

chromedriverVersion​

| STRING |

Allows you to specify the ChromeDriver version you want to use for your tests. The default version of ChromeDriver when no value is specified depends on the version of Chrome used. As of Chrome 73, the major version of the driver and the browser must match.

For a list of ChromeDriver versions, see chromedriver versions list.

Use this for specifying a specific point release

If you find a bug that you determine is driver related, you can specify the latest point release of the chrome driver that matches the browser version.

For example, Sauce Labs might default to "88.0.4324.27", but there is a bug fix in version "88.0.4324.96", so you can specify that in your test.

"chromedriverVersion": "88.0.4324.96"

edgedriverVersion​

| STRING |

Specifies the Microsoft Edge driver version you want to use for your tests. For a list of edgedriver versions, see the Microsoft Edge Driver website.

note

Edge Driver is based on Chrome Driver, so the same caveats from chromedriverVersion apply to edgedriverVersion.

"edgedriverVersion": "90.0.818.51"

geckodriverVersion​

| STRING |

Specifies the Firefox GeckoDriver version. The default geckodriver version varies based on the version of Firefox specified. For a list of geckodriver versions and the Firefox versions they support, see geckodriver Supported Platforms.

note

With geckodriver version 0.31.0, Mozilla removed the capability --remote-debugging-port, which was never officially supported. You can use the supported capability moz:debuggerAddress. See this article on our blog for more information.

"geckodriverVersion": "0.27.0"

iedriverVersion​

| STRING |

Specifies the Internet Explorer Driver version. If no version is specified, it defaults to 2.53.1. For a list of IE Driver versions, see Internet Explorer Driver Server CHANGELOG.

"iedriverVersion": "3.150.1"

seleniumVersion​

| STRING |

Specifies the Selenium version you want to use for your test. Sauce Labs will default to different versions, depending on the age of the browser and platform, and whether or not you're initializing a session with valid W3C syntax.

tip

Always use the latest Selenium version. The Selenium developers are very conscientious about backward compatibility support, so we recommend always using the latest available version unless you find a specific, known issue.

"seleniumVersion": "3.141.1"

avoidProxy​

| BOOLEAN |

Allows the browser to communicate directly with servers without going through a proxy that is shipped with Selenium versions prior to v3. By default, Sauce routes traffic from Internet Explorer and Safari through an HTTP proxy server so that HTTPS connections with self-signed certificates will work. The proxy server can cause problems for some users, and this setting allows you to avoid it.

note

This configuration is only relevant for Selenium versions 2.x and older. Any test run with a Sauce Connect tunnel has to use the proxy and this flag will be ignored.

"avoidProxy": true

extendedDebugging​

| BOOLEAN |

Enables Extended Debugging features. This applies to Firefox and Chrome only. It records HAR files and console logs for both of these browsers. In Chrome, it also enables network interception, network and cpu throttling as well as access to network logs during the session. It is required to be true for capturePerformance. The default value is false.

"extendedDebugging": true

capturePerformance​

| BOOLEAN |

Enables Performance Capture feature. Sauce Performance Testing can be enabled by setting both extendedDebugging and capturePerformance to true. Default value is false. See Getting Started with Sauce Front-End Performance for more information.

"capturePerformance": true

screenResolution​

| STRING |

Specifies the screen resolution to be used during your test session. Default screen resolution for Sauce tests is 1024x768.

note

To specify the screen resolution on Windows, we recommend that you set the platformName to Windows 8 or newer (e.g., Windows 10).

"screenResolution": "1280x1024"

commandTimeout​

| INTEGER |

Sets command timeout in seconds. As a safety measure to prevent Selenium crashes from making your tests run indefinitely, we limit how long Selenium can take to run a command in our browsers. This is set to 300 seconds by default. The maximum command timeout value allowed is 600 seconds.

"commandTimeout": 300

idleTimeout​

| OPTIONAL | DURATION | INTEGER | Desktop Only |

Sets idle test timeout in seconds. As a safety measure to prevent tests from running too long after something has gone wrong, we limit how long a browser can wait for a test to send a new command. This is set to 90 seconds by default and limited to a maximum value of 1000 seconds.

"idleTimeout": 90

devTools​

| OPTIONAL | BOOLEAN | Desktop Only | BETA |

Enables Chrome DevTools Protocol support, which is disabled by default on Sauce Labs platform. This allows Selenium 4 clients to use Bi-Directional functionality. In particular, this capability exposes the WebSocket endpoint which is available under se:cdp field in session startup response body. This endpoint can be used to issue Chrome DevTools Protocol commands as described by the specification. The default value is false.

The devTools capability is not compatible with extendedDebugging capability.

"devTools": true

Mobile Appium Capabilities​

As the W3C WebDriver Protocol is supported in Appium v1.6.5 and higher, and required for Appium v2.0, we encourage and support using it for your Appium mobile app tests instead of the JSON Wire Protocol (JWP). We'll continue to support JWP in all currently supported Appium 1.X versions, but please be aware that with Appium 2.0, JWP support will be fully deprecated in favor of W3C.

The capabilities defined here assume the W3C WebDriver Protocol. See Appium Real Device W3C Specification and Migrating Appium Real Device Tests to W3C for more information.

platformName​

| MANDATORY for Virtual and Real Devices | STRING |

Identifies the name of the operating system the mobile device should be running on. Values are not case-sensitive (i.e., "ios" is the same as "iOS"). Valid values are Android and iOS. See the WebDriver W3C Specification for more information.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("platformName", "Android");

appium:platformVersion​

| MANDATORY for Virtual Devices | OPTIONAL for Real Devices | STRING |

Allows you to set the mobile OS platform version that you want to use in your test.

note

Android and iOS platform versions are based on Semantic Versioning, also known as SEMVER. This means that the versions will have the format MAJOR.MINOR.PATCH.

Virtual Devices

This is mandatory for Android Emulators and iOS Simulators. You can find the available versions in our Platform Configurator.

note

iOS Simulators now support the values latest, current_major, or previous_major as the appium:platformVersion. These values will automatically use the latest, current major, or previous major version of iOS for your specified Simulator. See iOS Version Management for more information.

Real Devices

This is optional for Real Devices. There are three options you can use to determine which version you want to use for your automated Appium, Espresso, or XCUITest tests:

  1. Don't provide a platformVersion, this will result in any available Android or iOS device, no matter the version.
  2. Provide a platformVersion that starts with your provided platformVersion string:
    • 12: matches all minors and patches for platformVersion: "12". For example 12.1.0|12.1.1|12.2.0|...
    • 12.1: matches all patches for platformVersion: "12.1". For example 12.1.0|12.1.1, it will not match 12.2.x|12.3.x and higher
    • 12.1.1: matches all devices that have this exact platform version
  3. In/exclude a specific version and or a range of versions by using a regular expression (regex). You don't need to provide the forward slashes (/{your-regex}/) as you would normally do with regex. Keep in mind that the regex needs to match the format MAJOR.MINOR.PATCH. The possibilities are endless, but here are just a few examples:
    • ^1[3-4|6].*: Will match 13, 14 and 16, but not 15, see example.
    • ^(?!15).*: Will exclude version 15 with all it's minors and patches, but will match all other versions, see example.
NOTE

The stricter the platformVersions is, the smaller the pool of available devices will be and the longer you might need to wait for the available device. We recommend using only the major version or using the regex option to get the best results and an available device in the fastest way.

MutableCapabilities capabilities = new MutableCapabilities();
// For Android Emulators or iOS Simulators
// the platformVersion needs to match exactly
capabilities.setCapability("appium:platformVersion", "12.0");
// For Real Devices, dynamically finding an available device
// with at least major version 12
capabilities.setCapability("appium:platformVersion", "12");
// For Real Devices when you exactly know the version of
// the device you want to use
capabilities.setCapability("appium:platformVersion", "12.4.1");
// For Real Devices when you want to exclude version 15
capabilities.setCapability("appium:platformVersion", "^(?!15).*");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:deviceName​

| MANDATORY for Virtual Devices | OPTIONAL for Real Devices | STRING |

Allows you to set the name of the simulator, emulator, or real device you want to use in the test.

For Real Devices:

You can use this to set up a test with either static or dynamic allocation for RDC, and run individual or parallel tests. Static allocation allows you to run your tests on a very specific device, while dynamic allocation allows you to specify a family of devices or any device with a certain OS so you can quickly run your test on the first available real device (RDC) device.

  • Dynamic allocation example: for an Android RDC test, you can request a generic Samsung Galaxy device by using the option "appium:deviceName":"Samsung Galaxy.*".
  • Static allocation example: if you want to use a Samsung Real Device, you need to specify the exact Samsung Galaxy device by using it's device ID or display name (e.g., "appium:deviceName":"Samsung_Galaxy_S20_real" or "appium:deviceName":"Samsung Galaxy S20").

For Android Emulators

Each Android Emulator skin will have a different configuration depending on the phone or tablet that it emulates. For example, all the skins have different resolutions, screen dimensions, pixel densities, memory, etc. You can use our Platform Configurator to get a list of the available Android emulator skins for the various Android Emulator versions.

Examples

MutableCapabilities capabilities = new MutableCapabilities();
// For a real device
capabilities.setCapability("appium:deviceName", "Samsung Galaxy S20");
// For an Android Emulator
capabilities.setCapability("appium:deviceName", "Google Nexus 7 HD Emulator");
// For an iOS Simulator
capabilities.setCapability("appium:deviceName", "iPhone XS Simulator");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:automationName​

| OPTIONAL for Appium 1.x (JWP) | MANDATORY for Appium 2.0 (W3C) | STRING |

Allows you to set the automation engine that will be used. Possible values are:

Emulators / Simulators:

  • Android: UiAutomator2, Espresso, Flutter
  • iOS: XCUITest, Flutter

Real Devices:

  • Android: UiAutomator2
  • iOS: XCUITest
MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:automationName", "UiAutomator2");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

browserName​

| OPTIONAL | STRING | Virtual and Real Devices |

Identifies the browser to be used when automating with a mobile browser. See the WebDriver W3C Specification for more information. This capability is case-insensitive

  • For Android the value needs to be "Chrome".
  • For iOS, the value needs to be "Safari".
note
  • If this capability is not provided for a virtual device, the appium:app capability needs to be set. If none is set the test will throw an error.
  • This capability can be omitted for virtual devices if the appium:app capability is set.
  • If this capability is not provided for a real device session and also the: 
MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("browserName", "chrome");

appium:app​

| OPTIONAL | STRING | Virtual and Real Devices |

Allows you to set a path to an .ipa, .apk, .aab or .zip file containing the mobile app you want to test. This could be the location of your app in App Storage (e.g., storage:filename=myapp.zip) or the URL to a remote location where your app is located (e.g., http://myappurl.zip). The remote location needs to be accessible from the web, Sauce Connect can not access your internal file system where apps are hosted.

note

  • If this capability is not provided for a virtual device, the browserName capability needs to be set. If none is set the test will throw an error.

  • This capability can be omitted for virtual devices if the browserName capability is set.

  • If this capability is not provided for a real device session and also the:

    capability is not provided, then a real device session will automatically fall back to the default browser. This will be Chrome for Android and Safari for iOS

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:app", "storage:filename=my_app.zip");
Using Storage Id

If your app has been uploaded to Sauce storage, you can set the app capability to "storage:xxxxxxxxx-xxxxxxx-xxx" and enter the FILE ID for your app. This allows you to set which specific version you uploaded. Otherwise, if you use the file name it will select the latest version uploaded with the exact same name.

tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:bundleId​

| OPTIONAL | STRING | Real Devices Only | iOS Only |

Bundle identifier of the app under test, for example com.apple.calculator. The capability value is calculated automatically if appium:app is provided.

note

If neither appium:app, browserName, or appium:bundleId capability is provided then by default Sauce Labs will start the Safari browser for iOS.

tip

These two posts explain how you can get the bundleId for iOS apps:

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:bundleId", "com.apple.calculator");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:appPackage​

| OPTIONAL | STRING | Real Devices Only | Android Only |

Application package identifier to be started, for example, com.google.android.youtube. If not provided, then UiAutomator2 will try to detect it automatically from the package provided by the appium:app capability. Read How To Troubleshoot Activities Startup for more details.

note

If neither appium:app, browserName, or appium:appPackage plus appium:appActivity capabilities are provided then by default Sauce Labs will start the Chrome browser for Android.

tip

This post explains how you can get the appPackage for Android apps.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:appPackage", "com.google.android.youtube");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:appActivity​

| OPTIONAL | STRING | Real Devices Only | Android Only |

Main application activity identifier, for example, com.google.android.apps.youtube.app.watchwhile.WatchWhileActivity. If not provided then UiAutomator2 will try to detect it automatically from the package provided by the appium:app capability. Read How To Troubleshoot Activities Startup for more details.

note

If neither appium:app, browserName or appium:appActivity plus appium:appPackage capability are provided then by default Sauce Labs will start the Chrome browser for Android.

tip

You can get the current activity by using the Appium currentActivity command. This is the Appium 1 command, but will also work with Appium 2.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:appActivity", "com.google.android.apps.youtube.app.watchwhile.WatchWhileActivity");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:otherApps​

| OPTIONAL | STRING or LIST | Real Devices Only |

A dependent app that has already been uploaded to App Storage will be pre-installed on the device during the testing of the main app. You can specify the app using its storage:<fileId> or storage:filename=<filename> reference.

Dependent apps inherit the configuration of the main app under test for Device Language, Device Orientation, and Proxy, regardless of the settings may have been applied to the app at the time of upload, because the settings are specific to the device under test. For example, if the dependent app is intended to run in landscape orientation, but the main app is set to portrait, the dependent app will run in portrait for the test, which may have unintended consequences.

Android-dependent apps will not be instrumented or modified. iOS-dependent apps will always be resigned/modified (even when resigning is disabled for the main app) because apps can't be installed on iOS devices without resigning them. If a dependent app cannot be resigned (such as a third party app), the test will not work as intended.

MutableCapabilities capabilities = new MutableCapabilities();
// Or for a single app by name
capabilities.setCapability("appium:otherApps", "storage:filename=app0.apk");
// Or for a single app by fileId
capabilities.setCapability("appium:otherApps",  "storage:7435ab52-1eaa-4387-a67b-4d8e265f85");
// Or for multiple apps by name
capabilities.setCapability("appium:otherApps", ["storage:filename=app0.apk", "storage:filename=app1.apk"]);
// Or for multiple apps by fileId
capabilities.setCapability("appium:otherApps",  ["storage:7435ab52-1eaa-4387-a67b-4d8e265f8509","storage:9035342-f8ea-7687-a67b-4dd4365f8588"]);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:orientation​

| OPTIONAL | STRING | Virtual and Real Devices |

Specifies the orientation of the screen during the test. Valid values are PORTRAIT and LANDSCAPE.

important

This capability is an Appium capability that needs to be pre-fixed with appium: so it becomes appium:orientation. It can be used for virtual device mobile tests and real device tests. Theappium:orientation capability will only flip the screen while the capability deviceOrientation will flip the skin and the screen. See deviceOrientation for more information.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:orientation", "LANDSCAPE");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:noReset​

| OPTIONAL | BOOLEAN | Virtual and Real Devices |

If set to true it prevents the device from resetting before the session startup. This means the application under test will not be terminated or its data cleaned. This capability behaves differently across virtual and real devices.

For Real Devices:

Set noReset to true to keep a device allocated to you during the device cleaning process, as described under cacheId, allowing you to continue testing on the same device. Default value is false. To use noReset, you must pair it with cacheId.

For Virtual Devices:

This capability will have no effect on Sauce Labs virtual devices, it will only work on local Android Emulators/iOS Simulators. For local executions, you will likely only have one device available, in Sauce Labs you will have a pool of devices available depending on your concurrency. Each session will start a new clean session which will make this capability redundant.

Specifics for Android Real Devices:

If noReset is set to true:

  • The app does not stop after a test/session.
  • The app data will not be cleared between tests/sessions.
  • Apk will not be uninstalled after a test/session.

Specifics for iOS Real Devices:

On iOS devices, the noReset value is permanently set to true and cannot be overridden using noReset:false. If you check your Appium logs, you'll see that the value is true, even though the default setting technically is false. We've done this intentionally to ensure that your post-test iOS device cleaning process is optimal and secure.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:noReset", true);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:autoWebview​

| OPTIONAL | BOOLEAN | Virtual and Real Devices |

Move directly into Webview context if available. This can come in handy when you need to automate a Hybrid app and the first screen in your app is a Hybrid screen. Default false.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:autoWebview", true);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:includeSafariInWebviews​

| OPTIONAL | BOOLEAN | Virtual and Real Devices | iOS Only |

Add Safari web contexts to the list of contexts available during a native/webview app test. This is useful if the test starts with an app and you eventually need to open Safari to be able to interact with it. Defaults to false.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:includeSafariInWebviews", true);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:autoAcceptAlerts​

| OPTIONAL | BOOLEAN | Virtual and Real Devices | iOS Only |

Accept all iOS alerts automatically if they pop up. This includes privacy access permission alerts (e.g., location, contacts, photos). Default is false.

note

The Android equivalent is appium:autoGrantPermissions.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:autoAcceptAlerts", true);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:autoDismissAlerts​

| OPTIONAL | BOOLEAN | Virtual and Real Devices | iOS Only |

Dismiss all iOS alerts automatically if they pop up. This includes privacy access permission alerts (e.g., location, contacts, photos). Default is false.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:autoDismissAlerts", true);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:autoGrantPermissions​

| OPTIONAL | BOOLEAN | Virtual and Real Devices | Android Only |

Whether to grant all the requested application permissions automatically when a test starts.

The default value is true.

note

The iOS equivalent is appium:autoAcceptAlerts.

MutableCapabilities capabilities = new MutableCapabilities();
// Handle all requested application permissions "yourself"
capabilities.setCapability("appium:autoGrantPermissions", false);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:timeZone​

| OPTIONAL | BOOLEAN | Virtual and Real Devices | Android Only |

Overrides the current device's time zone. This change is done on per-device basis and is preserved for the whole duration of the test session. The time zone identifier must be a valid name from the list of available time zone identifiers, for example Europe/Paris.

note

The iOS equivalent is appium:appTimeZone.

note

This capability is only supported since UiAutomator2 driver version 3.1.0.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:timeZone", "Europe/Paris");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:appTimeZone​

| OPTIONAL | BOOLEAN | Virtual and Real Devices | iOS Only |

Defines the custom time zone override for the application under test. You can use UTC, PST, EST, as well as place-based timezone names such as America/Los_Angeles. See the list of available time zone identifiers f or more details. The same behavior could be achieved by providing a custom value to the TZ environment variable via the appium:processArguments capability.

note

The Android equivalent is appium:timeZone.

note

This capability is only supported since XCUITest driver version 7.10.0.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:appTimeZone", "America/Los_Angeles");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

Mobile Appium Timeout Capabilities​

As with Selenium Tests, Appium also supports different types of timeouts like:

  • Implicit Wait Timeout: Set the amount of time the driver should wait when searching for elements
  • Script Timeouts: Sets the amount of time, in milliseconds, that asynchronous scripts executed by execute async are permitted to run before they are cancelled (Web context only)

These timeouts can be controlled by the driver during the test session. There are timeouts that can be set as a capability for when you start the driver and can be driver specific.

appium:newCommandTimeout​

| OPTIONAL | DURATION | INTEGER | Virtual and Real Devices | Android and iOS |

Specifies the amount of time in seconds, in which the driver waits for a new command from the client before assuming the client has stopped sending requests. If there is no response during this time, the next executed command on the Virtual/Real Device will time out. The default value is 60 seconds while the maximum allowed value is not limited for Virtual Devices and is limited to 90 seconds for Real Devices.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:newCommandTimeout", 90);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:autoWebviewTimeout​

| OPTIONAL | DURATION | INTEGER | Virtual and Real Devices | Android only |

Set the maximum number of milliseconds to wait until a web view is available if autoWebview capability is set to true. 2000 ms by default

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:autoWebviewTimeout", 30000);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:webkitResponseTimeout​

| OPTIONAL | DURATION | INTEGER | Real Devices Only | iOS only |

Set the time, in milliseconds, to wait for a response from WebKit in a Safari session. Defaults to 5000

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:webkitResponseTimeout", 10000);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:webviewConnectTimeout​

| OPTIONAL | DURATION | INTEGER | Virtual and Real Devices | iOS only |

The time to wait, in milliseconds, for the initial presence of webviews in MobileSafari or hybrid apps. Defaults to 0

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:webviewConnectTimeout", 50000);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

Mobile Appium iOS WebDriverAgent Timeout Capabilities​

WebDriverAgent is a WebDriver server implementation for iOS that is used to remote control iOS devices. It is developed for end-to-end testing and is adopted via the XCUITest driver. The WebDriverAgent has it's own timeout capabilities that can be controlled by the driver during the test session. The most important ones are explained below.

note

It might be helpful to understand how the WebDriverAgent works before reading the following capabilities. You can check this video Appium: Under the Hood of WebDriverAgent by Mykola Mokhnach for a quick introduction. The reason for adjusting the timeouts, which are explained below, are explained in this video from here.

appium:wdaLaunchTimeout​

| OPTIONAL | DURATION | INTEGER | Virtual and Real Devices | iOS only |

Time, in ms, to wait for WebDriverAgent to be pingable. Defaults to 60000ms.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:wdaLaunchTimeout", 30000);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:wdaConnectionTimeout​

| OPTIONAL | DURATION | INTEGER | Virtual and Real Devices | iOS only |

Timeout, in ms, for waiting for a response from WebDriverAgent. Defaults to 240000ms.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:wdaConnectionTimeout", 30000);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:waitForIdleTimeout​

| OPTIONAL | DURATION | FLOAT | Virtual and Real Devices | iOS only |

The amount of time in float seconds to wait until the application under test is idling. XCTest requires the app's main thread to be idling in order to execute any action on it, so the WebDriverAgent might not even start/freeze if the app under test is constantly hogging the main thread. The default value is 10 (seconds). Setting it to zero disables idling checks completely (not recommended) and has the same effect as setting waitForQuiescence to false. Available since Appium 1.20.0.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:waitForIdleTimeout", 60);
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

appium:commandTimeouts​

| OPTIONAL | DURATION | STRING | Virtual and Real Devices | iOS only |

Custom timeout(s) in milliseconds for WebDriverAgent backend commands execution. This might be useful if the WebDriverAgent backend freezes unexpectedly or requires too much time to fail and blocks automated test execution. The value is expected to be of type string and can either contain max milliseconds to wait for each WebDriverAgent command to be executed before terminating the session forcefully.

note

Don't confuse appium:commandTimeouts with appium:newCommandTimeout which is the timeout for the next command to be executed.

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("appium:commandTimeouts", "120000");
tip

Using Appium 2? Prevent appium:-prefix repetitiveness and start using appium:options for Real Devices instead.

More Appium specific capabilities​

Not all specific Appium Driver capabilities are explained here in preventing duplications. There are more capabilities which are specific for each Appium Driver. They can be found here

Android

iOS

appium:options​

| OPTIONAL | OBJECT | Real Devices | Appium 2 Only |

If you use a lot of appium: capabilities in your tests, it can get a little repetitive. You can combine all capabilities as an object value of a single appium:options capability instead, in which case you don't need to use prefixes on the capabilities inside the object. For example:

MutableCapabilities capabilities = new MutableCapabilities();
capabilities.setCapability("platformName", "iOS");
capabilities.setCapability("browserName", "Safari");
MutableCapabilities appiumOptions = new MutableCapabilities();
appiumOptions.setCapability("automationName", "XCUITest");
appiumOptions.setCapability("deviceName", "iPhone iPhone 11");
appiumOptions.setCapability("platformVersion", "16");
capabilities.setCapability("appium:options", appiumOptions);
// `appium:options` will only work with Appium 2 or later
// This can be set in the `sauce:options` block
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("appiumVersion", "2.0.0");
sauceOptions.setCapability("build", "<your build id>");
sauceOptions.setCapability("name", "<your test name>");
capabilities.setCapability("sauce:options", sauceOptions);
note

appium:options support for Virtual Devices is coming soon.

caution

If you include the same capabilities both inside and outside of appium:options, the values inside of appium:options take precedence.

Mobile App Appium Capabilities: Sauce-Specific – Optional​

Optional, Sauce-specific capabilities that you can use in your Appium tests. They can be added to the sauce:options block of your session creation code.

appiumVersion​

| OPTIONAL | STRING | Virtual and Real Devices |

Specifies the Appium driver version you want to use. For most use cases, setting the appiumVersion is unnecessary because Sauce Labs defaults to the version that supports the broadest number of device combinations. Sauce Labs advises against setting this property unless you need to test a particular Appium feature or patch.

note

If you want to use Appium 2.0, see the Migration Guide.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("appiumVersion", "1.22.0");
capabilities.setCapability("sauce:options", sauceOptions);

Check on which Appium version your test ran:​

  1. Log into Sauce Labs.
  2. Go to Test Details.
  3. Find and select the test that you ran using Appium.
  4. Click the Metadata tab.
  5. Look for the Logs row and select Appium Log. The first line indicates the Appium version. For example, 2019-05-05T17:45:07.541Z - info: Welcome to Appium v1.21.0.

deviceOrientation​

| OPTIONAL | STRING| Virtual Devices Only |

Specifies the orientation of the virtual skin and screen during the test. Valid values are PORTRAIT and LANDSCAPE.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("deviceOrientation", "PORTRAIT");
capabilities.setCapability("sauce:options", sauceOptions);

customLogFiles​

| OPTIONAL | LIST | Virtual Devices Only |

If your app creates an extra log then you can use the customLogFiles to store those additional logs in the "Logs" tab of the executed automated session. It is created in the form of a list of search filters that enumerate after an app test to locate text files to upload as logs. Files are uploaded with the .log extension appended. The search paths are rooted at the application under test:

  • Android (path on the emulated device): /data/data/*PACKAGE_ID*/...
  • iOS: *SIMULATED_DEVICE_PATH*/data/Containers/Data/Application/*APPLICATION_ID*/.... On a macOS filesystem, an example of SIMULATED_DEVICE_PATH would be ~/Library/Developer/CoreSimulator/Devices/*DEVICE_ID*

To view and download the extra log files, go to the executed session in the Sauce Labs dashboard, and switch to the "Logs" tab:

  1. "Automated > Test Results"
  2. Search for your session and click on it
  3. Go to the "Logs" tab above the video
customLogFiles

The following examples outline how this is handled for the different device types.

Supplying the list ["files/*_log", "*crash*"] to an Android app test of the package com.saucelabs.exampleapp will upload all the files found after the test, that match either of the glob expressions:

  • /data/data/com.saucelabs.exampleapp/files/*.log
  • /data/data/com.saucelabs.exampleapp/*crash*

Supplying the list ["files/*_log", "*crash*"] to an iOS app test will upload all the files found after the test, that match either of the glob expressions (SIMULATED_DEVICE_PATH and APPLICATION_ID filled in with example values):

  • ~/Library/Developer/CoreSimulator/Devices/8BF8C5E3-E992-424F-A491-5C673761737C/data/Containers/Data/Application/DBF4A728-9414-4431-9A56-41EC1CBFFA0B/files/*.log
  • ~/Library/Developer/CoreSimulator/Devices/8BF8C5E3-E992-424F-A491-5C673761737C/data/Containers/Data/Application/DBF4A728-9414-4431-9A56-41EC1CBFFA0B/*crash*

In both sets of examples, it is worth noting that an asterisk can match directory elements as well as characters, so files/*log will match both files/debug.log and files/subdir/other.log

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("customLogFiles", ["Library/Caches/Logs/*_log", "files/*crash.log"]);
capabilities.setCapability("sauce:options", sauceOptions);

android.gpu.mode​

| OPTIONAL | STRING | Android Virtual Devices Only |

By default, our emulator uses software rendering to handle graphics for maximum compatibility. This involves the CPU calculating how everything looks on your app's screen. However, this could lead to an emulator crash when testing apps with intricate or heavy graphical elements. To mitigate this, use the hardware rendering option by specifying "android.gpu.mode"="hardware" in your test capabilities.

Valid values are hardware and software (default).

caution

Our advice is to leave it as software unless you are experiencing specific issues, like emulator (not app) crashes. Using hardware could solve your specific issue, but beware you might run into other issues which you didn't have before. If you do run into issues, please contact support.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("android.gpu.mode", "hardware");
capabilities.setCapability("sauce:options", sauceOptions);

disableImmersiveModePopUp​

| OPTIONAL | BOOLEAN | Android Virtual Devices Only |

Android allows apps to use the full screen, hiding the status bar and navigation bar. This is called "immersive mode". When you run an Android test, the device will show a popup asking if you want to allow the app to use immersive mode. This popup can interfere with your test, and by default we disable it. If you want to enable it, set disableImmersiveModePopUp to false.

note

Under the hood, this capability is running this command before the app is started:

adb shell settings put secure immersive_mode_confirmations confirmed
MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("disableImmersiveModePopUp", false);
capabilities.setCapability("sauce:options", sauceOptions);

setupDeviceLock​

| OPTIONAL | BOOLEAN | Real Devices Only |

Sets up the device pin code for the automated test session. Valid values are true and false. This capability sets your device in the state required for your application to launch successfully.

important

The setupDeviceLock capability helps to bypass the Security requirements from your applications, like pincode requirements for launching and app or invoking certain activities/features in your app. For an example, see https://developer.android.com/reference/android/app/KeyguardManager.

It must be paired with one of the capabilities listed below.

Real Device Setting
MutableCapabilities capabilities = new MutableCapabilities();
//.. .
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("setupDeviceLock", true);
capabilities.setCapability("sauce:options", sauceOptions);

tabletOnly​

| OPTIONAL | BOOLEAN | Real Devices Only |

Use this capability to select only tablet devices for testing by setting it to "true". For Dynamic Allocation.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("tabletOnly", true);
capabilities.setCapability("sauce:options", sauceOptions);

phoneOnly​

| OPTIONAL | BOOLEAN | Real Devices Only |

Use this capability to select only phone devices by setting it to "true". For Dynamic Allocation.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("phoneOnly", true);
capabilities.setCapability("sauce:options", sauceOptions);

privateDevicesOnly​

| OPTIONAL | BOOLEAN | Real Devices Only |

If your pricing plan includes both private and public devices, use this capability to request allocation of private devices only by setting it to "true". For Dynamic Allocation.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("privateDevicesOnly", true);
capabilities.setCapability("sauce:options", sauceOptions);

publicDevicesOnly​

| OPTIONAL | BOOLEAN | Real Devices Only |

If your pricing plan includes both private and public devices, use this capability to request allocation of public devices only by setting it to "true". For Dynamic Allocation.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("publicDevicesOnly", true);
capabilities.setCapability("sauce:options", sauceOptions);

carrierConnectivityOnly​

| OPTIONAL | BOOLEAN | Real Devices Only | Private Devices Only |

Use this capability to allocate only devices connected to a carrier network by setting it to "true". For Dynamic Allocation.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("carrierConnectivityOnly", true);
capabilities.setCapability("sauce:options", sauceOptions);

cacheId​

| OPTIONAL | STRING | Real Devices Only |

Keeps the device allocated to you between test sessions and bypasses the device cleaning process and session exit that occurs by default after each test completes. Normally, you'd need to start over and reopen another device. You'll need to launch your next test within 10 seconds of your previous test ending to ensure that the same device will be allocated for the test (not cleaned or reset).

note

For Android: If noReset is also set to true, the app under test and its data will remain as-is on the device.

For iOS Changing noReset has no impact here. The app will not be removed, will stay on the phone/tablet and will keep it's state. This is caused by the re-signing process of the app.

If you are running multiple test suites in parallel, the values for cacheId should be unique for each suite (to avoid mixing up the devices), and the value for cacheId must be the same for all test methods that you want to run on the cached device. The value itself can be any (random) string. In addition, the app and project ID used for the tests must remain the same, along with the values for these capabilities:

  • platformName
  • appium:deviceName
  • appium:platformVersion
  • appium:autoGrantPermissions

and specific sauce:options like:

  • tabletOnly
  • phoneOnly
  • privateDevicesOnly
  • appiumVersion

Suitable for test setups that require the app's state to be reset between tests. Can be used for both static allocation and dynamic allocation.

We recommend reviewing Device Management for Real Devices to learn more about how Sauce Labs manages device allocation, device caching, and device cleanup.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("cacheId", "Wou0L9usPI9v");
capabilities.setCapability("sauce:options", sauceOptions);

resigningEnabled​

| OPTIONAL | BOOLEAN | Real Devices Only |

Controls Sauce Labs default resigning (iOS) or instrumentation (Android) of mobile apps installed on our devices. By default, this property is always true.

iOS

When set to true, Sauce Labs will resign the app under test with its own signature. This is required for iOS apps to be installed on our devices, but also to support features like:

And many more. This value can be set to false to allow testing of specific behaviors that are not permitted under the Sauce Labs provisioning. See Resigning Enablements for more information. This capability can only be set to false for iOS private devices.

Android

When set to true, Sauce Labs will instrument the app under test with its own signature. This is required for Android apps if you want to use features like:

and many more. This value can be set to false and can be used for private and public devices.

AAB App Signing

To install an *.apk app that is extracted from an *.aab file, Sauce Labs must sign the *.apk using its own signature. In such cases, Sauce Labs signs both the app and testApp to ensure matching signatures, even if this capability is set to false. Otherwise, the app installation will fail.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("resigningEnabled", true);
capabilities.setCapability("sauce:options", sauceOptions);

sauceLabsImageInjectionEnabled​

| OPTIONAL | BOOLEAN | Real Devices Only |

Enables the camera image injection feature. resigningEnabled needs to be enabled if this is set to true.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("sauceLabsImageInjectionEnabled", true);
capabilities.setCapability("sauce:options", sauceOptions);

sauceLabsBypassScreenshotRestriction​

| OPTIONAL | BOOLEAN | Real Devices Only | Android Only |

Bypasses the restriction on taking screenshots for secure screens (i.e., secure text entry). resigningEnabled needs to be enabled if this is set to true.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("sauceLabsBypassScreenshotRestriction", true);
capabilities.setCapability("sauce:options", sauceOptions);

allowTouchIdEnroll​

| OPTIONAL | BOOLEAN | Real Devices Only |

Enables the interception of biometric input, allowing the test to simulate Touch ID interactions (not a Sauce Labs-specific capability). resigningEnabled needs to be enabled if this is set to true.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("allowTouchIdEnroll", true);
capabilities.setCapability("sauce:options", sauceOptions);

audioCapture​

| OPTIONAL | BOOLEAN |

Enables audio recording in your automated tests. This feature is supported for Windows and macOS desktop tests as well as mobile Real Devices. The audio will be part of the Test Results page video file, which you can play back and download in our built-in media player. The default value is false.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("audioCapture", true);
capabilities.setCapability("sauce:options", sauceOptions);

networkCapture​

| OPTIONAL | BOOLEAN | Real Devices Only |

Enables mobile app instrumentation (Android or iOS) and recording of HTTP/HTTPS network traffic for debugging purposes. API calls are collected into a HAR file, which you can view and download from your Test Results > Network tab console. The default value is false.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("networkCapture", true);
capabilities.setCapability("sauce:options", sauceOptions);

groupFolderRedirectEnabled​

| OPTIONAL | BOOLEAN | Real Devices Only | iOS Only |

Enables the use of the app's private app container directory instead of the shared app group container directory. For testing on the Real Device Cloud, the app gets resigned, which is why the shared directory is not accessible.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("groupFolderRedirectEnabled", true);
capabilities.setCapability("sauce:options", sauceOptions);

enableAnimations​

| OPTIONAL | BOOLEAN | Real Devices Only | Android Only |

Use this capability to enable animations for Android real devices by setting it to true. By default, animations are disabled.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("enableAnimations", true);
capabilities.setCapability("sauce:options", sauceOptions);

systemAlertsDelayEnabled​

| OPTIONAL | BOOLEAN | Real Devices Only | iOS Only |

Delays system alerts, such as alerts asking for permission to access the camera, to prevent app crashes at startup. resigningEnabled needs to be enabled if this is set to true.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("systemAlertsDelayEnabled", true);
capabilities.setCapability("sauce:options", sauceOptions);

sessionCreationTimeout​

| OPTIONAL | INTEGER | Real Devices Only |

Specify the amount of time (in milliseconds) that the test should be allowed to find and assign an available device before the test will fail. The default value is 900000 milliseconds (15 minutes) and the max is 1800000 milliseconds (30 minutes).

caution

If you assign a value to this parameter that is lower than 1 minute (60000 milliseconds), you might encounter an Unable to find available device within {sessionCreationTimeout}ms error. This happens because the device may not be prepared in time for the test to begin.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
// Set it to 5 minutes (5*60*1000=300000)
sauceOptions.setCapability("sessionCreationTimeout", 300000);
capabilities.setCapability("sauce:options", sauceOptions);

sessionCreationRetry​

| OPTIONAL | INTEGER | Real Devices Only |

Specify the amount of automatic retries that Sauce Labs will execute to find and assign an available device before the test will fail. The default value is 1 and the max is 3.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
// Set it to 5 minutes (5*60*1000=300000)
sauceOptions.setCapability("sessionCreationRetry", 2);
capabilities.setCapability("sauce:options", sauceOptions);

networkProfile​

| OPTIONAL | STRING | Real Devices Only | BETA |

Set a network profile with predefined network conditions at the beginning of the session. Please refer to the list of network profiles for more information about each profile's network conditions.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("networkProfile", "2G");
capabilities.setCapability("sauce:options", sauceOptions);

networkConditions​

| OPTIONAL | OBJECT | Real Devices Only | BETA |

Set custom network conditions for downloadSpeed, uploadSpeed, latency or loss at the beginning of the session. Not all parameters need to be specified and only the ones specified will have conditioning applied. Please refer to the supported network conditions for more information.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("networkConditions", ImmutableMap.of(
		"downloadSpeed", 5000,
		"uploadSpeed", 3000,
		"latency", 200,
		"loss", 2,
));
capabilities.setCapability("sauce:options", sauceOptions);
important

Each network condition has a supported value range:

  • downloadSpeed: 0 - 50000 kbps
  • uploadSpeed: 0 - 50000 kbps
  • latency: 0 - 3000 ms
  • loss: 0 - 100 %

sauce: network-profile​

| OPTIONAL | STRING | Real Devices Only |

Set a network profile with predefined network conditions dynamically during your session. Please refer to the list of network profiles for more information about each profile's network conditions.

driver.executeScript("sauce: network-profile", "2G");

sauce: network-conditions​

| OPTIONAL | OBJECT | Real Devices Only |

Set custom network conditions for downloadSpeed, uploadSpeed, latency or loss dynamically during your session. Not all parameters need to be specified and only the ones specified will have conditioning applied. Please refer to Network Throttling - executeScript for more information.

driver.executeScript("sauce: network-conditions", ImmutableMap.of(
    "downloadSpeed", 5000,
    "uploadSpeed", 3000,
    "latency", 200,
    "loss", 2,
));

mobile: shell​

| OPTIONAL | STRING | Real Devices Only | Android Only |

Execute ADB shell commands, through Appium's mobile: shell capability.

note

Sauce Labs now supports ADB commands for Appium. To use ADB and mobile: shell commands, please sign up for our BETA through this form and indicate the desired ADB commands you would like to run. We will be supporting a limited list of ADB commands through mobile: shell. Please refer to the list of allowed commands or contact support for assistance.

driver.executeScript("mobile: shell", ImmutableMap.of(
    "command", "input",
    "args", ImmutableList.of("keyevent", "3")
));

Desktop and Mobile Capabilities: Sauce-Specific – Optional​

Optional Sauce Labs-specific capabilities that you can use for any Sauce Labs test. They must be added to the sauce:options block of your session creation code.

name​

| OPTIONAL | STRING |

Records test names for jobs and make it easier to find individual tests.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("name", "You test name");
capabilities.setCapability("sauce:options", sauceOptions);

build​

| OPTIONAL | STRING |

Associates multiple jobs with a build number or app version, which will then be displayed on both the Test Results dashboard and Archive view.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("build", "build-1234");
capabilities.setCapability("sauce:options", sauceOptions);

tags​

| OPTIONAL | LIST | Virtual and Real Devices |

User-defined tags for grouping and filtering jobs on the Test Results dashboard and Archive view. Tags can facilitate team collaboration.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("tags", ["tag1","tag2","tag3"]);
capabilities.setCapability("sauce:options", sauceOptions);

username​

| OPTIONAL | STRING |

Sets your Sauce Labs username for a test.

You can either set "username" in capabilities or specify it in the Sauce URL as Basic Authentication. For Visual Tests), this must be set in capabilities.

tip

You can find your username value under Account > User Settings.

warning

Good security practices include never putting credentials in plain text in your code. We highly encourage you to reference this value from an Environment Variable and Set Environment Variables for Authentication on every machine that executes your code. The example below is in JavaScript.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("username", System.getenv("SAUCE_USERNAME"));
capabilities.setCapability("sauce:options", sauceOptions);

accessKey​

| OPTIONAL | STRING |

Sets your Sauce Labs access key for the test.

You can either set "accessKey" in capabilities or specify it in the Sauce URL as Basic Authentication. For Visual Tests, this must be set in capabilities.

tip

You can find your accessKey value under Account > User Settings.

warning

Good security practices include never putting credentials in plain text in your code. We highly encourage you to reference this value from an Environment Variable and Set Environment Variables for Authentication on every machine that executes your code. The example below is in JavaScript.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("accessKey", System.getenv("SAUCE_ACCESS_KEY"));
capabilities.setCapability("sauce:options", sauceOptions);

custom-data​

| OPTIONAL | OBJECT | Desktop and Virtual Devices Only |

User-defined custom data that will accept any valid JSON object, limited to 64KB in size.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("custom-data", "{'release': '1.0','commit': '0k392a9dkjr','staging': true,'execution_number': 5,'server': ‘test.customer.com'}");
capabilities.setCapability("sauce:options", sauceOptions);

public​

| OPTIONAL | STRING | Desktop and Virtual Devices Only |

We support several test/job result visibility levels, which control who can view the test details. The visibility level for a test can be set manually from the test results page, but also programmatically when starting a test or with our REST API. For more information about sharing test results, see the topics under Sharing the Results of Sauce Labs Tests.

Available visibility modes are:

  • public:
    • Accessible to everyone.
    • May be listed on public web pages and indexed by search engines.
  • public restricted:
    • Share your job's results page and video, but keeps the logs only for you.
    • Hides the fancy job log.
    • Prohibits access to the raw Selenium log so that anonymous users with the link will be able to watch the video and screenshots, but won't be able to see what's being typed and done to get there.
  • share:
    • Only accessible to people with a valid link.
    • Not listed on publicly available pages on Sauce Labs.
    • Not indexed by search engines.
  • team:
    • Best option if you want to share your jobs with other team members that were created as a sub-accounts of one parent account.
    • Only accessible to people under the same root account as you.
  • private:
    • Best option if you don't want to share your test results page and video with anyone.
    • Only you (the owner) will be able to view assets and test results page.
MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("public", "team");
capabilities.setCapability("sauce:options", sauceOptions);

tunnelName​

| OPTIONAL | STRING |

Specify a Sauce Connect tunnel to establish connectivity with Sauce Labs for your test. Tunnels allow you to test an app that is behind a firewall or on your local machine by providing a secure connection to the Sauce Labs platform.

See Basic Sauce Connect Proxy Setup for more information.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("tunnelName", "MyTunnel01");
capabilities.setCapability("sauce:options", sauceOptions);

tunnelIdentifier​

| OPTIONAL | STRING | DEPRECATED |

Specify a Sauce Connect tunnel name to establish connectivity with a Sauce Labs test platform. This is an alias for tunnelName.

Deprecation notice

tunnelIdentifier is being deprecated in favor of tunnelName.

Choose the Correct Tunnel Identifier

The value expected here is the value shown under the Tunnel Name column on the Sauce Labs Tunnels page, not the Tunnel ID numerical value.

See Using Tunnel Names for more information.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("tunnelIdentifier", "MyTunnel01");
capabilities.setCapability("sauce:options", sauceOptions);
Breaking Change

Appium tests for the Real Device Cloud using the W3C protocol MUST use tunnelName instead of tunnelIdentifier.

tunnelOwner​

| OPTIONAL | STRING |

If the tunnelName you've specified to establish connectivity with a Sauce Labs test platform is a shared tunnel, and you are not the user who created the tunnel, you must identify the Sauce Labs user who did create the tunnel in order to use it for your test.

Choose the Correct Tunnel Identifier

The value expected here is the value shown under the Tunnel Name column on the Sauce Labs Tunnels page, not the Tunnel ID numerical value.

See Using Tunnel Names for more information.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("tunnelName", "MyTunnel01");
sauceOptions.setCapability("tunnelOwner", "<username of tunnel originator>");
capabilities.setCapability("sauce:options", sauceOptions);

parentTunnel​

| OPTIONAL | STRING | DEPRECATED |

If the tunnelName (or tunnelIdentifier) you've specified to establish connectivity with a Sauce Labs test platform is a shared tunnel, and you are not the user who created the tunnel, you must identify the Sauce Labs user who did create the tunnel in order to use it for your test. This is an alias for tunnelOwner.

Deprecation notice

parentTunnel is being deprecated in favor of tunnelOwner.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("tunnelIdentifier", "MyTunnel01");
sauceOptions.setCapability("parentTunnel", "<username of tunnel originator>");
capabilities.setCapability("sauce:options", sauceOptions);
Breaking Change

Appium tests for the Real Device Cloud using the W3C protocol MUST use tunnelName instead of tunnelIdentifier and tunnelOwner instead of parentTunnel.

recordVideo​

| OPTIONAL | BOOLEAN |

Use this to disable video recording. By default, Sauce Labs records a video of every test you run. Disabling video recording can be useful for debugging failing tests as well as having a visual confirmation that a certain feature works (or still works). However, there is an added wait time for screen recording during a test run.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("recordVideo", false);
capabilities.setCapability("sauce:options", sauceOptions);

videoUploadOnPass​

| OPTIONAL | BOOLEAN |

Disables video upload for passing tests. videoUploadOnPass is an alternative to recordVideo; it lets you discard videos for tests you've marked as passing. It disables video post-processing and uploading that may otherwise consume some extra time after your test is complete.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("videoUploadOnPass", false);
capabilities.setCapability("sauce:options", sauceOptions);

recordScreenshots​

| OPTIONAL | BOOLEAN |

Disables step-by-step screenshots. In addition to capturing video, Sauce Labs captures step-by-step screenshots of every test you run. Most users find it very useful to get a quick overview of what happened without having to watch the complete video. However, this feature may add some extra time to your tests.

Limitations

The maximum number of screenshots is 150. Once the limit is reached, further screenshots will no longer be taken.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("recordScreenshots", false);
capabilities.setCapability("sauce:options", sauceOptions);

captureHtml​

| OPTIONAL | BOOLEAN |

In the same way Sauce Labs captures step-by-step screenshots, you can capture the HTML source at each step of a test. This feature is disabled by default, but when it is enabled you can view the HTML source captures on the Test Results page.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("captureHtml", true);
capabilities.setCapability("sauce:options", sauceOptions);

recordLogs​

| OPTIONAL | BOOLEAN |

Disables log recording. By default, Sauce creates a log of all the actions that you execute to create a report for the test run that lets you troubleshoot test failures more easily. This option disables only the recording of the log.json file; the selenium-server.log will still be recorded.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("recordLogs", false);
capabilities.setCapability("sauce:options", sauceOptions);

Desktop and Virtual Device Capabilities: Sauce-Specific – Optional​

The following are Sauce Labs-specific options that apply only to virtual devices (desktop sessions, emulators and simulators). These options can be added to the sauce:options block of your session creation code.

maxDuration​

| OPTIONAL | INTEGER | Desktop and Virtual Devices Only |

Sets maximum test duration in seconds. As a safety measure to prevent tests from running indefinitely, the default is 1,800 seconds (30 minutes) and the maximum is 10,800 seconds (three hours).

Tests Should Not Exceed 30 Minutes

A test should never need to run more than 30 minutes. Our data shows that tests that run in under two minutes are twice as likely to pass as tests that take longer than seven minutes.

We have a three-hour maximum in place to ease the transition of new users migrating long-running tests to Sauce Labs.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("maxDuration", 1800);
capabilities.setCapability("sauce:options", sauceOptions);

priority​

| OPTIONAL | INTEGER | Desktop and Virtual Devices Only |

Setting to prioritize jobs. If you have multiple new jobs waiting to start (i.e., across a collection of sub-accounts), jobs with a lower priority number take precedence over jobs with a higher number.

So, for example, if you have multiple jobs simultaneously waiting to start, we'll first attempt to find resources to start all the jobs with priority 0, then all the jobs with priority 1, etc.

When we run out of available virtual machines, or when you hit your concurrency limit, any jobs not yet started will wait. Within each priority level, jobs that have been waiting the longest take precedence.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("priority", 0);
capabilities.setCapability("sauce:options", sauceOptions);

timeZone​

| OPTIONAL | STRING | Desktop and Virtual Devices Only |

Allows you to set a custom time zone for your test based on a city name. Most major cities are supported.

  • For Desktop VMs: can be configured with custom time zones. This feature should work on all operating systems, however, time zones on Windows VMs are approximate. The time zone defaults to UTC. Look for the "principal cities" examples on this list of UTC time offsets.
  • For iOS Virtual Devices: You can use this capability to change the time on the Mac OS X VM, which will be picked up by the iOS simulator.
  • For Android Virtual Devices: This capability is not supported for virtual Android devices. Consider using appium:timeZone instead.
note

Most web apps serve localization content based on the computer's IP Address, not the time zone set in the operating system. If you need to simulate the computer being in a different location, you may need to set up a proxy.

MutableCapabilities capabilities = new MutableCapabilities();
//...
MutableCapabilities sauceOptions = new MutableCapabilities();
sauceOptions.setCapability("timeZone", "Los_Angeles");
capabilities.setCapability("sauce:options", sauceOptions);

| OPTIONAL | STRING | All Devices Since appium2-20240501 |

Both UiAutomator2 and XCUITest drivers allow to change the time zone using corresponding test session capabilities.

Android Devices

Provide a valid time zone identifier to appium:timeZone capability. The time zone identifier must be a valid name from the list of available time zone identifiers, for example America/New_York. The time zone is changed instantly on the per-device basis and is preserved until the next change.

iOS Devices

Provide a valid time zone identifier to appium:appTimeZone capability. The time zone identifier must be a valid name from the list of available time zone identifiers, for example America/New_York. The time zone is changed on the per-application basis and is only valid for the application under test. The same behavior could be achieved by providing a custom value to the TZ environment variable via the appium:processArguments capability.

Pre-Run Executables​

| OPTIONAL | Desktop and Virtual Devices Only |

Pre-run executables have a primary key (prerun) and four secondary keys:

Read the descriptions of each key below the example.

Full Example
"prerun": {
         "executable": "http://url.to/your/executable.exe",

prerun (primary key)​

status Use this to define pre-run executables. You can provide a URL to an executable file, which will be downloaded and executed to configure the VM before the test starts. For faster performance, you may want to upload the executable to your Sauce Apps Storage space. This capability takes a JSON object with four main keys. See Using Pre-Run Executables to Configure Browsers and VMs for more information.

  • Running AutoIt Scripts: If you want to run an AutoIt script during your test, compile it as an .exe, send it using this capability, and set background to true to allow AutoIt to continue running throughout the full duration of your test.
  • Using Multiple Pre-Run Executables: If you need to send multiple pre-run executables, the best way is to bundle them into a single executable file, such as a self-extracting zip file.
  • Sending a Single String Instead of JSON: If a single string is sent as the pre-run capability rather than a JSON object, this string is considered to be the URL to the executable, and the executable launches with background set to false.

executable (secondary key)​

| STRING |

Provide the URL to the executable you want to run before your browser session starts.

args (secondary key)​

| LIST |

Lists the command line parameters that you want the executable to receive. Valid arguments are:

  • --silent or /S: Installs the script silently without raising any dialogs.
  • -a: Add switches to the command line of the underlying setup.exe process.
  • -q: Like --silent, installs the script without raising any dialogs.

background (secondary key)​

| BOOLEAN |

Defines whether Sauce should wait for this executable to finish before your browser session starts. This setting overrides the values set by timeout.

timeout (secondary key)​

| INTEGER |

Defines the number of seconds Sauce Labs will wait for your executable to finish before your browser session starts. The default value is 90 seconds. Maximum is 360 seconds.

Additional Resources​

Example Test Scripts​

See Sauce Labs Training on GitHub.

Visual Testing​

While Visual Testing runs on Sauce Labs servers, the URL gets sent to "https://hub.screener.io". This means that the username and accessKey values are required.

See Visual Testing with WebDriver and Visual Commands and Options.

Limitations

When running a test on a Virtual Device, be aware that each capability value has a 100 characters limitation. If the value exceeds this limit, it will be truncated, which can lead to further side effects or prevent a job from starting.