User Stories with Gherkin Acceptance Criteria

Gherkin is the structured language behind behaviour-driven development, expressing behaviour as Given / When / Then:

Scenario: Password reset link expires after 24 hours
  Given a password reset was requested 25 hours ago
  When the user opens the reset link
  Then they see "This link has expired"
  And they are offered a way to request a new one

The value is not the syntax. It is that the format makes vagueness impossible to hide. "The reset link should expire reasonably quickly" survives a specification document; it cannot survive a Given step, because someone has to write a number.

The three keywords carry distinct meanings and conflating them is the most common mistake:

• Given — the state of the world before the behaviour. Preconditions, not actions. Past or present tense.
• When — the single action under test. One event, expressed in the user's terms.
• Then — the observable outcome. What changed that someone could verify.

And and But continue the previous keyword. A step list with five Givens is fine; a scenario with three Whens almost always means three scenarios have been merged.

The difference between a Gherkin suite that survives two years and one abandoned after six months is almost entirely this distinction.

Imperative scenarios describe interface mechanics:

When I click the "Account" dropdown
And I click "Settings"
And I clear the "Email" field
And I type "new@example.com"
And I click "Save"

Declarative scenarios describe intent:

When the user changes their email address to "new@example.com"

Both may drive the same automation. The difference is what happens when the interface changes. The imperative version breaks when the dropdown becomes a sidebar, and it breaks in the specification document that non-technical stakeholders read — so a visual redesign generates specification churn that communicates nothing.

The declarative version does not change, because the intent did not change. Only the step definition underneath is updated, in one place.

A reliable test: if your scenario mentions a button, a field, a URL or a CSS class, it is too low-level. Those belong in step definitions. The feature file should read as though written by someone describing what the product does, not by someone narrating a screen recording.

Acceptance criteria define "done" for a user story, and most are too vague to serve that purpose. "Login should work" cannot be tested; it can only be argued about.

Good criteria share four properties:

1. Testable. Someone can determine pass or fail without a judgement call.
2. Specific about values. Not "quickly" but "within 2 seconds". Not "a strong password" but the actual rule.
3. Independent. Each criterion stands alone.
4. Inclusive of failure. The unhappy paths are where defects live.

For every happy path, ask three questions that consistently surface missing requirements: *What if the input is invalid? What if the user lacks permission? What if the external dependency is unavailable?*

Applied to a password reset:

Scenario: Reset requested for an unregistered address
  Given no account exists for "ghost@example.com"
  When a password reset is requested for that address
  Then the response is identical to a successful request
  And no email is sent

That scenario encodes a real security decision — not revealing whether an account exists — which a "login should work" criterion would never have surfaced. This is the mechanism by which Gherkin earns its cost: the format forces the conversation that finds the requirement.

Scenario Outline parameterises a scenario across an Examples table:

```gherkin Scenario Outline: Password strength rules When the user sets their password to "<password>" Then the result is "<outcome>"

Examples: | password | outcome | | short | rejected: too short | | alllowercase123 | rejected: needs an uppercase | | Valid-Pass-123 | accepted | ```

This is the correct tool for the same behaviour across different inputs. It is the wrong tool for different behaviours that happen to look similar, which produces a table with columns that only apply to some rows — a reliable sign the outline should be separate scenarios.

Background runs steps before every scenario in a feature:

Background:
  Given a registered user "asha@example.com"

Backgrounds are useful and frequently overused. Once a Background exceeds three or four steps, individual scenarios become unreadable, because understanding one means scrolling to the top of the file and holding a dozen preconditions in mind. If a scenario needs elaborate setup, put the setup in a single well-named step — Given a user with an expired subscription — and let the step definition do the work.

The guiding constraint: a scenario should be comprehensible in isolation. If a reader must reconstruct state from elsewhere in the file, the abstraction is in the wrong place.

BDD suites fail in a predictable way. They are adopted enthusiastically, grow to several hundred scenarios, become slow and flaky, and are eventually ignored — at which point they are worse than nothing, because they carry authority without accuracy.

What prevents it:

Keep the suite small and high-value. Gherkin scenarios are expensive: they need step definitions, they run slowly, and they are read by non-technical stakeholders. Reserve them for behaviour that matters to the business. Exhaustive input validation belongs in unit tests, which are faster by orders of magnitude.

One behaviour per scenario. A scenario testing three things fails ambiguously and is hard to name.

Name scenarios as sentences describing the rule. "Reset link expires after 24 hours", not "Test reset 3". The name appears in failure output and is the first thing anyone reads.

Delete scenarios for removed behaviour immediately. A feature file describing something the product no longer does actively misleads.

Treat flakiness as a defect, not an inconvenience. One scenario that fails intermittently teaches the team to ignore red builds, and that habit generalises to the whole suite.

The OpenTools user story builder drafts stories and Given/When/Then criteria in the browser. Requirements documents routinely contain unreleased roadmap detail and customer names, which is reason enough not to draft them in a tool that transmits their contents.