Skip to content

Features and roles

The product side of the spec: features with scenarios written as Given, When, Then, and the roles of the people and systems that use it.

Features

A feature is a capability described from the outside, with a title, an intent ("so that customers never pay for items we cannot ship"), a description and scenarios. Each scenario has a title and steps with the keywords Given, When, Then, And and But.

Scenarios of the feature Reserve stock at checkoutGherkin
Scenario: Every line item gets a reservation
  Given a Customer has a cart with 2 "Trail mug" and 1 "Canvas tote"
  When the Customer starts checkout
  Then a reservation holds 2 "Trail mug" for the order
  And a reservation holds 1 "Canvas tote" for the order
  And the Catalog shows 3 units of "Trail mug" available

Scenario: Checkout stops when a line item cannot be reserved
  Given a Customer has a cart with 2 "Canvas tote"
  When the Customer starts checkout
  Then no reservation is created for the order
  And the Customer is told that only 1 "Canvas tote" is left
  And payment is not requested

Features are the acceptance examples of the spec. They are published as YAML with the rest; see Spec files in your repository.

Roles

A role is someone or something that uses the system: Customer, Warehouse picker, Payment provider. It has a summary and optional sections: description, responsibilities, needs and pain points.

Add a section when you have something to say; an empty section can be removed again. Use cases name the roles that call them.

Writing good scenarios

  • One behaviour per scenario, named after the outcome: "Checkout stops when a line item cannot be reserved".
  • Use the words of the glossary.
  • Keep each step to its job: Given to the state that matters, When to one action, Then to what can be observed.

Next steps