Acceptance Criteria in Given/When/Then Format: Complete Guide with Examples

Given/When/Then is the gold standard for writing acceptance criteria. It's clear, testable, and works perfectly with both human developers and AI coding agents.

The Format

• Given — The precondition or context
• When — The action the user takes
• Then — The expected outcome

Why This Format Works

1. Testable — Each criterion maps directly to a test case

2. Unambiguous — Removes guesswork about expected behavior

3. AI-friendly — AI agents can read Given/When/Then and implement precisely

30+ Examples by Category

Authentication

• Given I am a new visitor, When I click "Sign Up" and enter valid credentials, Then my account is created and I receive a welcome email.
• Given I am logged in, When I enable 2FA and scan the QR code, Then future logins require a 6-digit code.

CRUD Operations

• Given I am on the project board, When I drag a story from TODO to IN_PROGRESS, Then the story status updates and a timestamp is recorded.
• Given I am viewing a story, When I click "Delete" and confirm, Then the story is removed from the board and cannot be recovered.

Payments

• Given I am on the Free plan, When I click "Upgrade to Pro" and complete payment, Then my plan changes to Pro and I see unlimited features.

Error Handling

• Given the API is unavailable, When I try to save a story, Then I see an error message "Unable to save. Please try again." and my unsaved changes are preserved.

Common Mistakes

1. Too vague: "Then it works" — works how?

2. Too technical: "Then a 200 response with JSON body..." — write from the user's perspective

3. Missing Given: Without context, the criterion is incomplete

4. Multiple Whens: Split into separate criteria

AI-Powered Generation

Codepylot's AI automatically generates Given/When/Then acceptance criteria when you rewrite a story. It typically produces 3-5 criteria per story, covering the happy path, error cases, and edge cases.

Try the free Acceptance Criteria Generator at codepylot.io/tools/acceptance-criteria-generator.