Configuration The (in)Complete Guide

Basic Configuration

Sauce.config

Configuration for the Sauce gem is done with the Sauce.config class. The most common way to interact with this class is with a block:

Sauce.config do |config|
  config[:name] = "An example of Sauce::Config"
  config[:start_tunnel] = true
end

Working with the configuration class

There is one global Config class which is used to configure all of the built in integrations (RSpec, Cucumber, Test::Unit, Capybara, Selenium2). It's returned by Sauce.get_config.

You can access configuration options individually (with hash accessors), or as a group (with opts):

Sauce.config do |config|
  config[:name] = "This is the configured name"
  config[:browser] = "Firefox"
end

Sauce.get_config[:name]              #  =>  "This is the configured name"
Sauce.get_config[:browser]= "Opera"  #  =>  Opera is now the configured browser

Sauce.get_config.opts                #  =>  {:name => "This is the configured name", :browser> "Opera"}

Creating custom configurations

You can over-ride the global configuration by calling Sauce::Config.new directly.

If you pass a hash of options, all options in the YAML configuration file or the Environment are set first, then all the hash's options are set (and the previously set options are over-ridden, if relevant).

If you pass nothing, only the YAML and Environment options are set. If you pass false, nothing is configured.

Given this yaml file:

name: "I'm the YAML file"
build: "YAML Build 14"

Config works like this:

options_hash = {:name => "I'm the options hash"}

empty_config = Sauce::Config.new(false)
empty_config.opts  #  => {}

env_config = Sauce::Config.new
env_config.opts    #  => {:name => "I'm the YAML file", :build => "YAML Build 14"}

hash_config = Sauce::Config.new(options_hash)
hash_config.opts   #  => {:name => "I'm the options hash, :build => "YAML Build 14}

Configuring from external sources

Configuration can also be done from a YAML file or via Environment variables, as well as from a Heroku environment.

The gem will load from the following sources in turn, and each option set will override any previous value:

1. YAML
2. Environment Variables
3. Heroku Environment
4. Passed in options

Environment Variables

Any environment variable starting with "SAUCE_" will be converted into an option and set. Additionally, some options have aliases, which are listed below.

YAML File

Sauce::Config can load variables from a simple YAML config file. The gem searches for a file called 'ondemand.yml', stopping with the first one it finds:

1. PROJECT_ROOT/ondemand.yml
2. PROJECT_ROOT/config/ondemand.yml
3. __ FILE__/../../../ondemand.yml
4. ~/.sauce/ondemand.yml

Each key is converted directly to a symbol (with to_sym)

job_name = "A YAML Job" #=> :job_name
host = "bees.oprah.com" #=> :host

See below for a full list of options.

Heroku

COMING SOON

Authentication

We recommend setting your credentials in environment variables, so they're seamlessly available to all Sauce Labs related tools (and you don't accidentally check them into source control OR have to configure them for all projects):

SAUCE_USERNAME=YourSauceUserName
SAUCE_ACCESS_KEY=YourSauceAccessKey

Platforms

Single Platforms

# Set up a test on Windows 7 with IE 9
Sauce.config do |config|
  config[:os] = "Windows 7"
  config[:browser] = "Internet Explorer"
  config[:browser_version] = "9"
end

Alternatively, you can set the :browsers property in the config object to a single array, much like configuring multiple platforms.

Sauce.config do |config|
  config[:browsers] = ["Windows 7", "Internet Explorer", "9"]
end

Multiple Platforms

You can run each individual test/spec against multiple browsers by configuring the browser array. This requires you to have set up your tests properly for RSpec or Test::Unit integration (See the Readme).

Sauce.config do |config|
  config[:browsers] = [
    ["Windows 7", "Internet Explorer", "9"],
    ["Linux", "Firefox", "19"],
    ["OSX 10.6", "Chrome", nil]
  ]
end

Check out the list of all available platforms here

###Note about Chrome When using Chrome, you must set the version to nil.

Connectivity

Sauce::Connect

Sauce::Connect is the simple to use tunnelling tool, designed to allow Sauce Labs' secure infrastructure access to the machines under test. A tunnel will automatically be opened whenever your tests are run.

Disable Sauce::Connect

To Prevent Sauce::Connect starting (if you already have a tunnel running OR your application is not behind a firewall), you can set [:start_tunnel] to false.

Sauce.config do |config|
  config[:start_tunnel] = false
end

Override the Sauce::Connect endpoint

You can override the Sauce::Connect endpoint. This is helpful for tunnelling to staging servers.

Sauce.config do |config|
  config[:application_host] = "10.0.0.132"
  config[:application_port] = "333"
end

Starting the local application

When configured within RSpec and Test::Unit correctly, the gem tries to determine if it's being run against a Rails application. If it is, it will try to start the app before running tests. This behaviour can be disabled.

Sauce.config do |config|
  config[:start_local_application] = false
end

All The Things

Option	Purpose	ENV Key	Aliases
:username	Sauce Labs Username	SAUCE_USERNAME	SAUCE_USER_NAME
:access_key	Sauce Labs Access key	SAUCE_ACCESS_KEY	SAUCE_API_KEY
:application_host	Hostname for Sauce::Connect to tunnel to	SAUCE_APPLICATION_HOST
:application_port	Port for Sauce::Connect to tunnel to	SAUCE_APPLICATION_PORT
:browser	Browser to use during session	SAUCE_BROWSER	SAUCE_BROWSER
:browsers	Array of Platforms to test against	SAUCE_BROWSERS	SAUCE_ONDEMAND_BROWSERS
:browser_version	Version of Browser to use during session	SAUCE_BROWSER_VERSION
:build	Build this session is for	BUILD_NUMBER	TRAVIS_BUILD_NUMBER, CIRCLE_BUILD_NUMBER
:firefox_profile_url	Location of the profile to start Firefox with	SAUCE_FIREFOX_PROFILE_URL
:job_name	Name to give this job in Sauce Labs	SAUCE_JOB_NAME	JOB_NAME
:user_extensions_url	URL of user extensions to start Firefox with	SAUCE_USER_EXTENSIONS_URL
:os	Operating system to use during session	SAUCE_OS
:start_local_application	Boolean - Whether to start local Rails instance or not	SAUCE_START_LOCAL_APPLICATION
:start_tunnel	Boolean - Whether to start Sauce::Connect	SAUCE_START_TUNNEL