Guide
Link Cucumber scenarios to Jira issues with tags
By Miftode Vasilica, maker of Gherkin Studio ·
The simplest way to link a Cucumber scenario to a Jira issue is a tag with the issue key above the scenario: @PROJ-123. The tag travels with the text. It is in the .feature file, in the test report, and in any export, so every tool along the way can put the scenario back on the right story. This page covers where to put the tag, the forms that work, and the ones that quietly do not.
The spreadsheet nobody wants to make
A team has four hundred scenarios in a repository and three hundred stories in Jira. They change BDD apps. The new app asks one question for each scenario: which story is this?
If the keys are in the files, the answer takes a second. If they are not, somebody opens a spreadsheet, and two people spend a week matching scenario names to story titles from memory.
The tag costs ten characters when you write the scenario. It is the cheapest insurance in the whole file.
Where the tag goes
On the scenario, when a feature file holds scenarios for several stories:
Feature: Password reset
@PROJ-12
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"
@PROJ-19
Scenario: A used link cannot be used again
Given I already reset my password with a link
When I open the same link
Then I see "This link has already been used"
On the feature, when the whole file belongs to one story. Every scenario in the file inherits it:
@PROJ-12
Feature: Password reset
Both, when one scenario also proves something for a second story. A scenario tagged with two keys counts for both.
Forms that work
Gherkin Studio reads these as "this belongs to PROJ-12":
| Where | Form |
|---|---|
| Tag | @PROJ-12 |
| Tag with a prefix | @jira:PROJ-12, @issue=PROJ-12, @story_PROJ-12 |
| Comment at the top of the file (import only) | # Jira: PROJ-12 |
| File name | PROJ-12.feature |
When a file is imported, the order is: a tag on the feature, the comment at the top of the file, tags on single scenarios, then the file name. For test reports it is: tag on the scenario, tag on the feature, file name.
Forms that quietly fail
- Lower case.
@proj-12is an ordinary tag. Jira keys are upper case, and so is the match. - A key inside a longer tag.
@PROJ-12-smokeor@wip-PROJ-12is not read as a key. Use two tags:@PROJ-12 @smoke. - A space after the @.
@ PROJ-12is not a tag at all. - The key only in the scenario name.
Scenario: PROJ-12 link expiresreads well and links nothing. - A folder named after the key.
PROJ-12/reset.featureis not matched. Only the file's own name counts.
None of these produces an error. The scenario simply ends up in the "could not match" list, which is why that list is worth reading.
Check the tags before you need them
Two places tell you which scenarios have no story:
- At import. The preview lists every file and scenario that could not be matched, with the reason, before anything is written to Jira.
- After every test run. The answer to the report call has a count of
unmappedScenariosand a list ofunknownIssues, keys that are tagged but do not exist in Jira.
A story that was moved to another project gets a new key. The old key in the file becomes an unknown issue. That is the usual cause when a result stops showing up on a story that used to have one.
Short answers
Can one scenario belong to two stories?
Yes. Put both tags on it.
Do tags slow the tests down?
No. Cucumber only uses tags to select what to run.
Should I also put the key in the file name?
For one story per file, yes: PROJ-12.feature. It is what Gherkin Studio's Git sync writes, and it survives if somebody deletes the tag.
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 the import guide and how test results reach the story.