Introduction to BDD with Cucumber

Cucumber is a framework for writing and executing high level descriptions of your software's functionality. Call these tests, examples, specifications, whatever... it doesn't matter too much. What I'm talking about has traditionally been called functional, integration, and/or system tests. In XP terms this includes tests called Story Tests, Customer Tests, and/or Acceptance Tests.
One of Cucumber's most compelling features is that it provides the ability to write these descriptions using plain text in your native language. Cucumber's language, Gherkin, is usable in a growing variety of human languages, including LOLZ. The advantage of this is that these feature descriptions can be written and/or understood by non-technical people involved in the project.
One important thing to keep in mind is that Cucumber is NOT a replacement for RSpec, test/unit, etc. It is not a low level testing/specification framework.
Cucumber plays a central role in a development approach called Behaviour Driven Development (BDD).

A Bit About BDD

Dan North describes BDD as “writing software that matters” in The RSpec Book and outlines 3 principles:

1. Enough is enough: do as much planning, analysis, and design as you need, but no more.
2. Deliver stakeholder value: everything you do should deliver value or increase your ability to do so.
3. It's a behavior: everyone involved should have the same way of talking about the system and what it does.

BDD in its grandest sense is about communication and viewing your software as a system with behaviour. BDD tools such as RSpec and Cucumber strive to enable you to describe the behavior of your software in a very understandable way: understandable to everyone involved.

Features

A feature is something that your software does (or should do), and generally corresponds to a user story and a way to tell when it's finished and that it works.
The general format of a feature is:

Feature: <short description>
  <story>
  <scenario 1>
  ...
  <scenario n>

Within the definition of a feature you can provide a plain text description of the story. You can use any format for this, but having some sort of template makes it easier to see the important bits of information with a quick glance. Once of the more common template is discussed by Mike Cohn in User Stories Applied:

As a <role>
I want <feature>
so that <business value>

This format focuses us on three important questions:

• Who's using the system?
• What are they doing?
• Why do they care?

Here's a sample story:

As a code-breaker
I want to start a game
So that I can break the code

That defines who the user is (a code-breaker), what they want to do (start a game) and why (be able to break the code).

Scenarios

A feature is defined by one or more scenarios. A scenario is a sequence of steps through the feature that exercises one path. Cucumber uses the BDD style that Dan North put forth with his jBehave project: given-when-then.
A scenario is made up of 3 sections related to the 3 types of steps:

1. Given: This sets up preconditions, or context, for the scenario. It works much like the setup in xUnit and before blocks in RSpec.
2. When: This is what the feature is talking about, the action, the behaviour that we're focused on.
3. Then: This checks postconditions… it verifies that the right thing happen in the When stage.

The general form of a scenario is:

Scenario: <description>
  <step 1>
  …
  <step n>

Following our example, here's a scenario:

Scenario: start game
  Given I am not yet playing
  When I start a new game
  Then the game should say “Welcome to CodeBreaker”
  And the game should say “Enter guess:”

One thing to note is the last line. Notice the And. And can be used in any of the three sections. It serves as a nice shorthand for repeating the Given, When, or Then. And stands in for whatever the most recent explicitly named step was: Given, When, or Then. The last two lines above could have been:

Then the game should say “Welcome to CodeBreaker”
Then the game should say “Enter guess:”

That doesn't read nearly as well, though. Similarly, if you want to state a negative Then step, you can use But in place of Then, for example:

Then the game should say “Welcome to CodeBreaker”
But the game should not say “Save the cheerleader, save the world”

While there are no constraints on the number or order of steps, it is generally best to keep scenarios as simple as possible and have multiple simple scenarios. The closer your scenarios conform to the given-when-then format, the better.

Implementing Steps

So here's our feature:

Feature: code-breaker starts game
  As a code-breaker
  I want to start a game
  So that I can break the code
  Scenario: start game
    Given I am not yet playing
    When I start a new game
    Then the game should say “Welcome to CodeBreaker”
    And the game should say “Enter guess:”

If you run that you'll see an echo of the feature followed by (using Cucumber 0.3.11):

1 scenario (1 undefined)
4 steps (4 undefined)
0m0.001s
You can implement step definitions for undefined steps with these snippets:
Given /^I am not yet playing$/ do
  pending
end
When /^I start a new game$/ do
  pending
end
Then /^the game should say “Welcome to CodeBreaker”$/ do
  pending
end
Then /^the game should say “Enter guess:”$/ do
  pending
end

The next step (pardon the pun) is to define what each of our steps mean. When we executed our feature with no steps defined, Cucumber gave us skeletons for the undefined steps (see above). If we put those in the file features/step_definitions/codebreaker.rb and run it again, we get:

1 scenario (1 pending)
4 steps (3 skipped, 1 pending)

As you can see from above, the basic structure of a step definition is the keyword (i.e. Given, When, or Then) followed by a regular expression and a block of Ruby code. The regular expression is used to identify the desired step implementation. The step text in scenarios is matched against the regular expressions of appropriate (i.e. given, when, or then) step implementations to find the one to use. When a match is found, the substrings matching any groups in the regular expression are used as arguments to the block which is then evaluated. The result of that evaluation is discarded. Note that these arguments are always strings. If you need them converted to other types, it's up to you to do that conversion in the block. These groups and parameters have knowledge of position (i.e.. group 1 is used as the first parameter, group 2 as the second, and so on).
Notice that the suggested steps are completely concrete. While that is fine some of the time, you will generally want to refactor steps and make them more generic and reusable. Notice that there are two then step definitions that are much the same:

Then /^the game should say “Welcome to CodeBreaker”$/ do
end
Then /^the game should say “Enter guess:”$/ do
end

The difference is the string inside quotes (using quotes or similar delimiters is very handy for matching the groups). We can factor that out into a regex group:

Then /^the game should say “(.*)”$/ do |message|
end

Our given step could be:

Given /^I am not yet playing$/ do
  @game = Codebreaker::Game.new
end

Next is the when step:

When /^I start a new game$/ do
end

This might be implemented as:

When /^I start a new game$/ do
    @messages = @game.start
end

Now we have the variable @messages that can be used in subsequent steps.
Recall how we left our then step definition:

Then /^the game should say “(.*)”$/ do |message|
end

We can now fill this in:

Then /^the game should say “(.*)”$/ do |message|
  @messages.should include(message)
end

You can use whatever method of verification you want in the then steps: rspec, test/unit, shoulda, etc. I happen to prefer RSpec.
Earlier I mentioned that Cucumber supports various languages including LOLZ. Here's a feature in LOLZ:

OH HAI: STUFFING
 MISHUN: CUCUMBR
    I CAN HAZ IN TEH BEGINNIN 3 CUCUMBRZ
    WEN I EAT 2 CUCUMBRZ
    DEN I HAZ 2 CUCUMBERZ IN MAH BELLY
    AN IN TEH END 1 CUCUMBRZ KTHXBAI

And the step implementations:

ICANHAZ /^IN TEH BEGINNIN (d+) CUCUMBRZ$/ do |n|
  @basket = Basket.new(n.to_i)
end
WEN /^I EAT (d+) CUCUMBRZ$/ do |n|
  @belly = Belly.new
  @belly.eat(@basket.take(n.to_i))
end
DEN /^I HAZ (d+) CUCUMBERZ IN MAH BELLY$/ do |n|
  @belly.cukes.should == n.to_i
end
DEN /^IN TEH END (d+) CUCUMBRZ KTHXBAI$/ do |n|
  @basket.cukes.should == n.to_i
end

And that's all there is to understanding the basics of Cucumber.