template · gherkin scenario set

Gherkin scenario set template

Three or more scenarios per story, at least one negative. Given lines name the person's situation, not the system state. Written together at amigos.

How to use

Replace every [...] with concrete content. The Given clauses describe the named person's situation, not the system internals. The Then clauses describe what gets observed by that person or the team — events logged, screen state, response codes. If you find yourself writing about session tokens or DB rows in the Given, rewrite from the person's vantage.

# Story: [story title]
# Linked from: [link to the story]
# Signed at amigos: [PO, Developer, QA initials · date]

Feature: [feature name from the brief]

  Background:
    Given [named person] is [role + context]
      And the system is in [the stable initial state observable to them]

  Scenario: [Happy path — what the moment looks like when it works]
    Given [the person's situation in plain language]
      And [supporting situation if needed]
    When  [the action the person takes]
    Then  [what they observe — UI, response, or recorded event]
      And [any side-observable: log line, dashboard event]

  Scenario: [Variation — different valid input]
    Given [the situation that differs from happy path]
    When  [...]
    Then  [...]

  Scenario: [Negative — input is bad or the system fails gracefully]
    Given [the unhappy situation]
    When  [the action]
    Then  [the graceful failure is observable]
      And [no silent data corruption]
      And [the person can still proceed or recover]

  Scenario: [Edge — moment-specific edge case]
    Given [the edge condition surfaced in journey mapping]
    When  [...]
    Then  [...]

Worked example (from the canon)

Feature: Hebrew name rendering for graders

  Background:
    Given Gal is logged in as a grader

  Scenario: Hebrew name renders correctly on first load
    Given there is a submission from a student named "Yael Rosenberg-Hayut"
    When Gal opens the grading queue
    Then the student's name is displayed as "Yael Rosenberg-Hayut"
      And no encoding warnings are present in the application log

  Scenario: Hebrew name with mixed forms renders correctly
    Given there is a submission from a student named "אריאל שמעון-לוי"
    When Gal opens the submission
    Then the student's name renders correctly in both queue and review screens
      And the right-to-left layout is applied to the name field

  Scenario: Name with rare unicode form falls back gracefully
    Given a submission contains a unicode form not in the supported set
    When Gal opens the submission
    Then the name is displayed with the unicode-fallback character
      And a system warning is logged for review
      And Gal can still grade the submission without re-typing

Where this lives in your project

The Gherkin set lives alongside the story (linked, not embedded). Some teams keep it in the repo as .feature files; some keep it in the tracker. The location matters less than the discipline that it is signed at amigos.

What to do if a scenario resists

Resistance	What it means	Where to go
Given is in system-state language	Lost the person's vantage	Rewrite Given Gal is… not Given the user has session_id…
No negative scenario	Amigos hasn't held the anti-flow	Practice · Holding amigos · Step 5
All scenarios are the same shape	Story is too small (one AC repeated) or too big (no real variation)	Re-walk Story · DoR
Scenario describes implementation	The trio drifted into how	Constrain to behaviour. Hand the how back to the developer.
More than ~6 scenarios per story	The story is doing too much	Split the story; each half goes back to amigos

See also

• Practice — Holding amigos
• Template — Story (the input to a Gherkin set)
• Checklist — Amigos 45-minute agenda
• Canon — What We Shape · Amigos & Gherkin