Scenarios

Scenarios make up the detailed flows of each feature, both the expected path and any edge cases you can think of.

A feature can have multiple scenarios, in fact the more scenarios you have per feature, the more likely it will be implemented correctly the first time round.

A scenario is typically made up of 2 main parts along with supporting information:

  • A title.
  • The story.

Supporting Info:

  • The feature it belongs to.
  • FAQ this scenario raises.

Scenario Title

The title of a scenario should be a terse sentence that indicates the situation that makes it unique to this feature. Example titles:

Require credit card before publishing a property listing.

or

Detect credit card type from number.

Scenario Story

A good story sets up a scene (the state of the world), involving at least one character and describes the changes that happen as consequences of the character's actions or world's events.

In order to achieve that consistently, we encourage a syntax called Gherkin which is a type of "Business Readable, Domain Specific Language".

Before describing the structure lets start with an example of a story:

As a landlord.
Given I have already created a property listing.
And I don't have my credit card on file.
And I am viewing my property listing on the admin panel.
When I click on "Publish Now".
Then I should see a warning message: "You need to enter your credit card information in order to publish a property".
And I should not be able to publish the property.

A story consists of steps broken into the following sections:

As

From who's point of view is this scenario taking place. In other words who is the "actor", "character" or in software terms "user".

This step can be omitted if it is always the same or you do not expect ambiguity.

Examples:

  • As an administrator
  • As a visitor.
  • As a landlord or renter.

Given:

Use this to setup the scene.

When:

Then:

For consistency, it is best to always write the scenarios in first person.