Skip to end of metadata
Go to start of metadata

Selenium-Specific Options

You can find out more about Selenium testing options in the DesiredCapabilities page of the SeleniumHQ wiki

Required Selenium Test Configuration Settings

SettingDescriptionKeyValue TypeExampleNotes

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 "version": "45.0"If you want to use the latest stable version of Google Chrome or Firefox that Sauce supports, you can use "version": "latest". You can also use "version": "latest-1" or "version": "latest-2", etc to request the next most recent versions of a browser. For example, if the latest stable version of Chrome is 48, you can request "latest-2" to obtain Chrome 46.

Platform

Which operating system the browser should be running on. See the Platform Configurator for available options.

platform string "platform": "OS X 10.9"  

Other Selenium Options

OptionDescriptionKeyValue TypeExampleNotes

Selenium Driver Version

Allows you to choose the version of Selenium you want to use for your test.

The Selenium version defaults to 2.53.1 on Sauce when no version is specified.

For Firefox, the default version of Selenium when no value is specified depends on the version of Firefox.

Firefox 47: Selenium 2.53.1 only

Firefox 46: Selenium 2.51.0 2.52.0 2.53.0, 2.53.1

Firefox 44 - 45: Selenium 2.48.0, 2.50.0, 2.51.0, 2.52.0, 2.53.0

Firefox 39 - 43: Selenium 2.47.1, 2.48.0, 2.50.0, 2.51.0, 2.52.0, 2.53.0
Firefox 38: Selenium 2.46.0
Firefox 32 - 37: Selenium 2.45.0
Firefox 26 - 31: Selenium 2.40.0
Firefox 23 - 25: Selenium 2.35.0
Firefox 21 - 22: Selenium 2.33.0
Firefox 20: Selenium 2.31.0
Firefox 19: Selenium 2.30.0
Firefox 17 - 18: Selenium 2.29.0
Firefox 12 - 16: Selenium 2.27.0
Firefox 11 and below: Selenium 2.18.0

When testing with Chrome and Internet Explorer, Selenium Driver Version is ignored . Instead, for these browsers you should set the driver version as described for the Chrome Driver Version and Internet Explorer Driver Version options.

seleniumVersionstring

"seleniumVersion":

"2.46.0"

Your tests will always run against the most current default Selenium version unless you specify a different version by using this option.

Chrome Driver Version

Sauce Labs supports the ChromeDriver version 1 series (i.e. 26.0.1383.0) and the version 2 series (i.e. 2.15). The default version of ChromeDriver when no value is specified depends on the version of Chrome.

Chrome beta: ChromeDriver 2.24

Chrome 52+: ChromeDriver 2.22
Chrome 46-51: ChromeDriver 2.21
Chrome 46+: Chromedriver 2.21
Chrome 40 - 45: Chromedriver 2.15
Chrome 37 - 39: Chromedriver 2.11
Chrome 33 - 36: Chromedriver 2.10
Chrome 31 - 32: Chromedriver 2.8
Chrome 29 - 30: Chromedriver 2.4
Chrome 28 and below: Chromedriver 26.0.1383.0  
chromedriverVersionstring"chromedriverVersion": "2.15"

Supported Chrome Drivers

  • 21.0.1180.0
  • 23.0.1240.0
  • 26.0.1383.0
    • 0.6
    • 0.7
    • 0.8
    • 0.9
    • 2.0
    • 2.1
    • 2.2
    • 2.3
    • 2.4
    • 2.5
    • 2.6
    • 2.7
    • 2.8
    • 2.9
    • 2.10
    • 2.11
    • 2.12
    • 2.13
    • 2.14
    • 2.15
    • 2.20
    • 2.21
    • 2.22
    • 2.23
    • 2.24

Internet Explorer Driver Version

The Internet Explorer Driver defaults to version 2.53.1 when no version is specified. (For tests on Windows XP, the driver version will default to version 2.42.0.)

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:

Using a 32 bit driver on a 64 bit operating system causes Selenium's screenshot feature to only capture the part of the page currently visible in the browser viewport Selenium Issue 5876.

Using a 64 bit driver on a 64 bit operating system causes text entry to be extremely slow Selenium Issue 5516.

iedriverVersionstring"iedriverVersion": "2.46.0"

