This is the Ruby client adapter for testing with Sauce Labs, the multi-platform, multi-device testing service. The gem supports opening Sauce Connect tunnels, starting Rails applications, and most importantly, running your tests in parallel across multiple platforms.
Be sure to check the wiki for more information, guides and support.
# Gemfile
gem "sauce"
gem "sauce-connect" # Sauce Connect is required by default.
$ bundle install
Configure your access credentials as environment variables:
SAUCE_USERNAME= Your Username
SAUCE_ACCESS_KEY = Your Access Key, found on the lower left of your Account page (NOT your password)
If environment variables aren't your thing, check out the (in)Complete guide to Configuration for other options.
The Sauce gem does not currently support WebDriver 3.0 style capabilities correctly. This means that the gem can not be used to run tests against sessions using Appium 1.0 and above, including mobile browser tests.
$ bundle exec rake sauce:install:spec
Tag each example group you wish to use Sauce to run with :sauce => true
:
describe "A Saucy Example Group", :sauce => true do
it "will run on sauce" do
# SNIP
end
end
Place your Sauce.config block in spec_helper.rb
Create test/sauce_helper.rb with your desired config, and require sauce_helper
in your test_helper.rb
## Gemfile
gem "sauce-cucumber", :require => false
gem "sauce"
$ bundle install
$ bundle exec rake sauce:install:features
Edit features/support/sauce_helper.rb with your desired config.
Tag your Sauce-intended features with @selenium
.
Every test with Sauce behaviour included gets access to its own selenium driver, already connected to a Sauce job and ready to go.
This driver is a Sauce subclassing of the Selenium driver object, and responds to all the same functions.
It's available as page
, selenium
and s
, eg
describe "The friend list", :sauce => true do
it "should include at least one friend" do
page.navigate_to "/friends"
page.should have_content "You have friends!"
end
end
We recommend, however, the use of Capybara for your tests.
If it guesses you're in a Rails project, the gem will spin up your Rails server (because it's needed for tests); If you're using a separate server, or your specs already start one, you can prevent this in your Sauce Config:
Sauce.config do |config|
config[:start_local_application] = false
end
A suggestion of how to run tests locally or remotely is available at the Swappable Sauce wiki page.
The gem provides a Capybara driver that functions mostly the same as the existing Selenium driver.
## In your test or spec helper
require "capybara"
require "sauce/capybara"
# To run all tests with Sauce
Capybara.default_driver = :sauce
# To run only JS tests against Sauce
Capybara.javascript_driver = :sauce
You can now use Capybara as normal, and all actions will be executed against your Sauce session.
If you're running from inside an RSpec example tagged with :sauce => true, the @selenium
object and the actual driver object used by the Sauce driver are the same object. So, if you need access to the Selenium Webdriver when using Capybara, you have it.
You'll get automagic job creation and destruction, job naming and all our nice platform support using Capybara like this.
If you're not using the RSpec hooks, Capybara will use a single Sauce Labs job until your tests exit. You can force Capybara to close your session (and then start another):
Capybara.current_session.driver.finish!
Capybara.reset_sessions!
When used like this, you won't get any of the shiny serial platform support that the :sauce tag provides; You'll have to use our REST API to name your jobs (Possibly using Sauce_Whisk and your specs will only operate on the first platform you've specified.
Sauce Connect automatically proxies content on certain ports; Capybara.server_port will be set to a value suitable for use with Sauce Connect by default. If you want to use a specific port, using one of these will allow Sauce Connect to tunnel traffic to your local machine:
Capybara.server_port = an_appropriate_port
# Appropriate ports: 80, 443, 888, 2000, 2001, 2020, 2222, 3000, 3001, 3030, 3333, 4000, 4001, 4040, 4502, 4503, 5000, 5001, 5050, 5555, 6000, 6001, 6060, 6666, 7000, 7070, 7777, 8000, 8001, 8003, 8031, 8080, 8081, 8888, 9000, 9001, 9080, 9090, 9999, 49221
The sauce-cucumber
gem works best with Capybara. Each "@selenium" tagged feature automatically sets the Capybara driver to :sauce. All tagged features can simply use the Capybara DSL directly from step definitions:
## a_feature.rb
@selenium
Feature: Social Life
Scenario: I have one
Given Julia is my friend
## SNIP ##
## step_definition.rb
Given /^(\w+) is my friend$/ do |friends_name|
visit "/friends/#{friends_name}"
end
For more details, check out the wiki page, Cucumber and Capybara.
To get sweeeeet Saucy features like job status updating, subclass Sauce::TestCase
or Sauce::RailsTestCase
.
Sauce::TestCase
is a subclass of Test::Unit::TestCase
, for simple test cases without anything extra.
Sauce::RailsTestCase
is a subclass of ActiveSupport::TestCase
so you can use all the associated ActiveSupport goodness.
Each test will have access to a fresh Sauce VM, already running and ready for commands. The driver is a subclass of the Selenium::WebDriver class, and responds to all the same functions. It can be accessed with the page
, s
and selenium
methods.
## test/integration/some_test.rb
require "test_helper"
class FriendList < Sauce::TestCase
def test_the_list_can_be_opened
page.navigate.to "/friends"
page.should have_content "You have friends!"
end
end
We still recommend the use of Capybara, see above.
Uploading files in Selenium is done by calling send_keys
on a File input element, with the filename as the first parameter.
Remote uploads usually require you to create a File Detector and pass it to the Driver after initialization.
The gem takes care of this for you, so uploading files from your local machine during tests should "JustWork(tm)".
The browsers
array from Sauce.config
takes individual arrays, each representing a single platform to test against. Each array is in the form [platform_name_and_version, browser_name, browser_version]
.
## Somewhere loaded by your test harness -- spec/sauce_helper or features/support/sauce_helper.rb
Sauce.config do |config|
config[:browsers] = [
["Windows 7","Firefox","18"],
["Windows 7","Opera","11"]
]
end
The values for the browsers
array are terse versions of the capabilities generated by the Sauce Labs Platform Configurator; Use the 'platform' and 'version' capabilities directly, and use the name of the object you request from Selenium::WebDriver::Remote::Capabilities
as the browser name. For example:
### Platforms Configurator
caps = Selenium::WebDriver::Remote::Capabilities.chrome
caps['platform'] = 'OS X 10.10'
caps['version'] = '39.0'
### Is equivalent to
["OS X 10.10", "chrome", "39.0"]
All the standard Selenium & Sauce capabilities are accessible from the Sauce.config block. Some filtering is done to exclude nonsense caps. If you need to add a capability that's not already allowed (those in Sauce::Config::SAUCE_OPTIONS
), you can add it to the whitelist:
Sauce.config do |config|
# Build is already allowed
config[:build] = "9001AMeme"
# Shiny is not allowed yet
config.whitelist 'shiny'
config['shiny'] = "Something"
end
To set a capability for a single platform, add it as a hash to the end of the platform's array:
Sauce.config do |config|
config.browsers = [
["Windows 7", "Firefox", "18"],
["Windows 7", "Chrome", 30, {:build => 'ChromeTastic'}]
]
$ bundle exec rake sauce:spec
$ bundle exec rake sauce:features
This will run your RSpec tests or Cucumber features against every platform defined, across as many concurrent Sauce sessions as your account has access too.
You can pass arguments to these tasks to control concurrency, specs/features to run and commandline arguments.
# Run login\spec across all platforms with up to 8 concurrent specs
$ bundle exec rake sauce:spec concurrency=8 test_files="spec/login_spec.rb"
# Run report.feature across all platforms with up to 3 concurrent features
$ bundle exec rake sauce:features concurrency=3 features="features/report.feature"
Check out the Parallisation guide for more details.
As long as your tests are correctly tagged (See installation, above), running them without the rake task (eg $ bundle exec rspec
) will run them one at a time, once for every platform requested.
If you're mocking out external network requests, say with WebMock or FakeWeb, you'll need to ensure that requests can still be made to saucelabs.com
, as well as any subdomains.
You'll need to ensure you can make requests to your server as well.
We've provided a helper for WebMock
, which you can include with require 'sauce/webmock'
. This will preserve all the existing config passed to WebMock.disable_net_connect!
, while setting an exception for Sauce's servers. You'll need to include this helper after any other WebMock configuration
If you want full control of your mocking, just include saucelabs.com when allowing domains:
WebMock.disable_net_connect!(:allow => [/saucelabs.com/], "www.example.com")
If integrated with RSpec (as detailed above), the gem will automatically update your jobs' success (or failure) and name using the brand spankin' new SauceWhisk gem.
If your system under test is located behind a firewall, you can use Sauce Connect to run tests through your firewall, quickly and simply.
Sauce Connect is started by default, spinning up a tunnel prior to your tests and closing it down afterwards.
To disable Sauce Connect, set start-tunnel
to false in your Sauce.config block:
Sauce.config do |config|
config[:start_tunnel] = false
end
For details on named tunnels (including why you might want to use them) check out the Using Identified Tunnels with Sauce Connect page.
Check out the for a full list of configuration options and details.
This also details how to customise application/tunnel setup.
The Sauce gem has been optimized to work most effectively with RSpec.
Check the Troubleshooting Guide
- Fork the GitHub project
- Create a branch to perform your work in, this will help make your pull request more clear.
- Write some RSpec tests to demonstrate your desired capability or exhibit the bug you're fixing.
- Run the tests -
rake spec:unit
runs the unit tests,rake spec:
followed byconnect
,rspec
ortestunit
runs that integration test,rake test
runs everything - Make your feature addition or bug fix.
- Commit
- Send a pull request! :)
There is a Mailing List for developers.
The gem contains a logging facility. If left alone, it defaults to creating a Ruby::Logger
that logs at WARN
level to Standard Out. You can inject your own logger:
Sauce.logger= your_logger
Or, if you set the SAUCE_LOGFILE
and SAUCE_LOGLEVEL
environment variables, the gem will create a file logger which logs at that level. Logfiles will be created, appended too and rotated after 10Mb.
In parallel, each logfile will have the number of the parallel process appended to the filename; The rake task will log to the first file. Because of a quirk with how Parallel Tests numbers processes, the 'first' file will have no number, and the second will be numbered 2.
Running the full test suite will require RVM
-
Set
SAUCE_USERNAME
andSAUCE_ACCESS_KEY
in your environment to valid Sauce credentials or create anondemand.yml
in the following format:access_key: <yourkeyhere> username: <yourusernamehere>
-
Invoke
bundle install
to install the gems necessary to work with the Sauce gem -
Running
rake spec:unit
will run the RSpec unit tests -
If you'd like to run the entire test suit,
rake test
will run all the integration tests, but requires the Sauce credentials to be set up properly as these tests will run actual jobs on Sauce.
If you see Exception occured: uninitialized constant Sauce::RSpec::Spec
when requiring the sauce gem in the Rakefile, make sure to require bundler/setup.
require 'bundler/setup'
require 'sauce'
- Cucumber -- Cucumber, the only BDD Framework that doesn't suck.
- Capybara -- Don't handcode webdriver commands.
- SauceWhisk -- Ruby REST API Wrapper for the Sauce API. Fresh New Minty Flavour!