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.