Supported IE Drivers

  • 2.21.1
  • 2.21.2
  • 2.24.0
  • 2.25.3
  • 2.26.0
  • 2.28.0
  • 2.29.0
  • 2.30.1
  • 2.31.0
  • 2.32.2
  • 2.33.0
  • 2.34.0
  • 2.35.0
  • 2.35.1
  • 2.35.2
  • 2.35.3
  • 2.36.0
  • 2.37.0
  • 2.38.0
  • 2.39.0
  • 2.40.0
  • 2.41.0
  • 2.42.0
  • 2.43.0
  • 2.44.0
  • 2.45.0
  • 2.46.0
  • 2.48.0
  • 2.49.0
  • 2.50.0
  • 2.51.0
  • 2.52.0
  • 2.52.1
  • 2.52.2
  • 2.53.0
  • 2.53.1
  • x64_2.29.0
  • x64_2.39.0
  • x64_2.40.0
  • x64_2.41.0
  • x64_2.42.0
  • x64_2.43.0
  • x64_2.44.0
  • x64_2.45.0
  • x64_2.46.0
  • x64_2.48.0

Appium-Specific Options 

You can find out more about more about Appium-specific options in  the Appium Server Capabilities page of the Appium.io website

Required Appium Test Configuration Settings

 

SettingDescriptionKeyValue TypeExampleNotes

Browser Name

The mobile web browser that will be automated in the simulator, emulator or device.browserNamestring"browserName": "Safari"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.deviceNamestring"deviceName": "Google Nexus 7 HD Emulator"

For an Android emulator test you can request a generic Android emulator by using the option "deviceName":"Android Emulator". If you want to use an Android emulator that looks and feels like a specific Android phone or tablet, for example a Google Nexus 7 HD Emulator or a Samsung Galaxy S4, then instead of "deviceName":"Android Emulator", you need to specify the exact Android emulator skin to use, for example "deviceName":"Samsung Galaxy S4 Emulator".

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 Platforms Configurator to get a list of the available Android emulator skins for the various Android emulator versions. Supported Android Emulators describes the qualities for each type of emulator that Sauce Labs supports.

Platform Version

The mobile operating system version that you want to use in your test. platformVersionstring"platformVersion": "9.1" 

Platform Name

The mobile operating system platform you want to use in your test.platformNamestring"platformName": "iOS" 

Application Path

For mobile native and hybrid application testing only. See Native and Hybrid Applications: What's the Difference? for more information

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/.appstring"app": "sauce-storage:my_app.zip"This capability is only for testing mobile native or mobile hybrid applications. This capability is not required for Android if you specify the appPackage and appActivity capabilities.

 

Other Appium Options

OptionDescriptionKeyValueExampleNotes

Appium Version

The version of the Appium driver you want to use. If not specified the test will run against the default Appium version. appiumVersionstring It's better to specify the latest Appium version, which is the one suggested by the  Platforms Configurator, unless you have a reason for testing against some other version.

Device Orientation

The orientation in which the simulator/device will be rendered. Options are:

  •   portrait
  • landscape .
deviceOrientationstring"deviceOrientation": "portrait" 

Automation Engine

The automation engine that will be used. Options are:

  • Appium 
  • Selendroid

The default is Appium.

automationNamestring"automationName": "Selendroid" 

Auto Accept Alerts

For iOS Only

You can set this option to automatically accept privacy access alerts related to accessing contacts, photos, or other privacy-protected iOS applications.autoAcceptAlertsboolean"autoAcceptAlerts": true  

Application Package

For Android Only
The Java package of the Android app you want to run.appPackagestring"appPackage": "com.example.android.myApp, com.android.settings"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 Activity

For Android Only
The name for the Android activity you want to launch from your package.appActivitystring"appActivity": ".MainActivity"

This capability needs to be preceded by a . (dot). For example, .MainActivity instead of MainActivity.

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.

General Options

These options can be set for both Selenium and Appium Tests.

Alerts

OptionDescriptionKeyValue TypeExample

Auto Accept Alerts

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)."autoAcceptAlertsboolean"autoAcceptAlerts": true

Test Annotation

You can add these annotations to your tests to make them easier to track and identify. 

OptionDescriptionKeyValue TypeExample

Test Names

Used to record test names for jobs and make it easier to find individual tests
name
string

"name" : "my example name"

Build Numbers

Used to associate jobs with a build number or app version, which is then displayed on both the Dashboard and Archives viewbuildstring"build": "build-1234"

Tagging

User-defined tags for grouping and filtering jobs in the Dashboard and Archives viewtagslist"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 flag on the job. Since you can't know in advance whether a test passed or failed, this flag can't be set in the initial configuration.

passedboolean"passed": "true"

Custom Data

User-defined custom data that will accept any valid JSON object, limited to 64KB in size.customDataobject
"customData": {"release": "1.0", 
                "commit": "0k392a9dkjr", 
                "staging": true, 
                "execution_number": 5, 
                "server": "test.customer.com"}

 

