Skip to content
This repository

This is the Ruby client adapter for testing with Sauce Labs, a Selenium-based browser testing service (saucelabs.com).

README.markdown

Sauce for Ruby

Build Status Dependency Status

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.

Installation

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

RSpec

$ 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

Test::Unit

Create test/sauce_helper.rb with your desired config, and require sauce_helper in your test_helper.rb

Cucumber

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

Using the gem

RSpec

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.

Run tests locally or remotely

A suggestion of how to run tests locally or remotely is available at the Swappable Sauce wiki page.

Capybara

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.

Inside an RSpec Example (tagged with :sauce => true)

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.

Outside an RSpec Example (tagged with :js => true)

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

With Sauce Connect

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

Cucumber

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.

Test::Unit

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

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)".

Running your tests

Setting Up The Platform Array

## Somewhere loaded by your test harness -- spec/sauce_helper or features/support/sauce_helper.rb
Sauce.config do |c|
  c.browsers = [
    ["Windows 7","Firefox","18"],
    ["Windows 7","Opera","11"]
  ]
end

Run tests in Parallel (Highly recommended)

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

Run against several browsers in series

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.

Network Mocking

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 our server at ondemand.saucelabs.com.

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

Reporting Results

RSpec 2, Test::Unit and Cucumber

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.

Running tests against firewalled servers

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 |c|
  c[: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.

Full configuration details

Check out the for a full list of configuration options and details.

This also details how to customise application/tunnel setup.

Suggested Toolchain

The Sauce gem has been optimized to work most effectively with RSpec.

Troubleshooting

Check the Troubleshooting Guide

Contributing to the Gem

  • 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 by connect,rspec or testunit 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.

Testing the Gem

Running the full test suite will require RVM

  • Set SAUCE_USERNAME and SAUCE_ACCESS_KEY in your environment to valid Sauce credentials or create an ondemand.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.

References

  • 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!

Bitdeli Badge

Something went wrong with that request. Please try again.