Guide
How to write Gherkin scenarios in a Jira story
By Miftode Vasilica, maker of Gherkin Studio ·
To write Gherkin in Jira you need three things: a place on the story to keep the text, something that checks the syntax while you type, and a way to get the same text into your repository as a .feature file. Jira has none of them built in, so teams either paste scenarios into the description or install an app. This guide shows the second route, with the mistakes that cost the most time.
Thursday, 15:40, refinement
The story on the screen says "Password reset". Somebody asks how long the link stays valid. Nobody knows. Somebody else says an hour, the product owner nods, and the meeting moves on.
Two weeks later the tester finds the link works for a day. Nobody wrote the hour down.
That sentence, "the link expires after one hour", is what a scenario is for. It takes forty seconds to write while everybody is still in the room:
@PROJ-12
Feature: Password reset
Scenario: Link expires after one hour
Given I requested a reset link 61 minutes ago
When I open the link
Then I see "This link has expired"
Notice the 61. A scenario with a real number in it starts an argument now, when the argument is cheap.
Where the text lives
In the description. It works on day one. Then the description gets edited, the indentation goes, and no tool can read the scenarios back out.
In a panel on the story. A BDD app adds a panel that holds only Gherkin. In Gherkin Studio it is called Scenarios, and it sits on every Jira issue. Start from template gives you a first scenario to change, which is quicker than an empty box.
What the editor does for you
- Suggests steps your team already wrote. Type
Given,When,Then,AndorButand the steps already used in the project appear. Press Tab to take the first one. Reusing a step word for word is what keeps the automation small: one step definition serves twenty scenarios. - Explains errors in plain English. The message sits under the editor. Click Line N and the cursor jumps there.
- Lines up tables. Format tables aligns every column. Doc strings are left exactly as you typed them.
- Saves without stepping on a colleague. Ctrl or ⌘ + S saves. If someone else saved the same story while you were typing, you are told, and their work stays.
Anyone who can edit the issue can edit its scenarios. Anyone who can see the issue can read them.
Three mistakes the syntax check will not catch
These are valid Gherkin, so no parser complains. We ran each one through the official Cucumber parser to be sure.
1. A step with no scenario above it.
Feature: Password reset
Given I requested a reset link
This parses. The second line is read as the feature's description, plain text, and you have a feature with zero scenarios. Nothing will ever run.
2. Scenario without the colon.
Scenario Link expires is description text too. So is everything under it, until the next line that does start with a real keyword.
3. A typo in the first step.
Givn I requested a reset link, straight under Scenario:, becomes the scenario's description. The scenario exists, with no steps, so it checks nothing.
The tell is the same in all three: the line is not coloured like a keyword. If Given does not light up, the parser did not see a step.
Scenarios in another language
Start the text with a language header and write the keywords in that language:
# language: fr
Fonctionnalité: Mot de passe oublié
Scénario: Le lien expire après une heure
Soit un lien demandé il y a 61 minutes
Quand j'ouvre le lien
Alors je vois "Ce lien a expiré"
Every language in the Gherkin reference works, because the editor uses the official Cucumber parser.
Short answers
Can I write Gherkin in Jira without an app?
Yes, in the description or a text field. You get no syntax check, no step suggestions and no .feature file.
Who should write the scenario?
Whoever is in the room when the question comes up. The wording gets fixed later; the example has to be caught now.
How many scenarios should one story have?
Enough to cover each rule once. If a story needs more than eight or so, it is usually two stories.
Where Gherkin Studio fits
Gherkin Studio is a BDD app for Jira Cloud, built on Atlassian Forge. The editor on this site's home page is a simplified copy of the one inside Jira; you can try it in the browser without installing anything. The app is on the Atlassian Marketplace. See how the editor works.