Cucumber and Capybara

Introduction

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 'http://duckduckgo.com'
end

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

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}']")
end

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
end

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')
end

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

Issues

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.