Gherkin Acceptance Criteria: How to Write Given/When/Then Stories

Gherkin is a structured language for writing acceptance criteria that is both human-readable and automatable. Teams using behavior-driven development (BDD) write their acceptance criteria in Gherkin so they can be turned directly into automated tests.

The Given/When/Then structure

Given describes the initial state (the precondition). When describes the action or event. Then describes the expected outcome.

The structure forces you to be explicit about context, trigger, and result — the three things that make behavior testable.

Basic example: login

Given a registered user with valid credentials
When they submit the login form
Then they are redirected to the dashboard
And their name is displayed in the navigation

The And keyword extends the previous step without repeating Given/When/Then. Use it for additional assertions or preconditions.

Example: error handling

Given a registered user
When they submit the login form with an incorrect password
Then they see the error "Invalid email or password"
And they remain on the login page
And their account is not locked after the first failed attempt

Example: API scenario

Given an authenticated API request
When the client sends a POST to /api/projects with a valid payload
Then the server responds with HTTP 201
And the response body includes the new project ID

When to use Gherkin format

Use Gherkin when your team uses automated testing frameworks like Cucumber, Behave, or Playwright with a BDD layer. Also useful when QA writes test cases directly from acceptance criteria — the format maps cleanly to test structure.

For simpler stories without complex behavior, a checklist is often faster and equally effective.

Common mistakes

Putting implementation details in the Given: "Given the UserService returns a valid JWT" is an implementation detail. Use "Given a logged-in user" instead.

Combining multiple behaviors in one scenario: each scenario should test one path. Split happy path, error states, and edge cases into separate scenarios.

Skipping the Given when state is obvious: be explicit even when the precondition seems obvious. Omitting it makes the test ambiguous when the codebase changes.

Generate acceptance criteria instantly

Use our free acceptance criteria generator to draft Given/When/Then scenarios for any user story in seconds.