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

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

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

Ruby on Rails

Cucumber Rails support built-in, and I really recommend using Webrat
in the step definitions. Here is how to get you started.

Install Cucumber, Webrat and RSpec

git submodule add git://github.com/aslakhellesoy/cucumber.git vendor/plugins/cucumber
git submodule add git://github.com/brynary/webrat.git vendor/plugins/webrat
git submodule add git://github.com/dchelimsky/rspec.git vendor/plugins/rspec
git submodule add git://github.com/dchelimsky/rspec-rails.git vendor/plugins/rspec-rails

If your own Rails code is not in Git, just replace “submodule add” with “clone”.
If you’re behind a proxy, try to replace git:// with http:// and set the http_proxy environment variable.
As a last resort, download tarballs from GitHub.

Install Other dependencies

gem install hpricot cucumber

Yes, you did already install cucumber as a plugin, but this will install all the dependent libraries you need.

Bootstrap Cucumber

You’ll need a Rake task and a couple of files that configure Cucumber for use with Ruby on Rails and Webrat.
You create these with:

ruby script/generate cucumber

Take a look at the generated files. If you need to, you can go and tweak them later.

Start a feature

It’s really, really recommended that you write your features by hand – in collaboration with your
customer / business analyst / domain expert / interaction designer. However, to get you started (and so you can see how to use
Webrat), you can use the feature generator to generate the first few features:

ruby script/generate feature Frooble name color description

This will generate a simple plain text feature with associated steps. Don’t get addicted to this
generator – you’re better off writing these by hand in the long run. See the BDD tips section below.

Run features

rake features

This should result in failing scenarios, because you haven’t written any code yet (I hope). Now you it’s time
to write some code, or generate some. Try this:

script/generate rspec_scaffold Frooble name:string color:string description:text
rake db:migrate
rake features

Tips

These tips apply to Rails development in general…

• Talk to models directly in Given steps to set up a known state. Don’t use fixtures.
• Use Webrat in When steps
• Use response.should have_tag(…) (and models) in Then steps to verify the outcomes (which are on the screen, not only in the database).
• Organise steps in files named accordingly to resources used
• Avoid keeping state in @variables in steps. It will couple your steps and make them harder to reuse.

View spec redundancy

Since I recommend you verify outcomes (Then steps) by looking at the HTML, you might end up having some degree
of redundancy with view specs. I recommend you delete generated view specs if you run into too much maintenance
headaches and rely on the features instead of view specs. However, in some cases it can be handy to use both.

BDD

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.

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