Timeouts

OptionDescriptionKeyValue TypeExample

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.

A test should never be more than 30 minutes and ideally should be less than five minutes long. The 3 hour maximum exists mainly to ease the transition of new users migrating long running tests to Sauce Labs.

While our test VMs respect the maxDuration desired capability when it's set in tests, it may not always be precise. Tests will never be timed out before their maxDuration has elapsed and in most cases, they will be timed out very shortly after their maxDuration has elapsed (e.g. less than 1 second). But, in some rare cases, such as when the test VM is suffering performance problems, they can be allowed to run longer (e.g. 30 seconds or longer).

maxDurationinteger"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.commandTimeoutinteger"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.idleTimeoutinteger"idleTimeout": 90

Sauce Testing Options

OptionDescriptionKeyValue TypeExampleNotes

Version (Browser)

If this capability is null, an empty string, or omitted altogether, the latest version of the browser will be used automatically.versionstring 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  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.

Interacting with the Android Emulator

If you need to use Android tools to tweak the emulator before your test starts (such as  adb ), the  ANDROID_HOME  environment variable will be set before your executable is invoked. For example, you can access  adb  via  $ANDROID_HOME/platform-tools/adb . 

prerun

(primary key)

 

"prerun": { "executable": "http://url.to/your/executable.exe", "args": [ "--silent", "-a", "-q" ], "background": false, "timeout": 120 }

 

If a single string is sent as the  prerun  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 .
 The URL to the executable you want to run before your browser session starts.

executable

(secondary key)

   
 

A list of 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 

args

