Setting up environment for Cucumber BDD Rails

4 min read

(For more resources related to this topic, see here.)

Getting ready

This article will focus on how to use Cucumber in daily BDD development on the Ruby on Rails platform. Please install the following software to get started:

  • Ruby Version Manager
  • Version 1.9.3 of Ruby
  • Version 3.2 of Rails
  • The latest version of Cucumber
  • A handy text editor; Vim or Sublime Text

How to do it…

To install RVM, bundler, and Rails we need to complete the following steps:

  1. Install RVM (read the latest installation guide from ).

    $ curl -L | bash -s stable --ruby

  2. Install the latest version of Ruby as follows:

    $ rvm install ruby-1.9.3

  3. Install bundler as follows:

    $ gem install bundler

  4. Install the latest version of Rails as follows:

    $ gem install rails

Cucumber is a Ruby gem. To install it we can run the following command in the terminal:

  1. Cucumber contains two parts: features and step definitions. They are explained in the following section:

    $ gem install cucumber

  2. If you are using bundler in your project, you need to add the following lines into your Gemfile:

    gem 'cucumber'

How it works…

We will have to go through the following files to see how this recipe works:

  • Feature files (their extension is .feature): Each feature is captured as a “story”, which defines the scope of the feature along with its acceptance criteria. A feature contains a feature title and a description of one or more scenarios. One scenario contains describing steps.
  • Feature: A unique feature title within the project scope with a description. Its format is as follows:

    Feature: <feature title>
    <feature description>

  • Scenario: This elaborates how the feature ought to behave. Its format is as follows:

    Scenario: <Scenario short description>
    Given <some initial context>
    When <an event occurs>
    Then <ensure some outcomes>

  • Step definition files: A step definition is essentially a block of code associated with one or more steps by a regular expression (or, in simple cases, an exact equivalent string).

    Given "I log into system through login page" do
    visit login_page
    fill_in "User name", :with => "wayne"
    fill_in "Password", :with => "123456"
    click_button "Login"

When running a Cucumber feature, each step in the feature file is like a method invocation targeting the related step definition. Each step definition is like a Ruby method which takes one or more arguments (the arguments are interpreted and captured by the Cucumber engine and passed to the step method; this is essentially done by regular expression). The engine reads the feature steps and tries to find the step definition one by one. If all the steps match and are executed without any exceptions thrown, then the result will be passed; otherwise, if one or more exceptions are thrown during the run, the exception can be one of the following:

  • Cucumber::Undefined: Step was an undefined exception
  • Cucumber::Pending: Step was defined but is pending implementation
  • Ruby runtime exception: Any kind of exception thrown during step execution

Similar with other unit-testing frameworks, Cucumber runs will either pass or fail depending on whether or not exception(s) are thrown, whereas the difference is that according to different types of exceptions, running a Cucumber could result in the following four kinds:

  • Passed
  • Pending
  • Undefined
  • Failed

The following figure demonstrates the flow chart of running a Cucumber feature:

There’s more…

Cucumber is not only for Rails, and the Cucumber feature can be written in many other languages other than English.

Cucumber in other languages/platforms

Cucumber is now available on many platforms. The following is a list of a number of popular ones:

  • JVM: Cucumber-JVM
  • .NET: SpecFlow
  • Python: RubyPython, Lettuce
  • PHP: Behat
  • Erlang: Cucumberl

Cucumber in your mother language

We can actually write Gherkin in languages other than English too, which is very important because domain experts might not speak English. Cucumber now supports 37 different languages.

There are many great resources online for learning Cucumber:


In this article we saw what is Cucumber, how to use Cucumber in daily BDD development on the Ruby on Rails, how to install RVM, bundler, and Rails, running a Cucumber feature, and Cucumber in different language and platform.

Resources for Article :

Further resources on this subject:


Please enter your comment!
Please enter your name here