Skip to main content
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
    This must be “Zephyr Scale”, not “Zephyr Essential” — they are different products with different APIs.
  • Admin access to your Jira Cloud instance (for generating the API token)

​
Setup

1

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.
This is not your standard Atlassian API token (under Profile > Manage Account > Security). Zephyr Scale requires its own dedicated token.
2

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.
3

Done

The next time Bugzy runs a test generation or management task, it will use Zephyr Scale to store and organize test cases.

​
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

IssueSolution
Agent falls back to filesystem test casesZephyr Scale is not configured — go to Settings > Integrations > Zephyr Scale
Zephyr API error 401Token is invalid or expired — generate a new one in Jira
Blank page at Zephyr API Access TokensEnsure you installed “Zephyr Scale” (not “Zephyr Essential”)