Home

Cucumber

Cucumber is a tool that can execute feature documentation written in plain text.
Cucumber targets non technical business analysts, interaction designers, domain experts, testers (for the plain text part)
and programmers (for the steps, which are written in Ruby).

Cucumber itself is also written in Ruby, but it can be used to “test” code written in Ruby, Java (or web applications written
in any language). When IronRuby matures it can be used to “test” .NET code too.

Cucumber only requires minimal use of Ruby programming, so don’t be afraid to try it out even if the code you’re
developing is in a different language. Most programmers should pick up the required Ruby skills and be productive
with Cucumber in a few of days.

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
the production code is then written outside-in, to make them pass.

Migration from RSpec Stories

See Migration From RSpec Stories

Installation

(Rails people – see Ruby on Rails).

After you have installed Ruby or JRuby – install Cucumber with the following commands:

Ruby:

gem sources --add http://gems.github.com/ 
gem install aslakhellesoy-cucumber

JRuby:

jruby -S gem sources --add http://gems.github.com/ 
jruby -S gem install aslakhellesoy-cucumber

IMPORTANT As of Sept 12 there are problems with the gem. Please get the code via Git (or download a tarball) and build the gem yourself. I’m investigating what the problem is. —Aslak

git clone git://github.com/aslakhellesoy/cucumber.git
cd cucumber
rake gem # If you're on Windows this might fail because of missing tar.exe. Try installing MSYS.
rake install_gem

Getting started

There are several ways to get started, depending on the architecture of your application.
Take a look at the examples.
Each example directory has a Rakefile, and you can run the features in an example directory with

rake features

The examples deliberately have errors so you can get a taste of how the error output looks like. You can get help by asking
for it:

cucumber --help

BDD with Cucumber

If you have found a bug or want to add a feature, start by writing a new feature or scenario that describes the

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. You might as well get used to doing it this way, because we won’t accept
any patches unless you also have stories or specs for your code. This is because we don’t want to end up with a
brittle, unmaintainable, undocumented pile of code that nobody understands. (Yes, stores and specs are documentation too).

If you think this sounds annoying, try it out anyway. You’ll end up writing better (and less) code this way. Trust me.
Work outside-in (the outside being the story, 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

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 (Minimal Marketable Features) that will yield the most value.

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. 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 precicely 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.

Background and Credits

Cucumber is a rewrite of RSpec’s “Story runner”, which was originally written by Dan North. Dan’s original
implementation required that stories be written in Ruby. Shortly after, David Chelimsky added
plain text support with
contributions from half a dozen other people.

The business value guidelines and general wording in features is based on several conversations and blog posts
by Chris Matts, Liz Keogh and Dan North.

This brought executable stories a little closer to non-technical users, which is one of the target audiences
for this kind of tool.

David has a former life as the maintainer of FitNesse .NET. In early summer 2008, David and Aslak had some conversations about stories and how FIT style tables could be incorporated into the RSpec Story runner. Together we fleshed out some ideas about how scenarios and tables would look.

At this point, the architecture of the story runner was revisited and reevaluated in light of the looming requirement to use tables. It became clear that the RSpec Story runner had several shortcomings. (Similar shortcomings are common for tools that evolve in unforeseen ways and move into new territory). Some of its biggest problems were:

• Hard to get started with. A special “all.rb” file must be written before it can be used.
• No out of the box Rake support, which puts a lot of people off.
• No i18n, so if you want to write stories in a different language than English you’re out of luck.
• Poor error reporting. No way to know on what line a plain text story failed during execution or parsing.
• Limited colouring of output.
• No simple way to execute only one scenario.
• No command line tool to run stories.
• No easy before or after hooks.
• No highlighting of step parameters in the output
• No detection of ambiguous step names

While all of this could have been fixed in the existing codebase, I figured it would be easier to do a rewrite from scratch.
I also had some ideas for extensions of the story grammar (like FIT style tables that you can see in some of the examples),
so I decided to base it on a proper
grammar using
Treetop.

Cucumber addresses all of the above mentioned shortcomings of RSpec’s Story runner.
If the community likes it, perhaps it will replace the RSpec story runner – either by
being assumed into RSpec proper, or remaining a separate tool like now.

The term “Feature” has been adopted in favour of “Story” because I believe it is a more
appropriate term. A feature’s scenarios typically grow over time – fed by several user
stories. Or as David puts it: “Stories are the input to your development process – the features are the output”.

The name Cucumber means absolutely nothing, it was suggested by my girlfriend who was eating a cucumber sandwich
while I started to write it.