| Setting | Description | Key | Value Type | Example |
|---|---|---|---|---|
Browser Name | The name of the browser test against. See the Platform Configurator for available options. | browserName | string | "browserName": "firefox" |
Browser Version | The version of the browser you want to use in your test. | version | string |
Default to Latest Version of Chrome or Firefox If you want to use the latest stable version of Google Chrome or Firefox that Sauce supports, you can use Microsoft Edge versions Microsoft Edge has two version numbers, the browser application version and the EdgeHTML rendering engine version. For example, the current stable release of Edge as of September 2017 has the browser application version 40.15063 and the EdgeHTML version 15.15063. The Wikipedia page on Microsoft Edge covers this in more detail: https://en.wikipedia.org/wiki/Microsoft_Edge |
Platform | Which operating system the browser should be running on. See the Platform Configurator for available options. | platform | string | "platform": "macOS 10.13"
|
| Option | Description | Key | Value Type | Example | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Selenium Version | Allows you to choose the version of Selenium you want to use for your test. For Firefox, the default version of Selenium when no value is specified depends on the version of Firefox. "Marionette" replaces the Firefox driver in Firefox 48+. Its binary is called geckodriver (previously wires). The version we use depends on whether the job is Selenium 2 or 3:
When testing with Chrome and Internet Explorer, Selenium Version is not used to determine the version of the ChromeDriver or IEDriver that is used. For these browsers you should set the driver version as described for the Chrome Driver Version and Internet Explorer Driver Version options. | seleniumVersion | string |
Default Selenium Version By default, Sauce Labs will use the following version of Selenium, depending on your selected combination of browser and operating system. While Selenium 3 is not yet fully implemented as a default version, it is supported for all Chrome and Firefox browsers on Mac and Windows platforms, for Safari 10+ on macOS 10.12 Sierra, and for Microsoft Edge and IE browsers version 10 and above. Currently Sauce Labs supports Selenium 3.4.0+ for Firefox and Safari and Selenium 3.5.0+ for Microsoft Edge and Chrome.
You can set the Selenium version for your tests by using the
| ||||||||||||
Chrome Driver Version | Sauce Labs supports the ChromeDriver version 1 series (i.e. NOTE: This capability only applies to Desktop Chrome tests | chromedriverVersion | string |
| ||||||||||||
Internet Explorer Driver Version | The Internet Explorer Driver defaults to version 2.53.1 when no version is specified. Sauce Labs supports launching 64-bit IE on our 64-bit VMs: Windows 7, Windows 8, and Windows 8.1. This provides a workaround for two known Selenium issues:
| iedriverVersion | string |
|
| Setting | Description | Key | Value Type | Example |
|---|---|---|---|---|
| Appium Version | The version of Appium that you want to run your tests with. | appiumVersion | string |
Default Appium Version If you don’t select an Appium Version for your test in the Platform Configurator, this capability will automatically default to the latest version of Appium that is compatible with your selected OS. If you prefer to use a different version of Appium for your test, enter the version number you want as the value for the |
Browser Name | The mobile web browser that will be automated in the simulator, emulator or device. | browserName | string |
Empty String for Mobile Native and Hybrid Apps If you're testing a mobile native application or a mobile hybrid application, the value for this capability should be an empty string. Check out Native and Hybrid Applications: What's the Difference? for more information. |
Device Name | The name of the simulator, emulator, or device you want to use in the test. | deviceName | string |
Generic Android Emulator For an Android emulator test you can request a generic Android emulator by using the option Emulator Skins and Configurations 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 the Platform Configurator to get a list of the available Android emulator skins for the various Android emulator versions. |
Platform Version | The mobile operating system version that you want to use in your test. | platformVersion | string | "platformVersion": "9.1" |
Platform Name | The mobile operating system platform you want to use in your test. | platformName | string | "platformName": "iOS" |
Application Path | The path to a .ipa, .apk or .zip file containing the app to test. This could be the location of your app in the Temporary Sauce Storage, for example, sauce-storage:myapp.zip, or the URL to a remote location where your app is located, for example http://myappurl.zip/. | app | string |
Required for Mobile Native and Hybrid Apps Only This capability is required only for testing mobile native or mobile hybrid applications. See Native and Hybrid Applications: What's the Difference? for more information Not Required for Android This capability is not required for Android if you specify the |
| Option | Description | Key | Value | Example |
|---|---|---|---|---|
Appium Version | The version of the Appium driver you want to use. If not specified the test will run against the default Appium version. | appiumVersion | string | It's better to specify the latest Appium version, which is the one suggested by the Platform Configurator, unless you have a reason for testing against some other version. |
Device Type | The type of device to emulate. Options are:
| deviceType | string | "deviceType": "tablet" |
Device Orientation | The orientation in which the simulator/device will be rendered. Options are:
| deviceOrientation | string | "deviceOrientation": "portrait" |
Automation Engine | The automation engine that will be used. Options are:
The default is | automationName | string | "automationName": "UiAutomator2" |
Application PackageFor Android Only | The Java package of the Android app you want to run. | appPackage | string |
Automatic Package Detection Appium automatically determines the package to launch, you only need to use this desired capability if you want to specify a package different than the default one. |
Android ActivityFor Android Only | The name for the Android activity you want to launch from your package. | appActivity | string |
Don't Forget the Dot! This capability needs to be preceded by a Automatic Activity Detection Appium automatically determines the activity to launch, you only need to use this desired capability if you want to specify an activity different than the default one. |
| Option | Description | Key | Value Type | Example |
|---|---|---|---|---|
Auto Accept AlertsFor iOS Only | Setting this option will automatically accept any unexpected browser alerts that come up during your test, such as when Safari pops up the alert "Safari would like to use your current location (Don't Allow | Allow)." | autoAcceptAlerts | boolean | "autoAcceptAlerts": true
|
You can add these annotations to your tests to make them easier to track and identify.
| Option | Description | Key | Value Type | Example |
|---|---|---|---|---|
Test Names | Used to record test names for jobs and make it easier to find individual tests | name | string |
|
Build Numbers | Used to associate jobs with a build number or app version, which is then displayed on both the Dashboard and Archives view | build | string | "build": "build-1234" |
Tagging | User-defined tags for grouping and filtering jobs in the Dashboard and Archives view | tags | list | "tags": ["tag1","tag2","tag3"] |
Pass/Fail Status | Selenium and Appium handle sending commands to control a browser or app, but don't report to the server whether a test passed or failed. To record pass/fail status on Sauce, set the | passed | boolean | "passed": "true" |
Custom Data | User-defined custom data that will accept any valid JSON object, limited to 64KB in size. | custom-data | object | "custom-data": {"release": "1.0",
"commit": "0k392a9dkjr",
"staging": true,
"execution_number": 5,
"server": "test.customer.com"} |
| Option | Description | Key | Value Type | Example |
|---|---|---|---|---|
Maximum Test Duration | As a safety measure to prevent tests from running indefinitely, Sauce limits the duration of tests to 30 minutes by default. You can adjust this limit on per-job basis and the maximum value is 10800 seconds. Don't Exceed 30 Minutes A test should never last more than 30 minutes and ideally should take less than five minutes. The 3 hour maximum exists mainly to ease the transition of new users migrating long running tests to Sauce Labs. | maxDuration | integer | "maxDuration": 1800 |
Command Timeout | As a safety measure to prevent Selenium crashes from making your tests run indefinitely, Sauce limits how long Selenium can take to run a command in our browsers. This is set to 300 seconds by default. The value of this setting is given in seconds. The maximum command timeout value allowed is 600 seconds. | commandTimeout | integer | "commandTimeout": 300 |
Idle Test Timeout | As a safety measure to prevent tests from running too long after something has gone wrong, Sauce limits 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. You can adjust this limit on a per-job basis. The value of this setting is given in seconds. | idleTimeout | integer | "idleTimeout": 90 |
| Option | Description | Key | Value Type | Example | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Version (Browser) | If this capability is null, an empty string, or omitted altogether, the latest version of the browser will be used automatically. | version | string or integer | "version": "35" | ||||||||||
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 temporary Sauce storage. This capability takes a JSON object with four main keys. Check out the topics under Using Pre-Run Executables to Configure Browsers and Virtual Machines 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 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. |
(primary key) |
Sending a Single String Instead of JSON If a single string is sent as the | |||||||||||
| The URL to the executable you want to run before your browser session starts. |
(secondary key) | |||||||||||||
A list of the command line parameters that you want the executable to receive. Valid arguments are:
|
(secondary key) | |||||||||||||
A boolean that defines whether Sauce should wait for this executable to finish before your browser session starts. If background isn't set or is set to false , Sauce will wait for up to 90 seconds for the executable to finish. At that point, the browser will start and your test will proceed. |
(secondary key) | |||||||||||||
The number of seconds Sauce will wait for your executable to finish before your browser session starts. If timeout isn't set, Sauce will wait for up to 90 seconds for the executable to finish. timeout is capped at 360 seconds and won't apply if background is set to true. |
(secondary key) | |||||||||||||
Identified Tunnels | If an identified tunnel is started using Sauce Connect, your jobs can choose to proxy through it using this set of keys with the right identifier. | tunnelIdentifier | string | "tunnelIdentifier": "MyTunnel01" | ||||||||||
Shared Tunnels | This desired capability will let the test job use any shared tunnels available from the specified parent account. i.e. any account that is upstream in the hierarchy. If using a shared tunnel, you must specify both tunnelIdentifier and parentTunnel. | parentTunnel | string | "parentTunnel": "<username of parent>" | ||||||||||
Specifying the Screen Resolution | This setting specifies which screen resolution should be used during the test session. This feature is available in:
Default screen resolution for Sauce tests when not specified is 1024x768. | screenResolution | string | "screenResolution": "1280x1024" | ||||||||||
Custom Time Zones
| Desktop Test VMs can be configured with custom time zones. This feature should work on all operating systems, however time zones on Windows VMs are approximate. They will default to the time zone that the provided location falls into. You can find a complete list of timezones on Wikipedia. Underscores should be replaced with spaces. Sauce takes only location names (not their paths), as shown in the example below. | timeZone | string | "timeZone": "Los Angeles" "timeZone": "Honolulu" "timeZone": "Alaska" | ||||||||||
Avoiding the Selenium Proxy | By default, Sauce routes traffic from some WebDriver browsers (Edge, Internet Explorer and Safari) through the Selenium HTTP proxy server so that HTTPS connections with self-signed certificates work everywhere. The Selenium proxy server can cause problems for some users. If that's the case for you, you can configure Sauce to avoid using the proxy server and have browsers communicate directly with your servers. Don't Need the Selenium Proxy with Firefox or Google Chrome Firefox and Google Chrome under WebDriver aren't affected by this flag as they handle invalid certificates automatically and there isn't a need to proxy through Selenium. Incompatible with Sauce Connect Proxy This flag is incompatible with Sauce Connect Proxy. | avoidProxy | boolean | "avoidProxy": true | ||||||||||
Job Visibility | Sauce Labs supports several test 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 programatically when starting a test or with our REST API. For more information about sharing test result, see the topics under Sharing the Results of Sauce Labs Tests. Available visibility levels are:
| public | string | "public": "public" |
| Option | Description | Key | Value | Example |
|---|---|---|---|---|
Disable video recording | By default, Sauce records a video of every test you run. This is generally handy for debugging failing tests, as well as having a visual confirmation that certain feature works (or still works!) However, there is an added wait time for screen recording during a test run. | recordVideo | boolean | "recordVideo": false |
Disable video upload for passing tests | As an alternative to disabling video recording, the videoUploadOnPass setting will let you discard videos for passing tests identified using the passed setting. This disables video post-processing and uploading that may otherwise consume some extra time after your test is complete. | videoUploadOnPass | boolean | "videoUploadOnPass": false |
Disable step-by-step screenshots | Sauce 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. You can avoid this by optionally turning off this feature. | recordScreenshots | boolean | "recordScreenshots": false |
Disable 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. Selenium Logs Are Still Recorded This option only disables recording of the | recordLogs | boolean | "recordLogs": false |
Enable HTML source capture | In the same way Sauce captures step-by-step screenshots, we can capture the HTML source at each step of a test. This feature is disabled by default, but you can turn it on any time and find the HTML source captures on your job result page. | captureHtml | boolean | "captureHtml": true |
Prioritize Jobs | If you have multiple new jobs waiting to start, for example 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. | priority | integer | "priority": 0 |
Enable WebDriver's automatic screen shots | Selenium WebDriver captures automatic screenshots for every server side failure, for example if an element is not found. Sauce disables this by default to reduce network traffic during tests, resulting in a considerable performance improvement in most tests. You can enable this feature, but keep in mind that it may be detrimental to the performance of your jobs. | webdriverRemoteQuietExceptions | boolean | "webdriverRemoteQuietExceptions": false |
| Enable Extended Debugging | Extended debugging records HAR files for some browsers, as well as console.json logs. These are extremely valuable for debugging flaky tests. Default value is false. | extendedDebugging | boolean | "extendedDebugging": true |
3 Comments
Anonymous
There's a "share" job visibility setting that this page doesn't yet document. What's the difference between that and "team"?
Anonymous
"Share" is a carryover from a previous version of the API and is the same as "public." It's not documented because it's generally deprecated, but is still available via the API so that users who set this access option in the past can still access those test details pages.
Anonymous
The description for the "-a" argument for a prerun executable is rather vague, what are the details around what capabilities the "-a" argument gives?