Skip to main content

JIRA and other issue trackers

Key points

Linking from test scenarios to tickets​

Serenity BDD supports linking from test scenario results in the report to tickets in issue trackers such as Jira, Trello, GitHub Issues, GitLab Issues, and many others.

To make it work, you should tag your Cucumber scenarios with @issue and @issues as per the below listing:

@issue:WF-1
Feature: Weather forecast

  @issue:WF-2
  @issues:WF-3,WF4
  Scenario: Umbrella needed now

    Given it's currently raining
     When Alice asks "Do I need my umbrella now?"
     Then she should be told "Yes"

The @issue an @issues tags instruct Serenity to augment the reports with links to relevant tickets:

http://localhost:3000

Apart from improved navigation experience, another benefit of tagging your test scenarios with ticket IDs is that it helps Serenity understand what scenarios and features concern what tickets. This gives you another way to slice your reports, which can be particularly useful when you need to see all the scenarios that cover a given ticket:

http://localhost:3000

To make linking scenarios to tickets work, your test runner (such as Cucumber.js) must use Serenity/JS test runner adapter to emit SceneTagged event with an IssueTag pointing to the desired ticket when a test scenario is executed. The information about ticket identifiers associated with a given test scenario gets included in Serenity BDD json reports produced by SerenityBDDReporter. From there, it's picked up by Serenity BDD CLI and included in the Serenity BDD HTML report.

PRO TIP

Serenity/JS Cucumber Test Runner Adapter automatically links any scenarios tagged with @issue:<issueId> and @issues:<issueId1,issueId2,...>.

If you need this functionality for any other test runners, please raise a ticket on GitHub or submit a pull request.

Tagging Cucumber scenarios and features​

To indicate to Serenity/JS that you want your Serenity BDD report to link from a test scenario to a ticket in your issue tracker, you should tag your Cucumber.js scenario with a tag following one of the below formats:

  • @issue:<id> - to link to a single ticket,
  • @issues:<id1,id2,...> - to link to multiple tickets.
PRO TIP

Linking from a scenario to a ticket can be useful to indicate that the scenario was added to cover a specific defect reported in the issue tracker, or to provide additional context around the given feature or scenario.

In the example below, the first scenario will be linked to tickets: WF-1 (inherited from the Feature), as well as WF-2, WF-3, WF-4 the scenario is tagged with explicitly. The second scenario will be linked to ticket WF-1.

@issue:WF-1
Feature: Weather forecast

  @issue:WF-2
  @issues:WF-3,WF4
  Scenario: Umbrella needed now

    Given it's currently raining
     When Alice asks "Do I need my umbrella now?"
     Then she should be told "Yes"

  Scenario: Umbrella needed later

    Given it's currently not raining
      But there's a high likelihood of rain throughout the day
     When Alice asks "Do I need my umbrella now?"
     Then she should be told "Not yet, but you'll need it later"

It's important to note that different issue trackers use different naming conventions to identify tickets and to deep-link to them.

Read on to find out more about the approach that will work best in your case.

Working with Jira​

Atlassian Jira is project-centric and uses ticket identifiers that indicate both project ID and ticket sequence number, e.g. WF-123.

To link a test scenario to a ticket in Jira, you should use a Cucumber tag such as @issue:WF-1 or @issues:WF-3,WF4:

Linking to tickets in Jira
@issue:WF-1
Feature: Weather forecast

  @issue:WF-2
  @issues:WF-3,WF4
  Scenario: Umbrella needed now

To instruct Serenity BDD where your Jira instance is, provide the --jiraUrl argument when generating the report from the command line:

npx serenity-bdd run --jiraUrl=https://my-company.atlassian.net

Alternatively, you can specify the jira.url property in your serenity.properties file, which Serenity BDD will pick up automatically when executed:

serenity.properties
jira.url=https://my-company.atlassian.net

Working with GitHub and Gitlab​

GitHub and GitLab are code-centric systems that associate tickets with their relevant code repositories. They identify tickets using the #<id> naming convention, e.g. #123.

To link a test scenario to a ticket in GitHub or GitLab you should use a Cucumber tag such as @issue:#1 or @issues:#3,#4:

Linking to tickets in GitHub or GitLab
@issue:#1
Feature: Weather forecast

  @issue:#2
  @issues:#3,#4
  Scenario: Umbrella needed now

To instruct Serenity BDD where your GitHub or GitLab instance is, provide the --issueTrackerUrl argument when generating the report from the command line.

Note that --issueTrackerUrl is a template string where the {0} token gets replaced with the issue ID you've tagged your test scenario with (Serenity removes the # character from the ticket ID when generating the URL):

npx serenity-bdd run --issueTrackerUrl='https://github.com/my-namespace/my-project/{0}'

Alternatively, you can specify the serenity.issue.tracker.url property in your serenity.properties file, which Serenity BDD will pick up automatically when executed:

serenity.properties
serenity.issue.tracker.url=https://github.com/my-namespace/my-project/{0}