Telos logo
Telos
Book a Demo
Back to Blog
Product Management Agile Acceptance Criteria Testing BDD

Given-When-Then Acceptance Criteria: Gherkin Format Guide and Examples

Given-When-Then is the standard format for writing acceptance criteria in agile. Here's how to use it, with real examples and common mistakes to avoid.

Telos Team •
Given-When-Then Acceptance Criteria: Gherkin Format Guide and Examples

Given-When-Then is a structured format for writing acceptance criteria. It makes behavior explicit, eliminates ambiguity, and produces criteria that QA can turn directly into tests.

If you’ve seen acceptance criteria that look like this:

Given I am a logged-in user
When I click “Submit”
Then my form data is saved and I see a confirmation message

That’s Given-When-Then. The format comes from Behavior-Driven Development (BDD) and is sometimes called Gherkin - the language used in BDD testing tools like Cucumber and SpecFlow.

What Given-When-Then Means

Each part has a specific role:

Given - the starting state or context. What is true before the action happens? This describes the precondition: who the user is, what data exists, what state the system is in.

When - the action or trigger. What does the user do? This should be a single, specific action - clicking a button, submitting a form, navigating to a page.

Then - the expected outcome. What should happen as a result? This is the observable behavior: what the user sees, what gets saved, what notification fires.

The structure is deliberately restrictive. One precondition, one action, one outcome. If you need multiple outcomes, write multiple criteria.

Basic Given-When-Then Examples

Login

Given I am on the login page with valid credentials
When I click “Log in”
Then I am redirected to my dashboard

Given I enter an incorrect password
When I click “Log in”
Then I see “Incorrect email or password” and I remain on the login page

Password Reset

Given I am on the login page
When I click “Forgot password” and enter a registered email
Then I receive a password reset email within 5 minutes

Given I follow a password reset link that is 25 hours old
When I attempt to use it
Then I see “This link has expired. Request a new one.”

File Upload

Given I am on the upload page
When I select a file under 10MB in PDF format
Then the file uploads successfully and appears in my file list

Given I am on the upload page
When I select a file larger than 10MB
Then I see “File too large. Maximum size is 10MB.” and nothing is uploaded

Given I am on the upload page
When I select a file in .exe format
Then I see “Unsupported file type” and nothing is uploaded

Given I am on the search page
When I type at least 2 characters and pause for 300ms
Then results matching my query appear below the input

Given I search for a term with no matches
When results load
Then I see “No results for [search term]“

And / But Clauses

Given-When-Then can be extended with And and But:

  • And adds another condition of the same type
  • But introduces an exception
Given I am a logged-in user
And I have items in my shopping cart
When I click "Checkout"
Then I am taken to the checkout page
And my cart items are still present
But my coupon code input is empty

Use And and But sparingly. If you’re stacking many conditions, consider whether the scenario is too complex or whether it should be split into multiple criteria.

Gherkin Syntax: Given-When-Then in Test Tools

Gherkin is the formal language used in BDD testing frameworks like Cucumber (Ruby/JavaScript), SpecFlow (.NET), Behave (Python), and Serenity (Java). It extends Given-When-Then with a few structural elements:

Feature: User login

  Scenario: Successful login with valid credentials
    Given I am on the login page
    When I enter a valid email and password
    And I click "Log in"
    Then I am redirected to my dashboard

  Scenario: Failed login with invalid password
    Given I am on the login page
    When I enter an incorrect password
    And I click "Log in"
    Then I see "Incorrect email or password"
    And I remain on the login page

A Feature groups related scenarios. A Scenario is a single Given-When-Then test case. The keywords match Given-When-Then-And-But exactly.

If your team uses automated testing with any of these frameworks, writing acceptance criteria in Gherkin from the start means QA can use the criteria directly - no translation needed.

When to Use Given-When-Then

Given-When-Then is best for:

  • Conditional logic - if the behavior changes based on user state, permissions, or input
  • User-facing interactions - form submissions, button clicks, navigation flows
  • Error states - what happens when something fails, is invalid, or is unauthorized
  • Stories that QA will automate - Gherkin maps directly to automated test structure

The checklist format (simple bullet points) works better for:

  • Simple, unconditional behavior with no edge cases
  • Internal or background processes with no user-visible output
  • Very short stories where Given-When-Then feels like overkill

Both formats are valid. Use Given-When-Then when behavior is conditional or when you want testability built in from the start.

How to Write Good Given-When-Then

Keep each criterion to one action. “When I click Submit and enter my email” is two actions. Split it.

Make Given specific. “Given I am a user” is too vague. “Given I am a logged-in user with admin permissions” is specific.

Make Then observable. “Then it works” is not an acceptance criterion. “Then I see a green banner: ‘Changes saved successfully’” is testable.

Cover the unhappy path. The happy path (user does everything right) is only half the story. What happens with bad input? When the user has no permissions? When the network fails? These edge cases are where bugs live.

One scenario per criterion. Don’t combine multiple scenarios into one sprawling Given-When-Then. Write separate criteria for each behavior.

Avoid implementation details. “When the API returns a 200 status code” is not an acceptance criterion - it’s an implementation detail. “When the form submits successfully” is the criterion.

Given-When-Then Templates by Story Type

Feature access based on permissions

Given I am a [user role]
When I navigate to [page or feature]
Then I [see / am blocked from] [content or action]

Form submission

Given I [have / have not] filled in [required fields]
When I click [submit button]
Then [success state / error state]

Data display

Given [data condition]
When I view [page or section]
Then I see [expected content or state]

Notifications

Given [trigger condition]
When [action occurs]
Then [notification is sent / displayed within timeframe]

State transitions

Given I am in [state A]
When [action]
Then I am in [state B] and [observable change]

Generating Given-When-Then Acceptance Criteria Automatically

Writing acceptance criteria for every story takes time. For a sprint with 12 stories, you’re writing 30-60 individual Given-When-Then scenarios before development begins - and you still need to think through the edge cases.

Telos generates acceptance criteria automatically as part of its ticket creation workflow. When a feature comes up in a planning meeting or Slack discussion, Telos creates draft tickets with Given-When-Then acceptance criteria already written - including edge cases. You review, adjust, and approve before they go into Jira.

This doesn’t remove the judgment call - you still decide whether the scenarios are right. But the blank-page problem is solved.

For the broader acceptance criteria picture, read our guide on acceptance criteria. If you’re using Given-When-Then in user stories, the user story template post covers the full story format. And if you’re wondering how to get AI to generate these in context - book a demo of Telos.