How do I write testable acceptance criteria in Azure DevOps?

Write each acceptance criterion as one condition and one observable result, in the work item’s Acceptance Criteria field, in language a tester can act on without messaging you. “Requesting a return label twice within an hour reuses the first label and shows the existing tracking number” is testable. “Return labels should work correctly” is a hope.

Azure Boards helps here more than most trackers: User Story and Product Backlog Item both ship with a real Acceptance Criteria field, so criteria have a home that queries, exports, and reviewers can find. The rest of this guide covers what belongs in it, which format to pick, and the phrasings that look like criteria but can’t be tested.

What makes a criterion testable in practice?

Read each line and ask one question: could a tester who has never seen this work item pass or fail it today? Three properties get you a yes.

• It names an observable result. Something the system shows, stores, sends, or refuses. “The customer is informed” is not observable. “The confirmation page shows the refund amount and the expected settlement date” is.
• It carries real values. Thresholds, limits, and formats belong in the criterion, not in someone’s memory. “Back-in-stock alerts are throttled” becomes “a customer receives at most 1 back-in-stock alert per product per 24 hours”.
• It stands alone. Verification needs the work item, not its author. If the tester has to ask what was meant, the criterion already failed, and it failed before any code was written.

A useful habit during refinement: read a criterion aloud and have the person who will test it restate it as a test case. Anything they can’t restate gets rewritten while everyone is still in the room.

Where do acceptance criteria go on the work item form?

Use the Acceptance Criteria field. On the Agile process it sits on User Story, on the Scrum process it sits on Product Backlog Item, and in both cases it renders as a rich-text box directly under Description on the work item form. That placement matters for a boring reason: everything that reads your backlog later, including query columns, CSV exports, and the Vindex panel, looks in the field, not in a paragraph buried halfway through a description.

If your project uses the Basic process, the Issue work item type has no Acceptance Criteria field. Two options, in order of preference: move the team to Agile or Scrum if the backlog is real product work, or end every Description with a clearly headed Acceptance criteria section so at least the convention is consistent. Do not scatter criteria across the Discussion thread. Comments are where criteria go to die: they aren’t in the exported field, they aren’t on the printed card, and nobody reads them at sprint planning.

One more Azure Boards specific: because the field is HTML, a bulleted list stays a bulleted list everywhere it renders. Put one criterion per bullet and resist sub-bullets. Nesting is where “and also” requirements hide.

Should I use a checklist or Given/When/Then?

Use a plain checklist by default. Use Given/When/Then when the behaviour depends on state, and never mix the two formats inside one work item.

A checklist reads fast and covers most stories:

• Return requests inside the 30-day window create a prepaid label immediately.
• Return requests outside the window are refused with the reason and the order date shown.
• Requesting a second label for the same order within 1 hour returns the original label.

Given/When/Then earns its extra words when the same action produces different outcomes depending on prior state, which is exactly the case that breaks in production: “Given an order that has already been refunded, when the customer requests a return label, then the request is refused and the refund date is shown.” If you find yourself writing Given/When/Then for every line, the format has become ceremony. Drop back to the checklist.

What patterns make criteria untestable?

Five phrasings account for most of it. They all pass a casual read at refinement and all fail the moment someone tries to verify them.

• Adjectives standing in for numbers. Fast, reasonable, large, minimal. Replace with the number you would argue for: “the label PDF is available within 5 seconds”.
• Implementation instead of outcome. “Add a RabbitMQ consumer for label events” describes work, not a result a tester can check. Keep the how in Tasks; keep the what in the criteria.
• Compound criteria. Any line containing “and” between two different behaviours is two criteria, and it will be half-delivered.
• Happy path only. Payment declines, expired sessions, missing addresses, and duplicate requests are where defects live. If every criterion succeeds, the unhappy paths aren’t missing from the code, they’re missing from the conversation.
• Criteria that repeat the title. “Customer can request a return label” on a work item titled “Customer requests a return label” adds nothing. Every criterion should tell the reader something the title didn’t.

How many criteria should one work item have?

Between 3 and 7 for most User Stories. Under 3, the unhappy paths are usually missing. Over 7, you are almost certainly looking at two or three stories wearing one title, and the fix is to split it rather than to trim the criteria. That decision has its own guide: how to split oversized work items in Azure DevOps.

How does Vindex read acceptance criteria?

Vindex reads the Acceptance Criteria field on every work item create and update, alongside the title and description, and scores whether the criteria are actually testable rather than merely present. A work item with three vague bullets scores lower than one with three specific ones, and the finding says which criterion is the problem and why, in plain language on the work item form. No custom fields, nothing written back onto your work items.

You can see it on your own backlog before installing anything: paste one work item or drop a CSV export and read the findings yourself. No account needed, and demo uploads are deleted after 24 hours.