Skip to content


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP


Gregor Wolf edited this page · 141 revisions

The official Cucumber web site has some more marketing blurbs and CukeTV episodes!

Cucumber is a tool that executes plain-text functional descriptions as automated tests. The language that Cucumber understands is called Gherkin. Here is an example:

Feature: Search courses
  Courses should be searchable by topic
  Search results should provide the course code

  Scenario: Search by topic
    Given there are 240 courses which do not have the topic "biology"
    And there are 2 courses, A001 and B205, that each have "biology" as one of the topics
    When I search for "biology"
    Then I should see the following courses:
      | Course code |
      | A001        |
      | B205        |

While Cucumber can be thought of as a “testing” tool, the intent of the tool is to support BDD. This means that the “tests” (plain text feature descriptions with scenarios) are typically written before anything else and verified by business analysts, domain experts, etc. non technical stakeholders. The production code is then written outside-in, to make the stories pass.

Cucumber itself is written in Ruby, but it can be used to “test” code written in Ruby or other languages including but not limited to Java, C# and Python. Cucumber only requires minimal use of Ruby programming and Ruby is easy, so don’t be afraid even if the code you’re developing in is not Ruby.

Getting started

Install Cucumber using Rubygems.

Take a look at the examples. In each subdirectory you can run the cucumber command. If an example directory has a Rakefile, run rake -T to see what rake tasks are available.

You’ll see feature files printed in green indicating passing tests. Now go into the code the features describe and deliberately make a bug. Run the features again. Note that the backtrace (stack trace) also shows you the line of the plain text feature that fails.

There are several ways to get yourself started in writing tests, depending somewhat on the architecture of your application. Digest Cucumber Backgrounder first (especially if you work with Rails). Then you might want to read more about Gherkin, the Cucumber language and peek into specific topics (below) regarding the various aspects of setting up Cucumber.

Tap to the blogosphere via Tutorials and Related Blog Posts.

Developing with Cucumber and BDD

Once you have set up Cucumber in your project you can get down to action.

When you decide you want to add a new feature or fix a bug, start by writing a new feature or scenario that describes how the feature should work. Don’t write any code (yet).

Now run the features again. The one you wrote should have yellow, pending steps – or failing, red ones. (If you don’t get that you’re doing something wrong, or the feature is already implemented).

This is when you start writing code. Start by writing a couple of lines of code to address the failure you got from Cucumber. Run cucumber again. Repeat and rinse until you’re happy with your feature. When you get down to nitty gritty details, drop down one abstraction level and use RSpec, or any Ruby testing framework, to write some specs/tests for your classes. Write the specs first! If you follow this process you have a good guard against brittle, unmaintainable, undocumented code that nobody understands. (Yes, features and specs are documentation too).

If you think this sounds annoying, try it out anyway. You’ll end up writing better, less coupled (and less) code this way. Trust me. Work outside-in (the outside being the feature, the inside being the low level code). Do it the BDD way.

Business value and MMF

You should discuss the “In order to” part of the feature and pop the why stack max 5 times (ask why recursively) until you end up with one of the following business values:

  • Protect revenue
  • Increase revenue
  • Manage cost
  • Increase brand value
  • Make the product remarkable
  • Provide more value to your customers

If you’re about to implement a feature that doesn’t support one of those values, chances are you’re about to implement a non-valuable feature. Consider tossing it altogether or pushing it down in your backlog. Focus on implementing the MMFs (Minimum Marketable Features) that will yield the most value.

Here is an example taken from an IRC chat session in #cucumber:

[5:08pm] Luis_Byclosure: I'm having problems applying the "5 Why" rule, to the feature 
                         "login" (imagine an application like youtube)
[5:08pm] Luis_Byclosure: how do you explain the business value of the feature "login"?
[5:09pm] Luis_Byclosure: In order to be recognized among other people, I want to login 
                         in the application (?)
[5:09pm] Luis_Byclosure: why do I want to be recognized among other people?
[5:11pm] aslakhellesoy:  Why do people have to log in?
[5:12pm] Luis_Byclosure: I dunno... why? 
[5:12pm] aslakhellesoy:  I'm asking you
[5:13pm] aslakhellesoy:  Why have you decided login is needed?
[5:13pm] Luis_Byclosure: identify users
[5:14pm] aslakhellesoy:  Why do you have to identify users?
[5:14pm] Luis_Byclosure: maybe because people like to know who is 
                         publishing what
[5:15pm] aslakhellesoy:  Why would anyone want to know who's publishing what?
[5:17pm] Luis_Byclosure: because if people feel that that content belongs 
                         to someone, then the content is trustworthy
[5:17pm] aslakhellesoy:  Why does content have to appear trustworthy?
[5:20pm] Luis_Byclosure: Trustworthy makes people interested in the content and 
                         consequently in the website
[5:20pm] Luis_Byclosure: Why do I want to get people interested in the website?
[5:20pm] aslakhellesoy:  :-)
[5:21pm] aslakhellesoy:  Are you selling something there? Or is it just for fun?
[5:21pm] Luis_Byclosure: Because more traffic means more money in ads
[5:21pm] aslakhellesoy:  There you go!
[5:22pm] Luis_Byclosure: Why do I want to get more money in ads? Because I want to increase 
                         de revenues.
[5:22pm] Luis_Byclosure: And this is the end, right?
[5:23pm] aslakhellesoy:  In order to drive more people to the website and earn more admoney, 
                         authors should have to login, 
                         so that the content can be displayed with the author and appear 
                         more trustworthy.
[5:23pm] aslakhellesoy:  Does that make any sense?
[5:25pm] Luis_Byclosure: Yes, I think so
[5:26pm] aslakhellesoy:  It's easier when you have someone clueless (like me) to ask the 
                         stupid why questions
[5:26pm] aslakhellesoy:  Now I know why you want login 
[5:26pm] Luis_Byclosure: but it is difficult to find the reason for everything
[5:26pm] aslakhellesoy:  And if I was the customer I am in better shape to prioritise this 
                         feature among others
[5:29pm] Luis_Byclosure: true!

Outcomes and bottom-up scenarios

The value provided by a system is what you can get out of it – not what you put into it (Chris Matts said that). Just like the value is expressed at the top of a feature (In order to…), the value should be in the steps of a scenarios too, more precisely in the Then steps.

When you’re writing a new scenario, I recommend you start with the formulation of the desired outcome. Write the Then steps first. Then write the When step to discover the action/operation and finally write the Given steps that need to be in place in order for the When/Then to make sense.

Read more about Given-When-Then and Gherkin in general.


Something went wrong with that request. Please try again.