How to Write Test Cases in Jira: Template and Example

Summarize Blog

Quick Summary

Three ways to set up test cases in Jira and where each breaks, a template with the fields worth filling in, one story written as a test case in plain steps and in Gherkin, and seven habits that keep test cases useful.

A story has just moved to “Ready for QA”. You know what to check. But the test cases have to work for other people too: the teammate who runs them next sprint, the developer reading a failure at 6 pm, the release manager asking what was tested. Jira gives you the story, its description and comments. It has no place built for test cases.

This guide is for testers and QA leads whose team already works in Jira. It covers the three ways to set up test cases in Jira, a template with the fields worth filling in, one story written as test cases in plain steps and in Gherkin, and the habits that keep a test case useful after its sprint ends.

We make AIO Tests, a test management app for Jira, and show how it handles test cases near the end. Everything before that works whichever setup you choose.

Where test cases can live in Jira

Jira has no test case type out of the box, so every team picks one of three setups. Most start with the first and move on as the number of tests grows.

	In the story	A “Test” work item type	A test management app
How it works	Steps in the story’s description, or one sub-task per test	A Jira admin adds a Test work item type (Jira used to call these issue types) with fields for steps and expected results	An app from the Atlassian Marketplace adds test cases, test runs and results to Jira
Set-up	None	Work item type, fields, screens and a workflow	Install it, then adjust fields if you need to
Next release	Copy and paste	Clone each test, or overwrite last release’s status	Add the same cases to a new test cycle
Result for each step	No	No, one status per test	Yes
History across releases	Gone when the story closes	Only if you clone a test for every run	Every run kept
Works well for	A handful of checks on a small team	A few hundred tests and a Jira admin with time	Regression suites, several testers, release reports

The middle option is where many teams get stuck. It costs nothing and keeps tests searchable with JQL, but on the second release you either clone every test or lose the first release’s results. A thread on the Atlassian Community asks what to do when one story has 500 test cases: 500 sub-tasks? Jira on its own wasn’t built for that volume.

Whichever setup you choose, the test case itself should look the same.

What a good test case contains

Use this as your template. In Jira alone, each row becomes a field on the Test work item type or a heading in its description. In an app, most are already there.

Field	What to write	Why it matters
Title	What should happen: “Invite link expires after 7 days”	People scan titles when choosing what to run
Linked story	The story or requirement it checks	Shows coverage, and puts the result on the story
Preconditions	The state before step 1: role, settings, data that must exist	The tester doesn’t have to guess the set-up
Test data	Exact inputs: email addresses, amounts, file names	Two testers get the same result
Steps	One action per step, in order	A failure points to one place
Expected result	What the tester should see after each step that changes something	Pass or fail stops being a judgement call
Priority	High for anything that must pass before every release	Decides what runs when time is short
Type and labels	Functional, regression or smoke; the feature area	Lets you build suites later
Status	Draft, under review or published	Unreviewed cases stay out of release runs

One story, written as test cases

WS-142 As a workspace admin, I can invite a teammate by email. The invite link expires after 7 days.

Three test cases cover it: the main path (someone is invited and joins), the expiry, and a mistake an admin might make (inviting someone who’s already a member). Here’s the expiry case in full.

Title: Invite link expires after 7 days
Linked story: WS-142
Preconditions: Signed in as a workspace admin. Access to a test inbox. The test server’s clock can be moved forward.
Test data: invitee@example.test

#	Step	Data	Expected result
1	Open Settings > Members and select Invite		The invite form opens
2	Enter the email address and send the invite	invitee@example.test	“Invite sent” appears, and the invite is listed as Pending
3	Move the server clock forward 8 days		The invite is listed as Expired
4	Open the invite link from the test inbox		A page says the invite has expired and offers to request a new one
5	Return to Settings > Members		invitee@example.test is not a member

The same behaviour in Gherkin, the Given/When/Then format used for behaviour-driven development (BDD):

Feature: Invite teammates by email

  Background:
    Given I am signed in as a workspace admin

  Scenario Outline: An invite link works for 7 days
    Given I invited "<email>" <days> days ago
    When the invitee opens the invite link
    Then they see "<page>"

    Examples:
      | email               | days | page            |
      | early@example.test  | 1    | Join workspace  |
      | late@example.test   | 8    | Invite expired  |

The Background holds set-up that every scenario shares, and the Examples table runs one scenario with several rows of data.

