Use Gherkin; Given, When, Then steps to describe a process

[johnsBeharry]

Title: Use Gherkin to Describe a Process
Author: @johnsBeharry
Status: Draft
Type: Process

Abstract

Communicating an idea is difficult. Issues arise for a variety of reasons; to name a few would be difference of culture, native language, skill level etc.

Gherkin is an action oriented framework to describe a processes using the constraint of Given, When, Then at the beginning of each step.

Motivation

By adopting a fixed structure of describing things, and aiming to remove ambiguity by being explicit we can communicate our ideas more precisely — leading to less arguments, misunderstandings and inefficient use of time spent translating meaning.

The structure we use is Gherkin. It is an action oriented language that is used to take business requirements and explain them in a way that is clear and without ambiguity.

The Golden Gherkin Rule:

Treat other readers as you would want to be treated. Write Gherkin so that people who don’t know the feature will understand it.

Ambiguity in product requirements, or any form of communication around technology is very common and leads to wastage, and frustration by both the reporter of the task/bug/feature and the developer implementing the work.

The basic principal is that you define some process as a set of scenarios. The scenarios are sentences or "steps" beginning with Given, When, Then. But please note the Cardinal Rule of BDD: One Scenario, One Behavior!
Step types are meant to be guides for writing good behavior scenarios.

Specification

Gherkin

Feature: ATM

Scenario: Enter correct PIN
Given some context...
When <user> performs an action
Then expect this outcome
And another expectation can be added

Scenario: Entering a wrong PIN
...

Scenario: Entering wrong PIN 5 times
...

Scenario: Out of receipt paper
...

Scenario: Selecting less than $10
...

"And" can be used to extend the context, action or outcome.

By breaking down functionality into scenarios, you describe exactly the behavior / process you expect -- developers, designers whomever is implementing the work can make the functionality match.

Simple rule: be direct, and avoid ambiguity - if one of the steps can have multiple interpretations, you've done it wrong. Also, try and write steps in a way that they can be reused. This comes in very handy for larger projects with repetitive actions.

Features

• Every .feature file conventionally consists of a single feature.

Feature: Some terse yet descriptive text of what is desired
  1. Textual description of the business/customer value of this feature

  2. Business rules that govern the scope of the feature

  3. Any additional information that will make the feature easier to understand

Example

Feature: Serve coffee
  As a ___
  I want to ___
  So that I can ___

  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

  Some other details ___
  # Even add a note for @someone else

Scenarios

• ​In the scenario of X these steps happen.
• The title of the scenario must communicate in one concise line what the behavior is.
• For Draft scenarios
  • 3 underscores ___ can be used as filler for somethings that you cannot currently explain
  • Include @wip tag for a scenario that is incorrect and you need help with

Steps: Given, When, Then

• ​Given some precondition that sets up the environment
• When an action
• Then an outcome
• And more criteria, can be applied after any of the Given, When, Then steps to extend their criteria

N.B - Givens should always use present perfect tense, and Whens and Thens should always use present tense.

Rationale

...