How do I write testable acceptance criteria in Jira?

Write each acceptance criterion as one observable outcome that a tester could verify without asking you anything: what the system shows or does, under what conditions. “Expired promo code at checkout shows ‘This code has expired’ and keeps the cart total unchanged” is testable; “handle promo codes properly” is a wish.

That single rule does most of the work. The rest of this guide covers where criteria belong on a Jira issue, which format to use, and the specific phrasings that quietly make criteria untestable.

What makes a criterion testable?

A criterion is testable when it names a condition and an observable result, and a person who didn’t write the story can check it. Three properties get you there:

• Observable: the result is something you can see, measure, or assert (a message, a state change, a redirect, a value). “The user understands the error” is not observable; “the error names the field that failed” is.
• Specific: values are stated, not implied. “Large orders get free shipping” leaves “large” to be discovered in code review; “orders of $75 or more get free shipping” doesn’t.
• Self-contained: verifying it requires the story, not the author. If the tester has to ask what was meant, the criterion failed before the code did.

Where should acceptance criteria go on a Jira issue?

Put them in your site’s acceptance criteria custom field if one exists; otherwise, end the description with a clearly headed “Acceptance criteria” section. The location matters less than the consistency: pick one place per project so reviewers, testers, and any tooling always find criteria without hunting. Split locations (some criteria in the field, some in comments, some in a linked document) are how criteria get skipped in testing.

Avoid comments entirely for criteria. Comments are a conversation log, they don’t export, and nobody re-reads them before writing test cases.

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

Use a plain checklist by default, and Given/When/Then where the behavior depends on state. The checklist format is faster to write and easier to scan in refinement:

• Applying a valid promo code updates the order total before payment.
• An expired code shows “This code has expired” and leaves the total unchanged.
• Only one promo code can be active on an order at a time.

Given/When/Then earns its verbosity when preconditions matter: “Given a signed-in customer with a saved card, when the saved card has expired, then checkout shows the card update form before payment.” Write whichever the team will actually maintain; format religion produces worse criteria than either format used consistently.

What patterns make criteria untestable?

Four phrasings account for most untestable criteria. Each has a mechanical fix:

• Adverb criteria: “loads quickly”, “works smoothly”, “fails gracefully”. Replace the adverb with the number or behavior you actually mean.
• Implementation instructions: “add an index on the orders table”. That’s a task for the developer, not an outcome; state what the user or system observes instead.
• Bundled outcomes: “the customer can search, filter, and sort results”. Three behaviors, three criteria; bundles hide the one that fails.
• Negative space: “no bugs in checkout”. Unfalsifiable. Name the failure modes you care about: what happens on a declined card, an empty cart, a double-click on Place order.

How many criteria should a story have?

Three to seven, as a working range. Under 3 usually means unstated behavior that a developer will guess at (what does happen with two promo codes?). Over 7 usually means the story is two or three stories wearing one issue key, and it will estimate badly and test worse; split it while it’s still cheap. The count is a smell, not a rule: judge by whether every behavior someone will build or test is stated once.

How does Vindex score acceptance criteria?

Testability is one of the six INVEST dimensions Vindex scores on every Jira story. It reads the summary, description, and criteria the moment a story is created or edited, and flags exactly the patterns above: missing criteria, vague adverbs, bundled outcomes, unstated values. The finding appears in the issue panel in plain language (“Acceptance criteria are missing or untestable”) before refinement, when a rewrite costs minutes instead of a sprint. To see it against your own backlog, paste one story or drop a CSV and check the Testable score, no signup needed.