From User Story to Acceptance Criterion: Given/When/Then Done Right

A user story is a requirement wearing casual clothes. It is deliberately small and deliberately informal — but it is still a requirement, and it has the same one job: to remove ambiguity between what is wanted and what is built.

The trick is that a story alone does not do the job. A story without acceptance criteria is a wish. This post shows you how to write both — the story that starts the conversation and the criteria that end it.

A user story is a promise, not a spec#

The classic form: "As a <role>, I want <capability>, so that <benefit>."

Example: "As a project owner, I want to export my requirements to PDF, so that I can share them with a customer who does not use the tool."

Notice what the story does NOT say: it does not say how to build the export, what library to use, or what the PDF looks like. It states the need and leaves the how to the team. A story is a promise of value, not an implementation.

Acceptance criteria make it testable#

The acceptance criteria are where the story becomes concrete. They are the conditions that must be true for the story to count as done. If a story is a promise, the criteria are the definition of "kept".

The cleanest format is Given/When/Then (from Gherkin): given a starting state, when something happens, then the system must respond in a specific, observable way.

Given/When/Then, done right#

A complete example:

Given a document with 120 requirements — When the owner clicks "Export PDF" — Then the system generates a PDF containing all 120 requirements, and the PDF includes section numbering.

Three rules keep it honest: one verifiable outcome per Then; concrete values instead of vague words; and no implementation detail (the criteria say WHAT, never HOW).

• Given — the preconditions: the state, the data, the logged-in user.
• When — the single action or event that triggers the behaviour.
• Then — the observable, testable outcome.

INVEST: six tests for a good story#

• Independent — it can be built and delivered on its own.
• Negotiable — it captures the goal, not the design.
• Valuable — it delivers something the user actually cares about.
• Estimable — the team can size it.
• Small — it fits comfortably in a sprint.
• Testable — you can point to the acceptance criteria that prove it.

Common mistakes#

• Writing the HOW into the criteria (e.g. "use the PDF library X") — that is design, not acceptance.
• Packing several outcomes into one scenario — split them, or you cannot tell which one failed.
• Vague Then ("the system should be fast") — replace with a number.
• Stories so large they cannot be estimated — split them along the value, not the work.

A full worked example#

Bad: "As a user, I want to export, so I can save things. Acceptance: the export should work and be fast."

Good: "As a project owner, I want to export my requirements to PDF, so I can share them with a customer." — Given a document with 120 requirements, When the owner clicks "Export PDF", Then the system generates a PDF containing all 120 requirements. And the PDF includes section numbering and the traceability matrix. And the export completes within 2 seconds.

The first version is a wish and will start an argument. The second is a promise a tester can keep or break — which is exactly what makes it useful.