(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.

background

(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.

timeout

(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. tunnelIdentifierstring"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.parent-tunnelstring"parent-tunnel": "<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 Windows XP, Windows 7 (except Windows 7 with IE 9), Windows 8, Windows 8.1, and OS X 10.8, 10.9, 10.10, and 10.11. We do not yet offer specific resolutions for Windows 10, Linux, or mobile platforms. Default screen resolution for Sauce tests when not specified is 1024x768.screenResolutionstring"screenResolution": "1280x1024"

Valid values for Windows XP and Windows 7

  • 800x600 
  • 1024x768 
  • 1052x864 
  • 1152x864 
  • 1280x800 
  • 1280x960 
  • 1280x1024 
  • 1440x900
  • 1600x1200 
  • 1680x1050 
  • 1920x1200 
  • 2560x1600

Valid values for OS X 10.8

  • 1024x768
  • 1152x864
  • 1152x900
  • 1280x800
  • 1280x1024
  • 1376x1032
  • 1400x1050
  • 1600x1200
  • 1680x1050
  • 1920x1200

Valid values for OS X 10.9 and OS X 10.10

  • 800x600
  • 1152x720
  • 1152x864
  • 1152x900
  • 1280x720
  • 1280x768
  • 1280x800
  • 1280x960
  • 1280x1024
  • 1366x768
  • 1376x1032
  • 1400x1050
  • 1440x900
  • 1600x900
  • 1600x1200
  • 1680x1050
  • 1920x1200
  • 1920x1440
  • 2048x1152
  • 2048x1536
  • 2360x1770

Valid values for OS X 10.11

  • 1024x768
  • 1152x864
  • 1280x960
  • 1376x1032
  • 1600x1200
  • 1920x1440
  • 2048x1536

Valid values for Windows 8 and 8.1

  • 800x600 
  • 1024x768 
  • 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.timeZonestring

"timeZone": "Los Angeles"
"timeZone": "Honolulu"
"timeZone": "Alaska" 
"timeZone": "New_York" 

 

Avoiding the Selenium Proxy

By default, Sauce routes traffic from some WebDriver browsers (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

This flag is incompatible with  Sauce Connect Proxy . 


avoidProxyboolean"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:

Visibility KeyDescription
publicMaking your test public means that it is accessible to everyone, and may be listed on public web pages and indexed by search engines.
public restrictedIf you want to share your job's result page and video, but keep the logs only for you, you can certainly do so with public restricted visiblity mode. This visibility mode will hide the fancy job log as well as prohibit access to the raw Selenium log, so that anonymous users with the link will be able to watch the video and screen shots but won't be able to see what's being typed and done to get there.
shareYou can also decide to make your test sharable. Making your test sharable means that it is only accessible to people having valid link and it is not listed on publicly available pages on saucelabs.com or indexed by search engines.
teamIf you want to share your jobs with other team members (that were created as a sub-accounts of one parent account), you can use team visiblity mode. Making your test acessible by team means that it is only accessible to people under the same root account as you.
privateIf you don't want to share your test's result page and video with anyone, you should use private job visibility mode. This way, only you (the owner) will be able to view assets and test result page.



publicstring
"public": "public"
 

Optional Sauce Testing Features

By default, Sauce Labs captures screenshot and video of your tests. You can disable these and other optional test features. 

OptionDescriptionKeyValueExample

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.videoUploadOnPassboolen"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.recordScreenshotsboolean"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 log.json file. The selenium-server.log will still be recorded even if you choose to disable recording of the log.json.

recordLogsboolean"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.captureHtmlboolean"captureHtml": true

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. webdriverRemoteQuietExceptionsboolean"webdriverRemoteQuietExceptions": false

 


18 Comments

  1. Anonymous

    The documentation for disabling log recording doesn't make it clear that the selenium-server.log file will still exist.

    The fact that these logs are persisted makes it much more difficult to resolve a security risk that potentially exposes users' credentials to the account admin: https://saucelabs.ideas.aha.io/ideas/SLIDEA-I-240

    1. I've updated it with a note to make this information more prominent. 

  2. Anonymous

    In a pre-run executable example, "timeout" is used with "background": "true", whilst it says that the " timeout is capped at 360 seconds and won't apply if background is set to true".

    1. Changed it to false so it makes more sense, thanks for pointing that out.

  3. Anonymous

    @Phil  As per the documentation above if i set the "autoAcceptAlerts": true it doesnt accept the "Share Location" pop up in Firefox and IE. Is that only for a specific browser. How to get the location to be shared in Forefox and IE?

  4. Anonymous

    I am trying to run my webdriverio tests in saucelabs with the below capabilities and I am getting a security issue window and its stopping me for doing testing

    capabilities: [
    {
    maxInstances: 1,
    platform: 'Linux',
    browserName: 'opera',
    version: 'latest',
    },

    ]

     

    ANy help on this

  5. Anonymous

    We are running cucumber feature(Group of scenarios) file scenarios using saucelabs. The Report currently saucelabs showing is feature level i.e., Each feature file recorded as one session id in sauce labs report.

    But, I want to see scenario level session id reports in sauce labs. Can you please help me on this.

    1. Hi, I suggest you post this question in our support portal at https://support.saucelabs.com. We have an extensive community of Cucumber users and support staff who should be able to provide a solution.

  6. Anonymous

    tunnel-identifier is not documented even though it's valid.

    1. 'tunnel-identifier' is deprecated, it works for now but will likley stop working at some point in the future.

  7. Anonymous

    In protractor when I configure 

    "recordVideo": false,
    "videoUploadOnPass": false,

    it still recording video, and tests are executing very slow

    1. Anonymous

      +1 I have the same issue, my tests which on local machine run in 4min on sauce lab it takes more than 30min!!!

      1. Hi, tests run on Sauce Labs will always take longer than tests run locally, because of internet latency. We consider a 3x increase in execution time to be within the expected bounds. However, you might be able to speed up your execution time by running smaller, more atomic tests. Our topic Tips for Lean, Speedy Tests with Sauce Labs has some information that may help. 

    2. You may want to consult with a member of our support staff to find out why your tests are still recording video when you've set the value to "false": https://support.saucelabs.com

       

      1. Anonymous

        Acctually I did double check and seems that these params works. When tests are running I see movie but when tests are done the movie is not available.

        But the huge problem is that tests on sauce lab are really slow: on local machine I run 8 scenarios and it takes around 4 minutes to complete them, but on sauce lab the same tests' suit need 34 min to complete. Another issue is that even when I run only 1 scenario (4 steps, around 1 min on local machine) on sauce lab I get:  Error: Step timed out after 60000 milliseconds?

        Is any way to solve these two issues?

         

        1. There are a couple potential causes for timeout errors, which are described in Common Error Messages, along with some ways to try and resolve them. Without seeing your script it's difficult to say what could be causing the issues, but one thing that comes to mind is whether you are using driver.quit to end it - without a driver.quit, the Selenium server will continue to run, waiting for a new command. This can cause tests to run longer than expected, and time eventually time out. There could also be an issue with the way you're using waits. I suggest you post an example of the problem scripts in our support portal and ask for some guidance on how you can get them to run more quickly in a remote environment: https://support.saucelabs.com.

           

  8. Anonymous

    I am working on tests using mocha/chai and webdriver.io. We have a capabilities section defined in the webdriver.io config file, but every time we run the test it loads Linux/Firefox. Any ideas?

    1. Anonymous

      What browser do you have in your capabilities section? Can you paste capabilities here?

Write a comment…