Ruby Tools

This page describes tools for a Ruby or Ruby on Rails environment.

Build tools

Cucumber can be run in several ways. Be aware that rake cucumber, cucumber features, and autotest with ENV AUTOFEATURE=true do not necessarily produce the same results given the same features and step definitions.


Running rake cucumber from the command line provides the simplest method to run Cucumber tests.

Using Rake requires a Rakefile with a features task definition. For example:

require 'rubygems'
require 'cucumber'
require 'cucumber/rake/task' do |t|
  t.cucumber_opts = "--format pretty" # Any valid command line option can go here.

This will run all the Features with the pretty formatter.

Note, how we use the cucumber_opts accessor to define our arguments passed to Cucumber.

If you are using Ruby on Rails, this task is defined for you already.

Now you can run Cucumber with Rake:

rake features

The rake script provided with Cucumber performs much of the background magic required to get the test database and requisite libraries properly loaded. In fact, an important habit to acquire is to run Cucumber as a rake task immediately after performing a migration. This ensures that the test database schema is kept in sync with the development database schema. You can achieve the same effect by running rake db:test:prepare before your first Cucumber run following a migration but developing the habit of just running rake cucumber or rake cucumber:wip is probably the better course.

The Cucumber Rake task recognises the @wip Tag, so rake cucumber:wip will run only those scenarios tagged with @wip.

For example, given a feature file containing:

Feature: .  .  .

  Scenario: A

  Scenario: B

  Scenario: C

Then running the command rake cucumber:wip will run the Steps contained inside Scenario B only, while running rake cucumber:ok will run the Steps within all Scenarios other than B.

Using Profiles in Rake Tasks

For complex Feature runs that are tested often, it is nice to save the command line arguments as Cucumber profiles.

Once you have some profiles defined, you can use them in your Rake tasks, like so:

require 'rubygems'
require 'cucumber'
require 'cucumber/rake/task'

namespace :features do do |t|
    t.profile = "webrat"
  end do |t|
    t.profile = "selenium"

Guarding Your production machines From Cucumber

Since Rake tasks are used on development and productions systems, it is generally a good idea to place a guard around your Cucumber task so your productions boxes don’t need to install Cucumber.

Below is an example of how to do this. This example is the Rake task that Cucumber generates for Rails projects, but the same idea applies to any project using Cucumber and Rake:

require 'rubygems'

  require 'cucumber'
  require 'cucumber/rake/task' do |t|
    t.cucumber_opts = "--format pretty"

  task features: 'db:test:prepare'
rescue LoadError
  desc 'Cucumber rake task not available'
  task :features do
    abort 'Cucumber rake task is not available. Be sure to install cucumber as a gem or plugin'

Ruby on Rails


cucumber-rails is a RubyGem which brings Ruby on Rails Generators for Cucumber with special support for Capybara and DatabaseCleaner.


The cucumber:install generator sets up Cucumber in your Rails project. It generates the necessary files in the features/ directory. After running this generator you will also get a new rake task called cucumber.

For more details, see rails generate cucumber:install --help.


By default, cucumber-rails runs DatabaseCleaner.start and DatabaseCleaner.clean before and after your Cucumber scenarios. This default behavior can be disabled. See the cucumber-rails README for details.


To learn more of the tools being integrated and assisted by cucumber-rails, see the READMEs of DatabaseCleaner and Capybara.

You can help us improve this documentation. Edit this page.