Method · Acceptance criteria

Acceptance criteria for frontends, in Given/When/Then

An acceptance criterion describes one behaviour a user can observe, written as Given a starting state, When an action, Then a result. Every criterion we write becomes an automated test, so the spec is checked on every change, not once at the end.

Updated 22 November 2026

What an acceptance criterion is

An acceptance criterion is a short, testable statement of how the interface must behave. We write each one in Given/When/Then: the starting state, the user’s action and the observable result. Each criterion describes exactly one behaviour, so a failing test points at exactly one problem.

The format comes from behaviour-driven development, and its value is precision. “The checkout handles errors well” cannot be tested. “Given the payment service is unavailable, When the member submits payment, Then an error explains that no charge was made and the form keeps their entries” can. Writing the second version forces the questions that otherwise surface late: which error, what copy, what happens to the data the member typed.

We write criteria from the user’s side of the screen. They describe what a person sees, hears or can do, never which function is called. That keeps them stable when the implementation changes, and readable by a product owner who does not read code.

Criteria for every state, not just the happy path

Most frontend defects live outside the main flow: loading, empty, error, partial and offline states. We write criteria for each state a component can be in, because a state without a criterion is a state nobody designed. The spec lists the states first, then the criteria cover them.

Feature: Order history

  Scenario: Member with no orders
    Given a signed-in member with no past orders
    When they open order history
    Then they see "No orders yet" and a link to the catalogue
    And no empty table or column headers are shown

  Scenario: Slow response
    Given the orders request takes longer than 1 second
    When the member opens order history
    Then a skeleton list is shown in place of the rows
    And the page layout does not shift when the rows arrive

The second scenario also protects a performance budget: “does not shift” is a layout stability rule that a test can measure.

Errors and recovery

For errors, a criterion has to say three things: what the user is told, what happened to their data, and what they can do next. We write one criterion per failure the plan can produce: validation, network, server and permission errors. Then no failure reaches users without designed copy and a recovery path.

Feature: Member checkout

  Scenario: Payment service unavailable
    Given the payment service returns an error
    When the member submits payment
    Then a message says the payment did not go through and no charge was made
    And the entered address and delivery choice are kept
    And focus moves to the message

  Scenario: Session expired during checkout
    Given the member's session expired while the form was open
    When they submit the form
    Then they are asked to sign in again
    And after signing in they return to checkout with their entries restored

Privacy and security as criteria

Privacy and security rules are behaviours too, so we write them as criteria. “No tracking before consent” becomes a statement a test can check by watching network requests. That turns a policy into something that fails the build when it is broken.

Feature: Consent before storage

  Scenario: First visit
    Given a visitor with no stored consent choice
    When the home page loads
    Then no request is made to any third-party domain
    And nothing is written to cookies or local storage except "consent_pending"

Feature: Session security on shared devices

  Scenario: Idle timeout
    Given a signed-in member who has been inactive for 15 minutes
    When they interact with the page
    Then they are signed out and see why
    And the session cookie is no longer valid on the server

Accessibility as criteria

WCAG 2.2 AA is set in the constitution, and specific criteria make it concrete for each feature. We write what a keyboard user and a screen-reader user must be able to do. Automated checks catch part of WCAG, so these criteria also guide a manual pass on new interactive UI.

Feature: Spending limit step

  Scenario: Keyboard only
    Given a member using only a keyboard
    When they reach the spending-limit step
    Then they can choose daily, weekly, monthly or "no limit" with arrow keys
    And the focused option has a visible focus indicator with 3:1 contrast

  Scenario: Screen reader
    Given a member using a screen reader
    When the limit is saved
    Then the confirmation "Monthly limit saved" is announced without moving focus

How a criterion becomes a test

Every criterion gets an ID in the spec and at least one automated test that cites that ID. End-to-end behaviour runs in Playwright against a real browser. Logic such as validation and state changes runs in Vitest. Accessibility checks run with axe inside the Playwright suites.

// checkout.spec.ts · covers AC-7 "Payment service unavailable"
test('AC-7 payment error keeps entries and explains no charge', async ({ page }) => {
  await page.route('**/payments', (r) => r.fulfill({ status: 503 }));
  await page.goto('/checkout');
  await page.getByLabel('Address').fill('1 Example Street');
  await page.getByRole('button', { name: 'Pay' }).click();
  const alert = page.getByRole('alert');
  await expect(alert).toContainText('no charge was made');
  await expect(alert).toBeFocused();
  await expect(page.getByLabel('Address')).toHaveValue('1 Example Street');
});

The ID in the test name is what makes the trace report possible. At release, every criterion is listed with the test that covers it and its result. A criterion without a passing test means the work is not done.

How to tell a good criterion from a weak one

A good criterion is observable, singular and specific. It names a state and an action, and gives one result a test can check. A weak criterion uses words like “fast”, “intuitive” or “handles”, which nobody can test. We rewrite weak criteria until two people would write the same test for them.

Weak Strong
The form validates input Given an email without “@”, When the member leaves the field, Then “Enter an email address like name@example.com” appears below it
The page loads quickly Given a mid-range phone on 4G, When the page loads, Then the largest content appears within 2.5 s
Errors are handled Given the server returns 500, When the member saves, Then a message offers to retry and their changes are kept
It is accessible Given a keyboard user, When they open the menu, Then focus moves to the first item and Escape closes it

Where to start

Start with the states. List every state of the feature, then write one criterion for each before you think about components. Our feature spec template has the sections in the order we fill them. In a Spec Sprint we write these criteria with you, so you see the scope in plain sentences before anything is built.

Start with a Spec Sprint

One to two weeks to a versioned spec you own, whoever builds it.

Start a Spec Sprint