Thread by @thebddadvocate

Writing Gherkin scenarios collaboratively can be beneficial both for business analysis, discovering the language of the domain and for the purpose of driving the code.

For both use-cases, here are some of my rules-of-thumb for writing Gherkin scenarios effectively.
#bdd #ddd

Given, When and Then are analogous to the three standard stages of a test:

Arrange: arrange the system to be tested in a given state
Act: take the action that is to be tested (perform the test itself)
Assert: check that what should have happened indeed happened

These stages apply to all tests where outcome depends on command given to system and state system was in. System moves from state A to state B as the result of the command: S1 → S2

Given the system is in state S1
When I give the command X
Then the system should be in state S2

Could also be understood as a mini-timeline of the App: outcome of command depends on something that happened before which is relevant to the scenario.

Given some event Y relevant to the outcome happened
When I give the command X
Then something else happens depending on Y

Example: Given the book loan period is 3 days)

Given I extended my library book on the 21st
When I return the book on the 22nd
Then I should not be charged a fine

Given I extended my library book on the 21st
When I return the book on the 24th
Then I should be charged a £1 fine

The "Given" step usually describes something that happened in the past and is therefore written in past tense (this is especially true for event-based systems).

For example "Given Jon borrowed the book 'Sapians' last Wednesday".

"Given" can also describe the state of the system before the command is executed: "Given there are 3 copies of 'Sapians' in the Library'"

The When step is always the user interaction, the command that the user gives to the system: "When Jon returns the book 'Sapians'", ("Return Book" being the command here)

The "Then" is simply used to assert that the expected outcome happened, e.g. the system gave a particular response to the user, the system emitted events or the affected tables in the database are changed)

Generally "Then" it is the outcome that matters to the business,

e.g, 'Then stock level of the book 'Sapians' has increased', or 'Then there should be 4 copies of 'Sapians' in the library', or 'Then Jon should have been fine £1 for late return'

Given/When/Then scenarios should not be used to describe a user journey and should not refer to any specific technology (e.g. web), the scenarios should be written in plain business language describing the logic of the system from the business point of view.

A useful way to decouple from the underlying technology is to imagine you can only give the system command by talking to an operator on the phon.

Titles should reflect clearly what each scenario is about, and the difference between them:

Scenario: Retuning a book on time incurs no fine
Scenario: Incurring a £1 fine for returning a book late
Scenario: Incurring a £10 fine for returning a damaged book

Start writing the scenarios with the desired outcome in mind, i.e. the "Then" step. Following that, write the command the user gives the system for this outcome to happen - then "When" step. At this point the "Given" should be clear

Background keyword should be used to execute Given steps not relevant to the outcome of the scenarios but are important to know about in context of feature.
E.g, all scenarios that show examples of making transfer between accounts require an account number used in each scenario.

Another keyword you can use (especially in order to draw a clear contrast to the previous scenario) is "But"

The Gherkin language was recently updated with Example being synonyms with Scenario, but not all gherkin parsers support this keyword.

Thanks to all the people who've helped me understand and formulate these ideas better:

@everzet @CiaranMcNulty @lunivore @jennyjmar @tastapod

/cc @gasparnagy @sebrose @aslak_hellesoy @wakaleo