Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Cucumber and Capybara

DylanLacey edited this page · 11 revisions


Cucumber is a behavior-driven development framework that, when coupled with Capybara, provides a very good foundation for writing acceptance tests that use Sauce Labs. This guide assume you've already got a handle on Cucumber, and you're now wanting to write tests against Sauce Labs' cloud.

In order to use Capybara with Cucumber on Sauce Labs, you'll need to install the 'sauce-cucumber' and 'capybara' gems and add them to your features/support/env.rb

gem install sauce-cucumber
gem install capybara
# Inside features/support/env.rb
require 'capybara/cucumber'
require 'sauce/cucumber'

The integration is enabled by way of the @selenium tag in Cucumber. For example's sake, let's write a quick Feature for some of DuckDuckGo's !bang syntax

@selenium @ddg
Feature: Search for Ruby gems with !rubygems
  As a Ruby developer
  In order to quickly find fancy gems
  The '!rubygems <gemname>` query should take me directly to fancy gems

  Scenario: Finding the Sauce gem
    Given I am on the DDG homepage
    When I search for "!rubygems sauce"
    Then I should see an exact match on the Ruby Gems search page

In the above example, the Sauce gem will handle wrapping the entire "Finding the Sauce gem" scenario with the necessary hooks to install a custom Capybara driver and report the necessary job information to Sauce Labs.

For completeness' sake, here are some matching step definitions for the above scenario

Given /^I am on the DDG homepage$/ do
  visit ''

When /^I search for "([^\"]*)"$/ do |query|
  @query = query
  fill_in 'q', :with => query
  click_button "search_button_homepage"

Then /^I should see an exact match on the Ruby Gems search page$/ do
  gem_name = @query.split(' ').last
  page.should have_selector("a[href='/gems/#{gem_name}']")

Integrating with Cucumber/Rails

Check The Docs Here

Testing internal sites

The Sauce gem contains supports Sauce Connect out of the box, but it is disabled by default for Cucumber+Capybara integration.

Enabling Sauce Connect will slow down your tests, but can provide greater flexibility for testing against a local development server.

Add the following line to your features/support/env.rb to enable Sauce Connect:

Sauce.config do |c|
  c[:start_tunnel] = true

The :start_tunnel setting will start Sauce Connect at the beginning of a cucumber run, and tear it down when cucumber exits. Since this will slow down the speed in which you are able to iterate on tests, it is recommended that you use a long-running Sauce Connect tunnel. Execute sauce connect in another terminal, and update your env.rb to read:

Sauce.config do |c|
  c[:start_tunnel] = !(ENV['DISABLE_TUNNEL'] == '1')

Then you can invoke cucumber with:

DISABLE_TUNNEL=1 cucumber features/killerapp.feature

It will use the Sauce Connect tunnel you have running in another terminal, greatly reducing the cycle-time for running cucumber


My Tests are tagged with '@selenium' but they're still running locally

This sounds like a collision between the sauce-cucumber gem and capybara's cucumber integration. Check out the Cucumber Rails Integration docs.

Something went wrong with that request. Please try again.