Which format to use: Gherkin suits teams that automate from feature files or write acceptance criteria with product owners. Plain steps suit manual testing and anyone new to the product. Many teams use both.

Seven habits that keep test cases useful

One behaviour per case. If the title needs “and”, split it.
Write for someone who has never seen the feature. Name the page, the button and the data.
Keep data out of the step text, so you can rerun the case with new data without rewriting it.
Give every step that changes something an expected result.
Reuse shared steps instead of copying them. Keep sign-in in one shared case; when the login page changes, you fix one case, not forty.
Search before you write. Duplicates make regression longer without testing anything new.
Update the case when the story changes, and keep the old version. A failure from last release only makes sense against the steps that were run.

After the sprint: organize, reuse and run

A test case earns its keep in the releases after the one it was written for.

Organize by feature, not by sprint. Folders like Billing > Invoices stay useful; sprint folders are clutter within months.
Build a regression set from the cases that must pass before every release.
Run cases in a test cycle for each release, so this release’s results don’t overwrite the last.
Turn a failed step into a bug that links back to the case and the story, so the developer sees the steps and the tester knows what to retest.
Show results on the story. When anyone can see a story’s test cases, latest results and open bugs without leaving it, “is this tested?” stops being a meeting.

To check that every requirement has tests, see our guide to traceability in Jira.

Try it on your next story

The quickest way to see whether your test cases work for other people is to hand one over. It takes about 30 minutes, with any setup:

Pick one story that’s ready for testing.
Write three cases with the template: the main path, one edge case and one mistake a user might make.
Ask a teammate who didn’t write them to run one without asking you anything.
Note every point where they paused or guessed. Each is a missing precondition, step or expected result.
Fix the case, link it to the story and mark it for regression if it should run every release.

If the gaps were mostly about keeping fields, versions and results in step by hand, that’s the part a test management app takes over.

Writing test cases in Jira with AIO Tests

In AIO Tests, test cases live inside the app and link to Jira stories and bugs, so there are no extra work item types to set up. You can write a case from the AIO Tests menu or straight from the panel on a story. Only the title is required at first, and each project can make other fields mandatory or hide the ones it doesn’t use.

Steps: an action, data and an expected result for each step, or Given, When and Then for a BDD case.
Reuse: add a published case as a step in another, from any project you can open. Shared set-up goes in Backgrounds, which classic and BDD cases can both use, more than one per case.
Datasets: one case can run with several rows of data.
Review and history: cases move from Draft to Under Review to Published, and earlier versions are kept when steps change.
AI drafts: AI can draft cases from a story’s summary and description, plus any files you add, as plain steps or Gherkin. You review each draft before saving. AI can also suggest missing steps in existing cases. It’s included in the price.
Existing cases: import them from Excel or CSV by mapping your columns to AIO Tests fields.

Cases then go into sets and test cycles. A failed step raises a Jira bug with its summary and steps filled in, and the story shows its cases, latest results and bugs.

Choosing between apps? Our guide to Jira test management tools compares the main ones, and we have side-by-side pages for Xray and Zephyr.

AIO Tests is free for Jira sites with up to 10 users. Try AIO Tests on the Atlassian Marketplace

Frequently asked questions

Can you write test cases in Jira without an app?

Yes. Add a Test work item type with fields for steps and expected results, or keep steps in the story or its sub-tasks. You won’t get a result per step or a history of runs, which is usually when teams add an app.

How do I write a test case in Jira, step by step?

Link it to the story, write the preconditions and test data, then add one action per step with its expected result. Have someone review it before it goes into a release run.

What should a Jira test case template include?

A title, the linked story, preconditions, test data, steps, an expected result for each step, priority, type or labels and a status.

Can AI write test cases from a Jira story?

Yes. Several apps, AIO Tests included, draft cases from a story’s text. Treat drafts as a first pass: AI only knows what the story says and any files you give it, so check preconditions, data and expected results before anyone runs them.

How do I move test cases from Excel into Jira?

Most test management apps import Excel or CSV and let you match your columns to their fields. Remove duplicates first; an import is a good moment to retire cases nobody runs.

How we checked: Jira behaviour from Jira Cloud as of October 2026. AIO Tests features from the AIO Tests Knowledge Base, checked on 30 October 2026. The example story and test cases are our own. Spot something out of date? Email help@aiotests.com and we’ll fix it.