Zephyr for JIRA Tutorial: Test Management Tool

Zephyr is one of the most widely used test management solutions for Atlassian Jira. Acquired by SmartBear in 2021, the Zephyr family now includes Zephyr Squad (formerly Zephyr for Jira), Zephyr Scale (formerly TM4J), and Zephyr Enterprise. SmartBear reports that tens of thousands of customers across more than 100 countries use Zephyr products every day to ship software faster.

Zephyr Squad is the native Jira application that brings quality test management capabilities into any Jira Cloud or Data Center project. When Zephyr is used inside Jira, tests can be created, viewed in any Jira project, and executed immediately or as part of a structured test cycle that links to other Jira issues. Detailed testing metrics are tracked through customizable Zephyr dashboard gadgets.

Zephyr provides multiple deployment options:

1. Zephyr Squad for Jira Cloud
2. Zephyr Squad for Jira Data Center
3. Zephyr Squad for Jira Server (end-of-life February 2024)

This tutorial covers Zephyr Squad and its features in detail.

Features of Zephyr Squad for Jira

• Native to Jira, so users can author and run tests without leaving the project they already work in.
• Testing is integrated with project cycles, which enables teams to track software quality and make informed go/no-go decisions each sprint.
• Create, plan, and execute tests using the Test issue type that Zephyr adds to every Jira project.
• Create, view, and modify test steps and attachments for individual tests. Build test execution cycles, run the tests, and link defects back to specific test steps.
• Track quality metrics through ready-made Zephyr gadgets such as Test Execution Burndown, Traceability, and Top Failing Tests.
• Support for REST API, ZAPI, and CI/CD integrations with Jenkins, Bamboo, and GitHub Actions for automated test result imports.

Zephyr Squad vs Zephyr Scale: Which One Should You Use?

SmartBear sells two Jira-focused test management products, and confusing them is the most common mistake new users make. Picking the right one depends on team size, governance needs, and how much test reuse you require across projects.

• Zephyr Squad – The lightweight Jira-native option covered in this tutorial. It stores tests as Jira issues of type Test, supports ZQL searches, and is ideal for agile teams that want test management directly inside their existing Jira board.
• Zephyr Scale – The enterprise option (formerly Test Management for Jira, or TM4J). It stores tests outside the Jira issue tracker, supports a reusable test library, custom statuses, parameters, Gherkin BDD steps, and folder hierarchies. Better suited for large QA organizations with regulatory or audit needs.
• Zephyr Enterprise – A standalone web application that operates outside Jira. It is aimed at organizations that need cross-tool reporting beyond Atlassian.

If you are an agile squad of fewer than fifty testers who live inside Jira, Zephyr Squad is the right starting point. If you need shared test libraries across many projects or formal compliance reporting, evaluate Zephyr Scale instead.

How to Use Zephyr Squad for Jira Test Management

Before you start, set up an instance of Zephyr Squad. Either start a free trial of Zephyr Squad or purchase a license from the Atlassian Marketplace. Confirm that the Zephyr Squad add-on is installed and enabled by your Jira admin, and that your user account has permission to create and edit Test issues in the target project.

Create a Test

Steps:

1. To create a test case (an issue with type Test), click the Create button in the top menu navigation.

2. The Create Issue dialog opens with the following required fields:
   1. Project – The Jira project where the test case will live after creation.
   2. Issue Type – Choose Test (this issue type is added by Zephyr Squad).
   3. Summary – The name or title of the test case.
   4. Reporter – The Jira user who is creating the test case.

3. Once the required fields are filled in, scroll to the bottom of the form and add test steps. Each step captures three pieces of information:
   1. Test Step – Description of the action that needs to be performed for this step.
   2. Test Data – Any data required for the step.
   3. Expected Result – The result that should appear after the action is performed.

Modify and View a Test

Steps:

1. To view a test case and modify any of its fields, click Tests in the top menu navigation and select Search Tests.

2. The search screen opens with Zephyr Query Language (ZQL) controls for filtering test cases. Click the Summary of the test case you want to inspect. In this example we open the Guru99 Example Test Case.
   1. ZQL offers extra filters such as test status, cycle, label, and assignee to narrow the results.

3. This opens the individual test case view. Click any field to edit it inline. Press Enter on the keyboard and Zephyr autosaves the change. You can also edit individual test steps and rearrange them by drag and drop.

Create a Test Cycle

Steps:

1. To create a test cycle, click the Cycle Summary tab on the Test Summary page.

2. Existing cycles appear on the left-hand side of the interface in an organized folder structure. Add a new test cycle by clicking the + button at the top of the folder structure menu.

3. The Create New Cycle dialog opens. Complete the fields and click Save. The fields are:
   1. Version – The list of versions defined for the Jira project.
   2. Name – Name of the test cycle (required).
   3. Description – A short description of the cycle.
   4. Build – Informational field for build identifier (optional).
   5. Environment – Informational field for the test environment (optional).
   6. From – The start date of the test cycle.
   7. To – The end date of the test cycle. The end date is not enforced, so users can keep adding and executing tests beyond it.

4. After saving, the new cycle appears in the folder tree on the left side of the interface.

Add Tests to Test Cycles

Steps:

1. To add test cases to a test cycle, open the Cycle Summary tab and click the cycle you want to populate. Then click Add Tests on the right-hand side of the interface, above the test execution table.

2. The Add Tests dialog appears. Use the drop-down list to search for the test cases that should join the cycle, or type a test ID directly. After picking the tests, assign them to a Jira user. That user is the initial owner who will execute the added tests in the cycle.

• The assignee can be changed later when an individual test is executed.

Click Add once you have finished selecting and assigning all your test cases.

3. Zephyr adds and assigns every selected test case to the chosen Jira user. A progress dialog appears. When it finishes, click Close at the bottom right.

4. After the tests are added, click the cycle name to see all the added tests inside the execution table.

Assign Test Executions

Steps:

1. On the Cycle Summary page, click the E button next to the test case you want to assign.

2. The test execution view opens. Use the Assigned To drop-down list to pick a different user. Zephyr autosaves the change.

Execute the Tests

Steps:

1. Quick-execute a test case by changing its status in the Status column of the cycle execution table. For a more detailed run, click the E button next to the test.

2. From the execution view, mark the whole test case by selecting a value from the Execution Status drop-down list (typical values: PASS, FAIL, WIP, BLOCKED, UNEXECUTED). Zephyr records the run.

3. You can also execute each test step independently. Scroll to the Test Details section and change the Status drop-down for each step. Step-level results roll up to the test case status and feed Zephyr’s reporting gadgets.

View Testing Progress

Steps:

1. To view test progress across all activities, click Dashboards in the top menu navigation and open the dashboard you want to inspect.

2. The dashboard displays every gadget that has been added, including any Zephyr reporting gadgets. To add more Zephyr gadgets, click the Add Gadget button at the top right of the dashboard.

3. The Add a gadget dialog opens. Type Zephyr in the search bar to filter Zephyr’s testing gadgets (Test Execution Burndown, Top Failing Tests, Test Execution Results, Traceability, and others). Select a gadget and click Add gadget to place it on the dashboard so your team can track progress at a glance.

How AI Is Changing Test Management in Zephyr

SmartBear has rolled AI capabilities into the Zephyr family through its HaloAI initiative, and the impact on Zephyr Squad and Zephyr Scale is already visible. AI now reads the linked Jira story and generates draft test cases with steps, test data, and expected results, which dramatically cuts the time testers spend on authoring.

AI features also surface risk by analyzing past execution history. They highlight tests that fail most often, flag flaky steps, and suggest which areas of the product deserve extra coverage in the next cycle. Generative assistants can summarize a failed run into a defect description that is ready to link to Jira, and they translate ZQL queries from plain English. AI does not replace human review, but it shifts test management toward higher leverage, exploratory work.

FAQs