> ## Documentation Index
> Fetch the complete documentation index at: https://www.bugzy.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Zephyr Scale

> Manage test cases in Zephyr Scale — Bugzy creates, updates, and organizes test cases directly in your Jira Cloud test management system.

Zephyr Scale is a test case management tool for Jira Cloud. When configured, Bugzy creates and manages test cases directly in Zephyr Scale instead of the default filesystem — so your QA artifacts live alongside your Jira project.

## What Bugzy can do with Zephyr Scale

* **Create test cases** with objectives, preconditions, steps, and labels
* **Update existing test cases** when tests evolve or requirements change
* **Organize test cases** into folders within your Zephyr project
* **List and search** test cases and folders

## Prerequisites

* **Jira Cloud** with **Zephyr Scale - Test Management for Jira** installed
  <Warning>
    This must be "Zephyr Scale", not "Zephyr Essential" — they are different products with different APIs.
  </Warning>
* Admin access to your Jira Cloud instance (for generating the API token)

## Setup

<Steps>
  <Step title="Generate a Zephyr Scale API token">
    In Jira Cloud, go to **Settings** (gear icon) > **General Settings** > **Apps** > **Zephyr API Access Tokens** and click **Create access token**. Copy the token immediately — it is shown only once.

    <Info>
      This is **not** your standard Atlassian API token (under Profile > Manage Account > Security). Zephyr Scale requires its own dedicated token.
    </Info>
  </Step>

  <Step title="Configure in Bugzy">
    Open your project in the Bugzy dashboard, go to **Settings > Integrations > Zephyr Scale**, paste your API token, enter your Jira project key (e.g., `PROJ`), and click **Save Configuration**.
  </Step>

  <Step title="Done">
    The next time Bugzy runs a test generation or management task, it will use Zephyr Scale to store and organize test cases.
  </Step>
</Steps>

## How it works

Once configured, Bugzy's test-case-manager subagent switches from filesystem-based test cases (`test-cases/*.md`) to the Zephyr Scale API. The agent:

1. Lists existing folders in your Zephyr project
2. Creates or reuses folders to organize test cases by test area
3. Creates test cases with full metadata — name, objective, preconditions, steps, labels, and priority
4. Updates test cases when requirements change

Your Playwright test scripts still live in the Git repository. Zephyr Scale stores the **test case definitions** (what to test), while the test code (how to test) remains in `tests/specs/`.

## Troubleshooting

| Issue                                     | Solution                                                                          |
| ----------------------------------------- | --------------------------------------------------------------------------------- |
| Agent falls back to filesystem test cases | Zephyr Scale is not configured — go to **Settings > Integrations > Zephyr Scale** |
| `Zephyr API error 401`                    | Token is invalid or expired — generate a new one in Jira                          |
| Blank page at Zephyr API Access Tokens    | Ensure you installed "Zephyr Scale" (not "Zephyr Essential")                      |