Feature, User Story, Scenario authoring guidelines

Gherkin.md

#Gherkin Guidelines to documenting features, user stories, and scenarios using Gherkin, a business specification language.

In some projects, we will use Gherkin to communicate about features. Gherkin is a business-friendly language that is intended to ease communication between technical resources and project stakeholders.

##Feature A feature is a description of a key system function that delivers value to one or more stakeholders and/or end users.

##User Story A user story is a standard way of describing a feature in a matter that:

• describes the feature
• describes the audience's value
• describes the audience

As a project administrator
I want to create documents within my project
so that I can maintain a library of project-related documentation

In the above example, "As a" is used to denote the audience that will benefit from the feature. "I want to" describes the feature. And, "so that" describes the value of the feature to the audience.

##Scenario A scenario is a key example involving user/actor interactions and expected outcomes as they pertain to the feature.

##Step A single step describes one of the following:

• a precondition
• a user/actor interaction
• an expected system output

e.g. five steps

Given I am on the login page
When I enter "user1" in the "username" textbox
And I enter "password1" in the "password" textbox
And I click the "login" button
Then the page should say "Incorrect login credentials"

In the above example, "Given" describes the preconditions that must be met. "When" describes the actions taken by the user. And, "then" describes the state of the system that results from the user's actions.

"And" is used to expand any of the preconditions, interactions, or outcomes.

##Order

• A feature can be described with a user story.
• A feature consists of one or more scenarios.
• And, a scenario consists of at least two steps: an interaction, and an expected outcome

##Tips

###Do not describe user actions as preconditions Bad: Given I go to the login page

Better: Given I am on the login page

It is a subtle difference, but it distinguishes a precondition from an action.

###Use the User Story as a placeholder for a conversation Sometimes user stories are broad or vague. Additional stories can be derived from the discussion of an existing story. Capture the stories. Then, define the scenarios and steps of each story.