Every .feature file conventionally consists of a single feature. A line starting with the keyword Feature followed by free indented text starts a feature. A feature usually contains a list of scenarios. You can write whatever you want up until the first scenario, which starts with the word Scenario (or localized equivalent; Gherkin is localized for dozens of languages) on a new line. You can use tagging to group features and scenarios together independent of your file and directory structure.
Every scenario consists of a list of steps, which must start with one of the keywords Given, When, Then, But or And. Cucumber treats them all the same, but you shouldn’t. Here is an example:
Feature: Serve coffee Coffee should not be served until paid for Coffee should not be served until the button has been pressed If there is no coffee left then money should be refunded Scenario: Buy last coffee Given there are 1 coffees left in the machine And I have deposited 1$ When I press the coffee button Then I should be served a coffee
In addition to a scenario, a feature may contain a background, scenario outline and examples. Respective keywords (in English) and places to read more about them are listed below. You can get a list of localized keywords with
cucumber --i18n [LANG].
|keyword||localized||more info, see|
|scenario_outline||‘Scenario Outline’||Scenario outlines|
|examples||‘Examples’ / ‘Scenarios’||Scenario outlines|
For each step Cucumber will look for a matching step definition. A step definition is written in Ruby. Each step definition consists of a keyword, a string or regular expression, and a block. Example:
# features/step_definitions/coffee_steps.rb Then "I should be served coffee" do @machine.dispensed_drink.should == "coffee" end
Step definitions can also take parameters if you use regular expressions:
# features/step_definitions/coffee_steps.rb Given /there are (\d+) coffees left in the machine/ do |n| @machine = Machine.new(n.to_i) end
This step definition uses a regular expression with one match group –
(\d+). (It matches any sequence of digits). Therefore, it matches the first line of the scenario. The value of each matched group gets yielded to the block as a string. You must take care to have the same number of regular expression groups and block arguments. Since block arguments are always strings, you have to do any type conversions inside the block, or use Step Argument Transforms.
When Cucumber prints the results of the running features it will underline all step arguments so that it’s easier to see what part of a step was actually recognised as an argument. It will also print the path and line of the matching step definition. This makes it easy to go from a feature file to any step definition.
Take a look at Step Definitions and the examples directory to see more.