Connect your tests to Jira

In plain words

Jira is where your team keeps its requirements (the things the product must do) and its bugs. This page shows how to bring your requirements into StepTrails, send the test results back to Jira, and create a bug with one command when a test fails. StepTrails only reads issues, adds comments, creates bugs and links them. It never changes the status of an issue, and it never does anything unless you run the command.

You need test tracking set up, a Jira Cloud account, and a terminal.

1. Give StepTrails your Jira details

You need four settings. Creating bug tickets explains each one and how to make the token. Set them in the terminal window where you run the commands. Never put the token in a file.

Setting	What it is
JIRA_BASE_URL	Your Jira address, such as https://yourteam.atlassian.net
JIRA_EMAIL	The email you use to sign in to Jira
JIRA_API_TOKEN	A token from your Atlassian account. It works like a password for programs
JIRA_PROJECT_KEY	The short code at the start of your issue numbers, such as SHOP

2. Bring in your requirements

node bin/manage.js jira sync

StepTrails copies each issue's number, title, type and status into small files under .steptrails/manage/requirements. By default it copies every issue in your project that is not a bug. To choose differently, give your own Jira search:

node bin/manage.js jira sync --jql "project = SHOP AND labels = release-2"

Run it again whenever the issues change. It only updates what changed.

See what you have, and which requirements a passing test covers:

node bin/manage.js jira list

3. Tie your tests to requirements

Tell each test case which requirement it proves. Use the Jira number:

node bin/manage.js case set TC-0001 --requirement SHOP-1

A test can prove more than one requirement: --requirement SHOP-1,SHOP-2.

Your reports and the results page now show the requirement titles and their Jira status, next to whether a passing test covers them.

4. Send the results to Jira

When a round of testing is finished, send the results to the issues:

node bin/manage.js run finish RUN-20261025-1
node bin/manage.js jira push --run RUN-20261025-1

Each requirement gets one comment that lists its test cases and their result in this round, with the bug numbers if there are any. If you run the command again, StepTrails sees its earlier comment and does not add another one.

Want to see the comments first? Add --dry-run. Nothing is sent, and you see exactly what would be posted.

Notes you wrote on a result are not sent unless you add --with-notes. They may contain things that should stay with your team.

5. Create a bug when a test fails

node bin/manage.js jira bug --run RUN-20261025-1 --case TC-0002

StepTrails creates a bug in Jira with the steps to repeat the problem, marks the step that failed, and links the bug to the requirements that test proves. The bug number is saved on the result, so your reports show it. Add --dry-run to preview.

If Jira has no "Relates" link type, the bug is still created. StepTrails tells you which links did not work.

Good to know

• Only a comment, a bug and a link are ever created. Nothing is changed or deleted in Jira, and no status moves.
• Your token is read only from the settings. It is never printed or saved.
• The requirement files contain your Jira address and issue titles. Keep the project private, or look through them before you share them.
• If one issue cannot be found or you may not comment on it, the others are still sent, and you see which one failed.
• The same Jira settings also let you create a bug straight from a playback. See Create bug tickets.