Getting Started with Story Driven Development for Rails with Cucumber

I'd been hearing about Story Driven Development (SDD) for a while but kept putting it off, assuming there was a huge amount to learn and set up before I could get going. Turns out that was completely wrong. I started using Cucumber yesterday and it was surprisingly easy to get rolling.

Install and configure

First, install the required gems:

sudo gem install nokogiri term-ansicolor treetop diff-lcs hpricot cucumber

Then install Cucumber into your Rails app:

ruby script/generate cucumber

Next, install Webrat. Unfortunately it's not available as a gem at this point. If you're using Git, install it as a submodule. If not, clone the repository and svn add it:

git clone git://github.com/brynary/webrat.git vendor/plugins/webrat

Writing your first story

Stories have three components: the business value being delivered, the role of the person using the feature, and a description of what the feature does.

In order to [do something with business value]
As [role]
Should [describe the feature]

For example, imagine you're building an online ordering system for a pizza delivery company:

Feature: Order Pizza
  In order to get some hot, tasty pizza
  A hungry pizza lover
  Should be able to order pizza

Now you need some scenarios -- specific things that can happen during the story. Most pizza places aren't open 24 hours, so two obvious scenarios are: the shop is closed, and the shop is open.

  Scenario: The pizza shop is closed
    Given the pizza shop is closed
    And I am on the home page
    And I click "Feed Me!"
    Then I should see "Sorry, the shop is closed"

  Scenario: The pizza shop is open
    Given the pizza shop is open
    And I am on the home page
    And I click "Feed Me!"
    Then I should see "Your pizza will be with you soon"

Save this in a file like features/order_pizza.feature, where it can live happily under version control.

So now you have a story that describes how a feature should behave. But how does it become an actual test? You could hand these descriptions to a testing team, or you could wire them up as part of your automated test suite.

Automated tests: better than cake

When you installed Cucumber, you got a features/steps directory. This is where you teach your test suite how to understand your stories. There are already two files in there: common_webrat.rb, which gives you useful abilities like clicking links, and env.rb, which does essentially the same job as spec/spec_helper.rb but for Cucumber. You can mostly ignore env.rb, but common_webrat.rb is worth reading for examples of how to write step definitions.

Create a new file called order_pizza_steps.rb. This is where you define the steps involved in ordering pizza. Each step is just a regular expression that maps a line from your scenario to some Ruby code:

Given /the pizza shop is open/ do
  PizzaShop.open = true
end

Given /the pizza shop is closed/ do
  PizzaShop.open = false
end

And /I am on the home page/ do
  visits "/"
end

That's it. The common Webrat steps already handle clicking buttons and checking for text on the page.

Running your stories

Just run rake features. You'll get nicely coloured output, and if anything goes wrong, Cucumber is genuinely helpful about suggesting ways to fix it.