Acceptance criteria and Gherkin examples: write Given/When/Then scenarios

What acceptance criteria are and why they matter

Acceptance criteria are the conditions that a user story or feature must satisfy before it is accepted as done. Each condition should be clear enough that two different people would reach the same verdict: pass or fail.

They matter for three practical reasons. First, they remove ambiguity before work begins, because writing a criterion forces you to decide what the system should do in a given situation. Second, they give developers a target, so there is less guessing. Third, they become the starting point for testing, including user acceptance testing. Most arguments late in a project are really arguments about what the criteria would have said if anyone had written them.

If you are new to stories, read how to write user stories first. Our free requirements practice example shows a smaller version of this exercise. This article goes deeper into the formats, especially Gherkin.

Three formats for acceptance criteria

There is no single required format. Choose the one that suits the team and the rule you are describing.

1. A plain checklist

The simplest form is a short list of testable statements. It works well for straightforward stories and for teams that are new to the idea.

• A signed-in customer sees the transfer form with source account, destination account and amount.
• A transfer larger than the available balance is refused and the balance is unchanged.
• A confirmation message shows the new balance after a successful transfer.

2. Given/When/Then scenarios (Gherkin)

Each scenario describes a starting situation (Given), an action (When) and an expected result (Then). This form shines when the behaviour depends on conditions, such as limits and statuses, and when you want the same text to be used as an automated test.

3. Rule tables

When the behaviour is a set of combinations, a table can be clearest. For example, a table of customer type and transfer amount against the approval needed. Tables are often used together with scenarios, as in the scenario outline later in this article.

Many teams mix formats: a short checklist for simple points and Gherkin for the logic-heavy ones. The test of a good format is that a developer, a tester and a business user all read it the same way.

Gherkin syntax in five minutes

Gherkin is a structured plain-language format. It has a small set of keywords.

A first scenario looks like this:

Feature: Transfer between own accounts

  Scenario: Transfer within the available balance
    Given a signed-in customer with 500.00 available in their current account
    When they transfer 200.00 to their savings account
    Then the transfer is confirmed
    And the current account balance is 300.00
    And the savings account balance is increased by 200.00

Read it aloud: it is understandable by a business user, specific enough to test and free of screen details. Those three qualities are the goal.

A worked example: transfers at a fictional bank

Kestrel Bank is a fictional bank. The story is: "As a customer, I want to transfer money between my own accounts, so that I can move money to where I need it without visiting a branch." The analyst, Sam, writes the acceptance criteria in three passes.

Pass 1: the normal case

The scenario above covers the main success path. Sam keeps it.

Pass 2: the failure cases

Sam asks "what could go wrong?" and finds several rules. Each gets its own scenario.

  Scenario: Transfer larger than the available balance is refused
    Given a signed-in customer with 100.00 available in their current account
    When they try to transfer 150.00 to their savings account
    Then the transfer is refused with the message "Insufficient funds"
    And neither account balance changes

  Scenario: Transfer of zero or a negative amount is refused
    Given a signed-in customer
    When they try to transfer 0.00 to their savings account
    Then the transfer is refused with the message "Enter an amount greater than zero"

  Scenario: Transfer to the same account is refused
    Given a signed-in customer
    When they choose the same account as source and destination
    Then the transfer is refused with the message "Choose two different accounts"

Pass 3: the boundaries and the data

Sam notices that the bank has a daily transfer limit. Boundary values are where defects like to hide, so Sam uses a Scenario Outline with an examples table. The angle-bracket names are placeholders filled from each row.

  Scenario Outline: Daily transfer limit
    Given a customer who has already transferred <already_sent> today
    And the daily limit is 1000.00
    When they transfer <amount>
    Then the transfer is <result>

    Examples:
      | already_sent | amount  | result   |
      | 0.00         | 1000.00 | accepted |
      | 0.00         | 1000.01 | refused  |
      | 900.00       | 100.00  | accepted |
      | 900.00       | 100.01  | refused  |

The table tests the exact limit, one cent above it and a combination with earlier transfers. Four rows give far more confidence than a sentence like "transfers cannot exceed the daily limit". While writing the table, Sam also discovers a question for the product owner: does a refused transfer count towards the limit? The answer goes into the criteria, and the ambiguity is gone before any code exists.

Good practice: how to write criteria that last

1. One rule per scenario. When a scenario fails, you should know which rule broke. Avoid scenarios with ten steps.
2. Describe behaviour, not the interface. Write "the customer confirms the transfer", not "the customer clicks the green button in the top right". Screens change; rules do not.
3. Use business language. Use words that appear in the glossary of the business. Our glossary can help you keep terms consistent.
4. Be specific with data. "A large amount" is vague; "an amount above the daily limit" or an exact value is testable.
5. Cover the three types of case. Normal, error and boundary. If you only write the normal case you are describing hope, not behaviour.
6. Include non-functional expectations where they matter. For example, "the confirmation appears within three seconds" or "the action is recorded in the audit log". See non-functional requirements.
7. Keep them short enough to read. Three to eight scenarios per story is typical; many more suggests the story is too big. See the splitting advice in the user stories guide.
8. Review them with a developer and a tester. The developer finds technical gaps; the tester finds ambiguity.

Common mistakes and how to fix them

Another common slip is to write criteria after the work is built. Criteria written after the fact tend to describe what was built, not what was needed. Write them during refinement, and update them if the team learns something during the sprint.

From criteria to tests and traceability

Each scenario is a candidate test case. Testers expand the scenario with detailed steps and data, and may automate it with tools that read Gherkin. Whether or not you automate, the link from criteria to tests is valuable: it shows that every requirement has been checked. A table that records that link is a requirements traceability matrix; see our guide to the traceability matrix and the worked traceability and UAT example.

Criteria also feed user acceptance testing. Business users run selected scenarios in the test environment and record pass or fail; see the UAT guide. And they support the team's definition of done, which usually includes "acceptance criteria verified".

To practise, take a story from your own work and write one checklist version and one Gherkin version of the same criteria, then compare which was clearer. The BA Lab includes tasks in which the checks flag vague words and missing error cases, so you can see what a reviewer would catch. Whichever route you choose, remember that the format is only a tool. The value comes from asking, for every rule, "how would we know?".

Frequently asked questions