Guide
Acceptance criteria and Given/When/Then in Jira: rules first, examples second
By Miftode Vasilica, maker of Gherkin Studio ·
An acceptance criterion is a rule the story must satisfy. A Given/When/Then scenario is one concrete example of a rule. They are not the same thing, and a story needs both. Trying to write every criterion as Given/When/Then is how a team gets tired of Gherkin. This page shows how to keep the two apart, and where each one lives in Jira.
The scenario that says nothing
A story, "Password reset", has three acceptance criteria in its description:
- A reset link works for one hour.
- A reset link works once.
- The email does not say whether the address has an account.
Somebody has read that criteria should be written in Gherkin. An hour later the description says:
Scenario: Reset link validity
Given a user has a reset link
When the user uses the reset link within the validity period
Then the reset link works
It is longer than the criterion. It says less. And it cannot be argued with, because there is no number in it. Is 60 minutes "within"? Nobody can tell, and that was the one question worth asking.
Rule and example
| Acceptance criterion | Scenario | |
|---|---|---|
| What it is | A rule | One case of the rule |
| Sounds like | "A reset link works for one hour" | "A link opened after 61 minutes is refused" |
| Has real values | Sometimes | Always |
| Can be run as a test | No | Yes |
| How many | One per rule | One or two per rule, at the edge |
The criterion stays a plain sentence. The scenario answers a different question: show me a case.
Gherkin has a keyword for this
Since version 6, Gherkin has Rule:. It groups the scenarios that illustrate one rule. Example: is another spelling of Scenario:, and reads better under a rule.
@PROJ-12
Feature: Password reset
Rule: A reset link works for one hour
Example: Opened after 59 minutes
Given I requested a reset link 59 minutes ago
When I open the link
Then I can choose a new password
Example: Opened after 61 minutes
Given I requested a reset link 61 minutes ago
When I open the link
Then I see "This link has expired"
Rule: A reset link works once
Example: Opened a second time
Given I already reset my password with a link
When I open the same link
Then I see "This link has already been used"
The first two criteria are still there, word for word, as the two rules. Under each one sits the proof. The third comes in a moment.
Notice 59 and 61. Two examples on either side of the limit say more than ten in the middle. And the first time somebody reads them aloud, somebody else asks about exactly 60. That is the conversation the story needed.
A routine for refinement
For each criterion on the story, ask one question: can you give me an example?
- If the answer comes with a number, a name or a date, write it down as an example. Then ask for the one just past the limit.
- If the answer is "well, it just works", the rule is not understood yet. That is worth knowing before the sprint starts.
- If no example is interesting, the criterion does not need a scenario. "The button uses the brand colour" is checked by looking at it.
The third criterion above has no example yet. In the room, somebody will say: "Ask for a reset with an address we do not have. What does the page say?" That is the example.
Where each one lives in Jira
The criteria are sentences. Teams keep them in the story's description, or in a custom field they added for the purpose. Either works. They have to be easy to read, not easy to run.
The scenarios are text that a test runner will read later. They need a place that keeps Gherkin as Gherkin: indentation kept, syntax checked, and a way out to a .feature file. In a description they tend to lose all three the first time somebody edits the story.
In Gherkin Studio that place is the Scenarios panel on the issue. Rule: and Example: are coloured and checked like every other keyword.
Three things about Rule: that surprise people
We checked each one with the official Cucumber parser.
- Rules do not nest. A second
Rule:always starts a new rule, however far you indent it. - Indentation decides nothing. A scenario written after a rule belongs to that rule, even if you move it back to the left margin. Scenarios that belong to no rule must come before the first
Rule:. - A tag on a rule applies to every example under it.
One caution before you commit files with Rule: in them: older test runners do not know the keyword. Check that yours does.
Short answers
Should acceptance criteria be written in Given/When/Then?
The rule, no: one plain sentence is clearer. The examples of the rule, yes.
How many scenarios does one criterion need?
Usually two: one just inside the limit and one just outside. A criterion with no limit often needs one.
Does every story need scenarios?
No. Write them where a rule can be misunderstood. A story that changes a label does not need a scenario.
Can I write the examples without the Rule: keyword?
Yes. Plain scenarios under the feature work the same way. Rule: only keeps each example next to the sentence it proves.
Where Gherkin Studio fits
Gherkin Studio is a BDD app for Jira Cloud, built on Atlassian Forge. It is on the Atlassian Marketplace, with a 30-day free trial. See how to write scenarios in a Jira story and when a Background helps.