Sauce Labs has some amazing functionality out of the box, but if like me you want a little more control about when your Cucumber/Capybara tests utilise Sauce Labs, then this post may help you out.

The Sauce gem is brilliant. It enables you to easily create an array of browsers that you want your tests to tun in. If you want your tests to run against Sauce Labs and not your default webdriver, all you need to do it mark all tests with the @selenium tag and the Sauce gem will do the rest.

For lots of the time, this may be sufficient, but if you want to easily switch between Sauce Labs and running tests locally, you won’t want to have to manually add in the @selenium tag to all your features. You’ll want to write a hook to turn the gem on and off. You can then wrap the hook in some code that receives an environment variable. When a certain environment variable is passed in, your tests will run against Sauce Labs, leaving the default behaviour as running locally.

This works, but has two drawbacks. Firstly, it means you still need to add in the @selenium tag to all of your scenarios or, at the very least, at the top of all your features. This could be mildly annoying, but is no big deal. However, the deal breaker for this workaround is that @selenium is already an explicit tag used by Capybara to ensure your tests run using Selenium. If, like me, your default webdriver is Capybara Webkit (or indeed any other webdriver), this provides a problem as it will override whatever you’ve specified in your env.rb file.

Fortunately, Sauce Labs has a bunch of helpful developers on hand and, after chatting with Dylan recently, we came up with the following workaround that enables you to run your tests against Sauce Labs whenever you want to and use any other webdriver by default.

This is how it’s done.

Firstly, my starting point was with an existing block of code in my env.rb file that enabled me to pass in an environment variable when I was running my cucumber tests to determine which webdriver I used. Here is my original code:

case ENV['browser']
when 'firefox', 'ff'
  Capybara.default_driver = :selenium
when 'chrome'
  Capybara.default_driver = :selenium_chrome
else
  Capybara.default_driver = :webkit
end

As you can see, the default webdriver is the headless Capybara Webkit, but I could easily switch to Selenium & Firefox with the following command:

cucumber browser=firefox

Now we just need to add in some more code to enable us to pass in another browser type. In our case, it’s Sauce Labs. Here we go:

case ENV['browser']
when 'sauce', 'saucelabs'
  require 'sauce/cucumber'
  require 'sauce/utilities'
  Capybara.default_driver = :sauce

  Before do
    Sauce::Capybara::Cucumber.before_hook
  end

  Around do |scenario, block|
    Sauce::Capybara::Cucumber.around_hook(scenario, block)
  end

  at_exit do
    Sauce::Utilities::Connect.close
  end
when 'firefox', 'ff'
  Capybara.default_driver = :selenium
when 'chrome'
  Capybara.default_driver = :selenium_chrome
else
  Capybara.default_driver = :webkit
end

As you can see, we’ve added a couple of additional require statements, we’ve changed the default driver to Sauce Labs and we’ve included a few hooks.

Firstly, we want the require statements here as they’re not needed unless this code is called. This also means that we can use the existing explicit @selenium tag if we want to, without running against Sauce Labs. The hooks are also here so they’re only run when they need to be. They utilise the code within the Sauce Gem that would normally be called when using the @selenium tag.

With this setup, you can easily switch to running your entire suite of tests against Sauce Labs using the following command:

cucumber browser=sauce

Also, crucially, without passing in any environment variables, you can revert to your default webdriver.

Enjoy!