Products Documentation > Using Sauce OnDemand

Using Sauce OnDemand

Overview

To get started, you'll need to create an account using our signup form. Choose a username and enter your email address (users who register with their company email address qualify for a free 100-minute trial). Once your account is ready, you need to get some test minutes by either asking for a trial, subscribing with your credit card or buying pre-paid minutes using paypal.

Once you have your account ready and have some test-minutes, you can start using Sauce OnDemand for your tests. Initialize your Selenium RC client to use saucelabs.com at port 4444. If you find your tests can't connect to the server, it may be that outgoing connections on port 4444 are blocked on your network. No problem: just use ondemand.saucelabs.com, port 80.

The JSON configuration

To use our service, you'll also need to specify OnDemand-specific information, including your username and access key, and the browser environment you wish to test against. We've designed Sauce OnDemand to be a seamless replacement for any regular Selenium RC server, so the way to provide all this information is by using selenium's "browser" parameter, which generally is a string in the form "*browser" (e.g. "*iexplore", "*firefox"), but will now need to be a full JSON object like this: 

'{"username": "your username here", 
  "access-key": "your access key here", 
  "os": "Linux", 
  "browser": "firefox", 
  "browser-version": "3."}'

Click here for a complete list of supported OS/browser/version combos.

Test Examples

PHP | Python | Ruby | Java | Perl | C#

Name your jobs

To make it easier to our users to find and identify each test they run (which for OnDemand are called jobs), we have an options JSON key you can provide along with the rest of the information: 

"job-name": "My job's name"

Disable Video Recording

Sauce Labs records a video of every test you run. If a test fails, it can be useful to see what actually happened on screen to rule out obvious issues, like a pop-up dialog window appearing unexpectedly. Alternatively, when a test passes, you can show the video to other team members as visual confirmation that the feature works (or still works!). However, there is a small performance penalty for screen recording during a test run. You can avoid this penalty by optionally turning off the recording feature.

To turn off video recording, add this to the JSON browser string:

"record-video": false

Enable User Extensions

User extensions are available for custom selenium functionality on the OnDemand service. As far as the file is served in an availabled server (public or tunneled), we will download it and use it in your test. Both HTTP and FTP are supported.

You can optionally provide a list of extensions and all will be loaded. 

"user-extensions-url": "http://saucelabs.com/ext/flex.js"
"user-extensions-url": "ftp://username:password@server.com/bleh.js"
"user-extensions-url": ["http://saucelabs.com/ext/flex.js", "ftp://username:password@server.com/bleh.js"]

Enable a Custom Firefox Profile

Custom Firefox profiles are available; allowing you to customize the Firefox browser on the OnDemand service.

The profile needs to be formatted as the zipped contents of the Firefox profile directory you wish to use. Additionally, it needs to be served from an accessible URL similar to user-extensions.

* Note: If you actually zip the directory it will not work, the zip file needs to contain the contents of the profile, not a directory of the contents of the file. 

"firefox-profile-url": "http://saucelabs.com/example_files/rce.zip"
"firefox-profile-url": "ftp://username:password@server.com/my_profile.zip"

Maximum Test Duration

As a safety measure to prevent broken tests from running indefinitely, Sauce Labs limits the duration of tests to 30 minutes by default. You can adjust this limit per job.

To set a custom maximum duration in seconds, provide an integer value in the JSON browser string. Here's an example for setting a 5-minute maximum: 

"max-duration": 300

Accessing Intranet Applications

To enable the Sauce-hosted tests to execute against your local application under test (AUT), just open up a publicly-accessible port somewhere for access to the application under test, and use that as the base URL for Selenium. If you're not comfortable opening up your app on a public port for the duration of the test, you could use HTTP Basic Auth to protect it, or use our secure end-to-end tunneling API.

How to Find Videos by Job ID

In Selenium RC, when a client requests a new browser session, the server returns a session id, which is appended to all further API calls for that sesssion. The session id is stored as a member variable of the instantiated selenium object, and named "sessionId" or "session_id", depending on the RC client library language. At Sauce Labs, we use that session id as the job id for recording videos viewable at saucelabs.com.

To view the video of a particular test run, you will first need to note the session id locally, usually by writing it to a log file. Then, login to your account at https://saucelabs.com/jobs, and in the "jobs completed" column, look for the job id that matches the session id.

Alternatively, you can create a url to go directly to the video viewing page, by following the url scheme: http://saucelabs.com/jobs/<jobid>, replacing "<jobid>" with the actual job id.

Note that currently the Java libarary does not provide access to the session id. However we store selenium.sessionId JavaScript variable which you can access using getEval.

How to Find Server Logs

Selenium RC keeps detailed log data during each test run. At Sauce Labs, we store this log data and make it available to you online.

To view the server log of a particular test run, you will first need to note the session id for the test run in question. (See How to Find Videos by Job ID for information on session ids.) Then, login to your account at https://saucelabs.com/jobs, and in the "jobs completed" column, look for the job id that matches the session id. On the job page, you can view the log file by clicking the link "selenium-server.log", which should be just below the video window.

Downloading Video and Logs

You can download all log and video files after every test run using the Sauce Labs REST API.

The following files are created:

Make a request matching the following pattern:

GET https://saucelabs.com/rest/<username>/jobs/<job_id>/results/<file_name>

Sauce uses HTTP Basic Authentication. Each request needs to include an Authorization HTTP header with your username and access key.

Real-world example using curl to download selenium-server.log: 

$ curl -u jhuggins:763a23a1-91e1-4f6b-be79-oiu722855hvh \
 
     https://saucelabs.com/rest/jhuggins/jobs/2z234fd4c4006b1e73faf3fa3cdadc75/results/selenium-server.log \

     --output selenium-server.log

Integrating videos with CI test results

We offer a simple supported way to embed videos in CI results. 

<script src="http://saucelabs.com/video-embed/<job id>.js?username=<username>&access_key=<access key>"/>

Of course you need to replace the username and access-key with your own.

Getting Help

We're still working to extend and improve our documentation, so if this document has left you with any doubts, you will find more info in our wiki and you can always ask for help and even contribute in our user forums.