Tuesday, April 21, 2009

Cucumber Syntax

Cucumber is the latest incarnation of the RSpec Story runner concept; A complete rewrite by Aslak Hellesoy.

I have been using Cucumber at work as a requirements parser to generate test scripts. Here is a quick guide to the content of the feature files.

Cucumber provides a simple way to parse feature/scenarios that have been written in a english (or whatever your native language is). For Cucumber to understand your features though you need to structure them in a certain way... here is how you do it.

A standard install has the following directory structure...

ProjectDirectory
+ bin
+ features
- XXX.feature
- ...
+ step_definitions
- XXX_steps.rb
- ...
+ support
- env.rb
+ lib
+ spec

Features


The features are documented in the files named [feature_name].feature in the features directory.

They follow this pattern:
Feature: [the features name]

In order to [goal]
As a [role]
I want to [action]

[...background...]

[...scenarioes...]


Scenarioes


Cucumber doesn't actually do anything with this information (except the scenarioes and background). It is intended to give a human reader context (and reveal the motivation for) for the scenarioes that follow.

Scenarioes are descriptions of the ways that that feature manifests itself within the application. You would have one scenario for each path through the feature. These are a lot like use cases, but you keep them high level, short and only exercising one path.

Scenarioes is made up of a several steps, and can take the following form:
Scenario: [name of the scenario]
Given [some statement]
When [some action]
Then [expected result of the action on the system]
And [another expectation]


Note: And can be used after Given, When or Then steps.

When you run cucumber against a file it will suggest code to put in your ..._steps.rb files to match any currently undefined steps.

Note: Steps can be parameterized to aid reuse. If you put "quotes" around some part of your step (e.g. Given I am on the "login" screen ), then when cucumber suggests the code for you, it will automatically suggest one that will pass what is between the quotes as an argument.

Given the following customer exist:
|name | age | email |
|rod | 32 | rod@somewhere.cool |
|jane | 35 | jane@somewhere.cool |
|freddy | 34 | freddy@somewhere.cool |

You can also have steps (Given, When, Then, or And) it this form. This will result in a table of information being passed to your step definition.

Background


Background defines the context that the scenarioes should be run in. In other words a set of Steps that will be executed before each scenario in this file is run.

Background takes the following form:
Background: 
Given ...
And ...
And ...


Scenario Outlines


Scenario Outline: [name of the scenario]
Given [some statement]
When [some action]
Then [expected result of the action on the system]

Examples: [name of example set]
| column A | column B | column C |
| row 1 A | row 1 B | row 1 C |
| row 2 A | row 2 B | row 1 C |


The scenario outline in infact defining several scenarioes. The Outline will be executed by Cucumber once for each row in the Examples table (excluding the first with is the column headings). Any steps within the scenario that include something of the form <column name> will have the <...> substituted with the contents of that column for the current row.

Note: You can include multiple Example tables if you like.

Cucumber uses the features/support/env.rb file to set up cucumber. This is a good place for your:
Before do  |scenario|
...
end

After do
...
end

...blocks to live. These are executed before and after (respectively) each scenario is run.

GitHub Projects