No PhD

I work for Nature Publishing, but I haven't got a PhD

An introduction to Cucumber

leave a comment »

We’re using Cucumber internally at Nature Publishing to define requirements and run integration tests. It’s becoming embedded in the way we drive our development iterations. I wrote this originally as a Wiki page to help introduce the concepts and figured, hey, I might as well share it. So here it is…

Cucumber is a Ruby gem/framework that enables documents written in a structured plain text language to be executed as automated integration tests. As ever, an example is the best way to explain:

Feature: Authenticating users
  In order to manage my account, add events, etc
  As a Organizer
  I want to log in to the service

  Scenario: Log in with invalid login
    Given the following users exist: 
      | email | password | first_name | last_name | title | country |
      | | itsasecret | Bob | Smith | mr | UK |
      And I view the login screen
    When I fill in "email" with ""
      And I fill in "password" with "anothersecret"
      And I press "Log in"
    Then I should view the login screen
      And I should see "Could not log you in as ''"

This definition language is called ‘Guerkin’ and provides a simple, unambiguous manner with which to define a feature, or requirement, of the system. Cucumber allows us take these plain text features descriptions and turn them in to automated tests that ensure a system fulfills the business requirements.


A feature is a discrete chunk of functionality; above, authentication is a good example. Features should not have too wide a remit; “Provide a blogging system” would be too high level. Better would be defining features such as “Adding a comment to a blog post”, etc. Features are comprised of a header, and a series of scenarios.

Feature header

A feature is introduced with a simple header that defines the business benefit for implementing it. You define a feature by saying:

In order to…

“publicise my scientific event to a wide community of scientists, researchers and journalists”

Defines the business benefit to the user of delivering the feature.

As a…

“event organiser”

The role definition; specifies who is the end user wanting to achieve the benefit.

I want to…

“register as an event organiser on”

What the user has to do in order to achieve the perceived benefit.


Each feature is likely to have a number of scenarios. Using authentication as an example, there are several possible user scenarios we need to test. Using unknown logon, supplying the wrong password, logging in correctly, etc. These can all be defined as separate scenarios using Guerkin.

A scenario is defined in terms of steps called given, when or then, and can be comprised of any number of those steps in any order.


A given is a pre-requisite for a user-led action taking place. In order to test a user logging in for instance, an account for that user has to exist. If multiple Givens are required then you use the And term to link them. I.e:

  Given I have an account with email "" with the password "letmein"
    And the account "" has 3 associated comments


A when is typically a user action, or more likely a series of user actions. For web-applications these would be things like clicking on links/buttons, filling in text fields, selecting items from a list, etc.

  When I fill in "email" with ""
    And I fill in "password" with "letmein"
    And I press "Log in"

By default, Cucumber uses a library called Webrat to carry out the actions.


A then defines an outcome; an expected side-effect of the previous actions. Then steps are usually concerned with ensuring the user sees something on a screen, or that an entity has been created in the database.

  Then I should see "Welcome to"
    And I should have a new session

The nice thing about defining scenarios using these simple building blocks is that we can build up complex user stories with ease:

  Scenario: I want to post a free event
  Given the following users: 
    | username | password | enabled |
    | | itsasecret | true |
    And I am logged in as ""
    And I view the homepage
  When I follow "Post an event"
  Then I should see "Please enter your event details"
  When I fill in the new event form
    And I press "Post Event"
  Then I should see "Your event has been submitted for approval"
    And I should be redirected to the event screen
    And there should be a new event
    And an emails should be sent to "" and ""

As was mentioned before, we can use multiple When/Then steps in order to tell a much longer and more compelling user story.

It is worth mentioning that at this point Cucumber does not allow you to “include” a reusable collection of steps in to a scenario; for instance, if you wanted to include a standard set of login steps in to multiple scenarios you’d either have to cut/paste (not very DRY) or define a “super-step” that undertakes them all for you.

Making Guerkin sing

Now Guerkin is very nice and everything, but the true power of Cucumber is to take those feature definitions and turn them in to executable integration tests. You do this by taking each step definition in your features and writing a matching statement in one of your step_definition.rb files. For instance, given a step:

  Given I have an account with email "" and password "letmein"

You would typically create a file under the step_definitions directory (see Setting Cucumber up) called user_steps.rb, and in it would define something like the following:

  Given /I have an account with email "(.*)" and password "(.*)"/ do |email, password|
    User.create(:email => email, :password => password)

As you can see, the step matcher can parameterise information in the step using standard ruby regexp matchers, and these are passed as arguments to the step block. In our simple example the code creates the user referred to in the step so it’s available to subsequent steps.

Using Webrat in your steps

Webrat provides a way of simulating user actions on the browser such as following links, clicking on buttons and entering text in to fields. Webrat is maintained at github.

When you set Cucumber up with Webrat a set of default step definitions is provided in features/step_definitions/webrat_steps.rb. This gives you the ability to do things like:

  When I press "Submit"

Which would be mapped to

  When /^I press "(.*)"$/ do |button|

click_button is a webrat method. Others include follow_link, fill_in and select. You can use these methods in your own actions too. For instance, when defining a scenario including completing a lengthy form, rather than defining each field as a separate step using the webrat_steps helpers, it’s better to define your own “When I complete the form” step, then have:

  When /^I complete the form$/ do
    fill_in "firstname", :with => "Bob"
    fill_in "lastname", :with => "Bob"
    select "mr", :from => "title"

Much neater.

Using tables

Another useful Cucumber construct is the table, also known as a Fixture Input Table (FIT). These enable bulk creation of test data for the scenario. I’ve already shown the use of these, in fact in the original example:

  Scenario: Log in with invalid login
    Given the following users exist: 
      | email | password | first_name | last_name | title | country |
      | | itsasecret | Bob | Smith | mr | UK |

The given step here has a FIT table immediately afterwards. These are simple to define; the first row specifies the attributes to pass, and subsequent rows specify the values for each instance you want to create. The companion step definition might look something like:

Given /the following users exist:/ do |user_table|
  user_table.hashes.each do |attrs|

Each row in the FIT table is turned in to a Ruby hash that maps the column name to the value. These hashes can be used in ActiveRecord object creators as shown above.

FIT tables can also be used in scenario outlines.

Setting Cucumber up

This section tells you how to get your Rails project running with Cucumber.

How do I get it.

The project is maintained on github. To install the gem do the following:

  • If you have not already done so, add to your gem sources:
      gem sources -a
  • Now install the gem:
      sudo gem install aslakhellesoy-cucumber
  • It’s also worth installing webrat (for defining browser actions in your Cucumber features) and rspec (for your unit/functional testing)
      sudo gem install webrat rspec rspec-rails

Setting your Rails app up to use Cucumber

Simply go to your Rails root directory and run:

  ruby script/generate cucumber

This creates the following structure under your Rails project:


Your plain text feature definitions go in the features directory. The step_definitions directory contains the code to map your feature steps to executable test code, and support typically just contains the env.rb file, roughly equivalent to the rspec spec_helper.rb file, or your Rails environment.rb file.

I want more!

This is really a light introduction to Cucumber. You will find a lot more information at the Cucumber Wiki.


Written by spanx

17th July, 2009 at 7:31 pm

Posted in Code

Tagged with , ,

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: