Zephyr Scale for Jira: Test Management Best Practices

Zephyr Scale (formerly TM4J) is a test management app for Jira that keeps test cases, test cycles, and defects in the same platform as your backlog and sprints. For teams already invested in Jira, this integration eliminates the friction of switching between tools and enables traceability from requirement to test to defect.

Why Zephyr Scale vs. Standalone Tools

Standalone test management tools (TestRail, qTest) require synchronizing issue IDs between two systems. Zephyr Scale lives inside Jira — test cases are Jira issues, defects are Jira issues, and requirements are Jira issues. Traceability is automatic.

For agile teams that plan work in Jira sprints, Zephyr Scale means:

• Test cases live alongside the user stories they verify
• Sprint boards show test execution status for stories under test
• Test coverage is visible without importing/exporting between tools

The tradeoff: Jira's performance under heavy test loads and Zephyr Scale's reporting depth don't match dedicated tools like TestRail for teams with thousands of test cases.

Core Concepts

Test Cases: Issues with type "Test" containing steps, preconditions, and metadata. Created in the Jira project alongside regular issues.

Test Cycles: A container for a test execution effort — equivalent to a "test run" in TestRail. A cycle selects test cases and assigns them to testers.

Test Plans: Group related test cycles for a release or sprint. A test plan for sprint 24 might contain cycles for regression, new features, and smoke testing.

Folders: Organize test cases hierarchically within a project. Structure mirrors your product: Authentication > Login > OAuth, Payments > Checkout > Credit Card.

Setting Up Zephyr Scale

Install Zephyr Scale from the Atlassian Marketplace. After installation, configure via Project Settings > Zephyr Scale:

1. Enable test management for the Jira project
2. Create test case folders matching your product structure
3. Configure custom fields for your workflow (Automation Status, Component, Priority)
4. Set up statuses: Draft, Ready for Review, Approved, Deprecated

Creating Test Cases

Navigate to the Tests section in your Jira project sidebar. Click Create Test Case:

Title: User can log in with valid credentials

Folder: Authentication > Login

Priority: High
Status: Approved
Estimated Time: 3m

Preconditions:
User account exists with email test@example.com and password TestPass123!

Test Steps:
1. Navigate to /login
   Expected: Login form displays with email and password fields

2. Enter test@example.com in the email field
   Expected: Field accepts input, no validation error

3. Enter TestPass123! in the password field
   Expected: Field accepts input, characters masked

4. Click "Sign In" button
   Expected: Redirect to dashboard, user name displayed in header

5. Check browser developer tools > Application > Cookies
   Expected: Session cookie set with HttpOnly flag

Tag test cases with labels for filtering: smoke, regression, critical-path, browser:chrome.

Linking Tests to Requirements

The core value of Zephyr Scale is traceability. Link test cases to the Jira stories they verify:

1. Open a test case
2. Click Link → Is Tested By (from story to test)
3. Or from the test case: Link → Tests (test to story)

On any Jira story, the Zephyr Scale panel shows:

• Which test cases cover this story
• Execution status across the current cycle
• Coverage percentage

Sprint planning becomes more precise when you can see which stories have zero test coverage before committing to a release.

Test Cycles: Planning Execution

Create a test cycle to plan a test execution effort:

1. Test Cycles → Create Test Cycle
2. Name: "Sprint 24 Regression"
3. Select test cases (from folders, by label, or individually)
4. Assign to testers
5. Set start and end dates

During execution, testers update each test case status:

• Pass — Test passed
• Fail — Test failed, link the Jira defect
• Blocked — Dependency issue, note the blocker
• In Progress — Being executed
• Not Executed — Not yet started

The cycle dashboard shows real-time execution progress: 45/120 executed, 40 passed, 5 failed, 75 remaining.

Test Plans for Releases

Group cycles under a test plan for release-level visibility:

v2.4 Release Test Plan
├── Sprint 24 Regression Cycle
├── Sprint 24 New Features Cycle
├── Browser Compatibility Cycle (Chrome, Firefox, Safari)
├── Mobile Regression Cycle
└── Smoke Test Cycle (pre-deploy verification)

The test plan dashboard shows aggregate status: how many tests are passing across all cycles, how many defects are open, and execution progress toward the release date.

CI/CD Integration via REST API

Zephyr Scale's REST API lets automated tests report results directly:

const axios = require('axios');

const ZEPHYR_URL = 'https://api.zephyrscale.smartbear.com/v2';
const API_TOKEN = process.env.ZEPHYR_TOKEN;

async function createTestCycle(projectKey, name) {
  const response = await axios.post(
    `${ZEPHYR_URL}/testcycles`,
    {
      projectKey,
      name,
      statusName: 'In Progress'
    },
    { headers: { Authorization: `Bearer ${API_TOKEN}` } }
  );
  return response.data.key;
}

async function reportResult(cycleKey, testCaseKey, statusName, comment) {
  await axios.post(
    `${ZEPHYR_URL}/testexecutions`,
    {
      projectKey: 'YOUR_PROJECT',
      testCycleKey: cycleKey,
      testCaseKey: testCaseKey,
      statusName, // 'Pass', 'Fail', 'Blocked'
      comment,
      executedById: 'automation'
    },
    { headers: { Authorization: `Bearer ${API_TOKEN}` } }
  );
}

// In your CI pipeline (e.g., after Jest runs)
const cycleKey = await createTestCycle('PROJ', `CI Run - ${process.env.CI_COMMIT_SHA}`);

for (const result of testResults) {
  await reportResult(
    cycleKey,
    result.testCaseKey,  // e.g., 'PROJ-T123'
    result.passed ? 'Pass' : 'Fail',
    result.error || ''
  );
}

For pytest, the pytest-zephyr-scale plugin handles this automatically — annotate tests with @pytest.mark.zephyr_testcase('PROJ-T123') and results are reported to the corresponding test case.

Cucumber/BDD Integration

Zephyr Scale supports Cucumber (BDD) natively. Feature files map to test cases, and Cucumber execution results import automatically:

# features/login.feature
@PROJ-T123
Feature: User Login

  @PROJ-T124
  Scenario: Valid credentials
    Given I am on the login page
    When I enter valid credentials
    Then I should be on the dashboard

Import results with the Zephyr Scale CLI:

zephyr-scale-cli upload \
  --server https://yourcompany.atlassian.net \
  --project PROJ \
  --token $ZEPHYR_TOKEN \
  --cucumber-results cucumber-report.json

Each Scenario with a @PROJ-Txxx tag maps to that test case in Zephyr Scale.

Coverage Metrics and Reporting

Zephyr Scale generates several report types:

Traceability Report: Shows which requirements have test coverage and which are untested. Critical for compliance and release sign-off.

Execution Report: Pass/fail rates per cycle, tester productivity, execution timeline.

Requirement Coverage Matrix: Cross-reference between stories/requirements and test cases. Identifies gaps.

Export reports as CSV or PDF. For stakeholders, the traceability report on a test plan shows release coverage at a glance.

Best Practices for Agile Teams

Keep test cases sprint-neutral: Write test cases for features, not sprints. Reuse them across cycles rather than copying.

Use the "Ready" status gate: Test cases in "Draft" can't be added to cycles. This prevents unreviewed cases from appearing in execution reports.

Link defects immediately: When a test fails, link the defect before moving to the next test. Unlinked failures lose traceability.

Tag automation status: Track which tests are automated vs. manual. Zephyr Scale can filter by this — run only manual tests in your manual cycle, automated tests in your CI cycle.

Archive deprecated cases: Don't delete old test cases — archive them. History is valuable for audits.

Zephyr Scale vs. Xray

Both are Jira-native test management apps. Key differences:

Teams with heavy BDD/Gherkin usage or advanced reporting needs often prefer Xray. Teams transitioning from standalone tools find Zephyr Scale easier to adopt.

Continuous Application Testing

Zephyr Scale tracks executed test cases. For continuous monitoring of your deployed application between test cycles, HelpMeTest runs automated functional tests against your live app on a schedule — complementing your Jira-based test management with always-on verification.

Summary

Zephyr Scale is the right choice for teams that:

• Already use Jira and want to avoid tool-switching overhead
• Need direct traceability from requirements to tests to defects
• Run agile sprints and want test coverage visible in sprint planning
• Have mixed manual + automated test suites

Structure: folders for organization → test cases with detailed steps → cycles for execution → plans for releases → traceability links to requirements. The Jira integration pays dividends at sprint review time, when you can show exactly which stories are tested and which defects are outstanding.