Documentation
Stepwise Test Management for Jira: user guide
Everything the app does, in the order you will meet it: setup, test cases, cycles, runs, defects, coverage, reports, imports and the details admins ask about.
On this page
- Getting started
- Setup for space admins
- Writing test cases and steps
- Test cycles
- Running tests
- Defects
- Coverage and requirements
- The transition check
- Reports
- Import test cases from CSV
- Import a JUnit XML report
- JQL fields
- Premium features
- Permissions
- Data and privacy
- Limits
- FAQ
- Troubleshooting
- Not available yet
Getting started
Stepwise Test Management for Jira is a Jira Cloud app. A Jira admin installs it from the Atlassian Marketplace and approves its permissions (explained under Permissions). Then a space admin sets it up for each space that does testing.
A test case is an ordinary Jira work item. The app creates no work types, fields or screens. It adds panels to work items, a Tests page to the space, and a workflow validator.
- A space admin opens the space’s app settings and chooses which work types are tests and requirements (see Setup).
- Create a test work item and write its steps in the Test panel.
- Open the space’s Tests page, create a cycle, add tests and run them.
Setup for space admins
Open Space settings, then Apps, then Test management. You need to be a space admin. Settings are kept per space.
- Test cases: the work type that means “this is a test case”. Work items of this type get the Test panel.
- Requirements and coverage: the work types you want to cover with tests, for example story and epic. These get the requirement panel.
- Link type for coverage: an ordinary Jira link type. A link of this type from a test to a requirement counts as coverage.
- Work type for defects: the type of work item created from a failed step, usually Bug.
- Environments: the list you pick from when you create a cycle, for example Staging or Production.
The transition check is set up in the workflow, not here. See The transition check.
If you change which work type is the test type later, existing work items of the old type keep their steps and results in the app’s storage, and they come back when you mark that type again.
Writing test cases and steps
Open a test work item and find the Test panel.
- Precondition: what must be true before the test starts.
- Steps: each has an Action, Test data and an Expected result.
- Reorder: drag a step by its handle.
- Duplicate a step, or copy steps from another test.
- Paste many steps: paste a list from a spreadsheet or plain text and the app makes one step per line (or per row, when columns are pasted).
- Capacity: a test holds up to 200 steps. A capacity meter appears near the limit and suggests splitting the test into two.
Steps are stored by the app. The work item’s summary, description, labels, components and links are normal Jira fields, so search, boards and filters work as usual.
Test cycles
A cycle is a set of tests you run together. Open the space’s Tests page and choose Create cycle.
- Name, description and environment.
- Version: chosen from the space’s Jira versions.
- Sprint or milestone label: a short text, for example “Sprint 31”.
- Add tests: by a JQL query, or by picking keys.
- Testers: assign one or more people to the cycle.
- Close and reopen a cycle when the work is done or needs more.
Running tests
Open a cycle and select a test, or press Run next test.
- Status of the test: Pass, Fail, Blocked, Skipped or Not run.
- A result per step: mark each step, and write the actual result and a note.
- Timer: start it to record time spent. It is added to the reports.
Steps are frozen at the first result
When you record the first result, the app keeps a copy of the steps as they were. If someone edits the test later, the run shows the test changed since. What was executed stays as it was. Choose Run again to run the test with the current steps.
Defects
- Create a defect: on a failed step, press Create defect. The app creates a work item of the defect type with the steps up to the failing one, the expected and the actual result, and the cycle and environment. It is linked to the test and recorded on the run.
- Link an existing defect: enter its key.
The defect is created as you, so Jira permissions apply: you need permission to create work items in the project.
Coverage and requirements
Link a test to a requirement with the link type your space admin chose. Then:
- The requirement panel shows its tests, their latest results and their defects.
- The Coverage page lists requirement, tests, latest result and defects, and the requirements that have no tests.
- Search with JQL, for example
type = Story AND (coveringTests = 0 OR coveringTests is EMPTY)for stories with no tests (see JQL fields).
The transition check
A workflow validator keeps a requirement from moving on until its tests have passed. For example, you can hold the move to Done.
- Open the workflow of the requirement’s work type in edit mode.
- Select the transition, for example the one to Done, and open Validators.
- Add the Stepwise Test Management validator and publish the workflow.
- The requirement passes when the latest result of every linked test is Pass.
- Optionally, it is also refused when it has no tests.
- The decision is made from the app’s own storage, not from a field that anyone can edit.
Whoever may edit that workflow in Jira can add the validator.
Reports
- Cycle progress and pass rate.
- Results by tester and by component.
- Flaky tests: tests whose results keep flipping between Pass and Fail.
- Time spent from the timers.
- Defects found.
- What needs attention: failed, blocked and not-run tests.
- CSV export of a cycle for a spreadsheet or a status mail.
Import test cases from CSV
Bring test cases from a spreadsheet or another tool.
- Open the Import tab on the Tests page and choose your CSV file.
- Name the columns ID, Summary, Precondition, Action, Data, Expected and Labels (a sample CSV is offered to download). The file is parsed in your browser, not sent anywhere.
- Read the preview: it shows problems per line, so you can fix the file before anything is created.
- Start the import. Test work items are created in batches, with progress shown, and as you.
Import a JUnit XML report
Take the JUnit or xUnit XML report that your CI produces and import it into a cycle.
- Open the cycle and choose Import JUnit XML.
- Pick the file. It is read in your browser.
- Results are matched to tests by work item key or by name. Review the matches, then import.
This is a file import. The app has no live connection to a CI server, no REST API and no webhooks, so nothing arrives by itself. Import the report when your pipeline has produced it.
JQL fields
Use these in any Jira search, filter or board, and in a cycle’s JQL when you add tests.
| Field | What it finds | Example |
|---|---|---|
testResult | Tests by their latest result | testResult = "fail" |
testRuns | Tests by their runs | testRuns > 0 |
testSteps | Tests by their steps | testSteps > 10 |
testCoverage | Requirements by the state of their tests | testCoverage = "failing" |
coveringTests | Requirements by how many tests cover them | coveringTests >= 2; a requirement that never had a test has no value, so add OR coveringTests is EMPTY to find it |
Permissions
Who can do what
| Action | Who |
|---|---|
| Choose test and requirement work types, link type, defect type, environments | Space admins |
| Write steps, create cycles, run tests, log results | People who can edit work items in that space |
| Create a defect from a failed step | People who can create work items in the defect’s project |
| Add the validator to a workflow | Whoever may edit that workflow in Jira |
| Read tests, results and coverage | People who can see the work items in Jira |
What the app is allowed to do
When the app is installed, Jira asks the admin to approve five permissions:
| Permission | Why the app needs it |
|---|---|
| Read Jira work | To read test cases, requirements, versions, links and the current person’s view of them |
| Write Jira work | To create test work items from an import, create defects and links, and keep results connected to work items |
| Read user names | To show testers and who recorded a result |
| App storage | To keep steps, cycles, results and settings in your Atlassian cloud |
| Personal data reporting | So Atlassian can ask the app to update or erase personal data it holds |
Data and privacy
- The app runs on Atlassian Forge. Data stays in your Atlassian cloud. Nothing is sent to any other server.
- There is no analytics and no AI.
- Actions you take, such as creating a test, a defect or an import, are made as you.
- CSV and JUnit XML files are parsed in your browser.
- The transition check decides from the app’s own storage, not from a field that anyone can edit.
More detail: Security and data. Legal wording: Privacy policy.
Limits
| Item | Limit |
|---|---|
| Steps per test | 200 (a capacity meter appears near the limit) |
The app shows a message in the place where you reach any other limit.
FAQ
- What is Stepwise Test Management for Jira?
- It is test case management inside Jira Cloud. You write test cases with steps, group them into test cycles, run them, log results and defects, and see which requirements are covered.
- Does it add work types, fields or screens?
- No. A test case is an ordinary work item of the work type your space admin marks as Test in the app’s space settings. Requirements are the work types you pick, for example stories and epics.
- How do tests link to requirements?
- With an ordinary Jira link type that your space admin chooses. A link of that type from a test to a requirement counts as coverage.
- Do the steps change after I run a test?
- No. The steps are frozen at the first result. If the test is edited later, the run shows that the test changed since, and you can run it again with the current steps.
- Can I create a defect from a failed step?
- Yes. One click creates a bug with the steps up to the failing one, the expected and actual result, the cycle and the environment. It is linked to the test and recorded on the run. You can also link an existing defect by key.
- Can it stop a requirement from moving to Done?
- Yes. Add the workflow validator to a transition. The requirement waits until the latest result of every linked test is Pass, and optionally until it has at least one test. The docs show how.
- Can I import my existing tests and results?
- Yes. Import test cases from a CSV file, with a preview of problems per line. Import a JUnit or xUnit XML report into a cycle; results are matched to tests by work item key or by name. Both files are read in your browser.
- Is there a REST API or a live CI connection?
- Not today. You import a JUnit XML report from any CI into a cycle.
- Can I search tests with JQL?
- Yes:
testResult,testRuns,testSteps,testCoverageandcoveringTests, for exampletestCoverage = "failing"ortestResult = "fail". - Where is my data?
- In your Atlassian cloud. The app runs on Atlassian Forge, uses no external servers and no analytics.
- Does it support dark theme and small screens?
- Yes. It follows each person’s Jira theme and works on narrow screens.
Troubleshooting
- A work item has no Test panel.
- Its work type is not marked as Test in the space settings. Ask a space admin.
- A requirement shows no tests.
- The test must be linked with the link type your space admin chose, and the requirement’s work type must be marked as a requirement.
- A transition is refused.
- The message names the tests that have not passed. Run them again, or link a test if the requirement has none.
- A run says the test changed since.
- The steps were edited after the first result. Choose Run again to run the current steps.
- A JUnit result was not matched.
- Matching is by work item key or by name. Check that the test name in the report is the same as the work item, or put the key in the test name.
- Some CSV lines were not imported.
- The preview lists problems per line. Fix them in the file and import again.
Still stuck? Contact support.
Not available yet
These are not in the app today. We list them so that you know what not to look for yet. There are no dates attached.
- Automatic result intake from a CI server (you import a JUnit XML report instead)
- A REST API and webhooks
Missing something else? Tell us.