Zephyr Scale migration: move your tests to QAM HubNew
Import Zephyr Scale Cloud projects with folders, cases, steps, cycles, results and attachments, plus Jira issues, versions and people with Jira credentials.
Zephyr Scale keeps its test cases next to Jira, so a Zephyr Scale migration has two halves: the folders, cases, steps, cycles and results that live in Zephyr, and the people, issues and versions that only Jira can name. The QAM Hub import wizard handles both. It reads Zephyr Scale Cloud through its API, optionally reads Jira Cloud next to it, and turns each Zephyr project into one QAM Hub project after a field mapping you review before anything is written.
How the Zephyr Scale migration works
- Open "Import from other TMS" on Org Home and choose Zephyr Scale. Organization Admins only.
- Connect with a Zephyr Scale Cloud API token. The region of your instance (US, EU, AU or DE) is detected from the token, so there is no host to look up.
- Optionally add Jira Cloud credentials: the email and API token of a Jira user who can see the projects.
- Pick the projects and review the preview of what each contains and what is left behind for your selection.
- Review the field mapping and change any row that is not what you want.
- Decide on the team, start the import, follow the live progress and read the report.
The wizard supports Zephyr Scale Cloud only, through the API v2 of Zephyr Scale Cloud. Zephyr Scale Server and Data Center are not supported.
Do you need Jira credentials?
Zephyr refers to people and issues by id only. Without Jira credentials the import still brings test cases, folders, steps, cycles and results, which is the bulk of the data. What it cannot do is turn those ids into names, so attribution, the Team step, traced Jira issues, defects and Jira versions stay behind. The preview states exactly what is left out for your selection, so the decision is made before the import rather than discovered after it.
| With Jira Cloud credentials | Without |
|---|---|
| Executions carry the tester's name; the Team step matches Zephyr users to members and offers invites | Executions are imported without attribution; no Team step |
| Traced Jira issues become requirements linked to the case | Not imported |
| Execution defects become linked Jira issues | Not imported |
| Jira versions become milestones | Not imported |
| Cases, folders, steps, cycles, results and attachments | Imported the same way |
What comes across from Zephyr Scale
| In Zephyr Scale | In QAM Hub |
|---|---|
| Test case folders | Each top-level folder becomes a suite with nested folders as groups, or one suite per project with the whole folder tree as groups. You choose. |
| Test cases | Name, objective, precondition and steps, with the original created and updated dates. |
| Steps | Test data and expected result per step, HTML converted to Markdown, one copy of each expected result under its step number. Call-to-test steps are expanded inline. |
| BDD scripts | Kept verbatim. |
| Priority | The built-in Priority field. |
| Status, component, owner, estimated time, web links | Custom fields, each with its own row in the mapping. Component and owner names are read from Jira, so they need Jira credentials. |
| Labels | Tags. |
| Custom fields | Custom fields, up to 20 per project; the surplus is reported in the preview. |
| Zephyr key | Kept in a "Zephyr key" text field on the case. |
| Test cycles | Test runs: the newest 50, 200 or every cycle per project, one run per environment where a cycle covers several. |
| Executions | Each execution with its result history, date, comment and, with Jira credentials, its tester. |
| Custom result statuses | Up to three custom execution statuses; the rest import as Untested. |
| Attachments on cases and results | Attachments, deduplicated into the project library. |
| Traced Jira issues, defects, Jira versions | Requirements linked to the case, linked Jira issues, milestones. Jira credentials needed. |
| Zephyr users | Matched to workspace members by email; the rest can be invited. Jira credentials needed. |
How steps and scripts are converted
Zephyr stores step text as HTML. The import converts it to Markdown, so lists and emphasis survive as text a tester can edit rather than as markup. Each step keeps its test data and one copy of its expected result under the step number, so a case does not end up with every expectation repeated at the bottom. Call-to-test steps are expanded inline, which means a case reads complete on its own and does not depend on another case staying unchanged. BDD scripts are kept verbatim, Gherkin keywords and all.
A Zephyr test case written in prose keeps its objective and precondition, with the precondition in the built-in Pre-conditions field, and the Zephyr key stays on the case in a "Zephyr key" text field so a reference in an old ticket can still be found.
Test cycles become test runs
Each test cycle becomes a test run, and a cycle that was executed in several environments becomes one run per environment, so results from staging and production do not get averaged into one number. You choose the depth per project: the newest 50 cycles, the newest 200, or every cycle. Every execution keeps its result history, date and comment, and the tester when Jira credentials were given.
| Zephyr status | QAM Hub status |
|---|---|
| Pass | Passed |
| Fail | Failed |
| Blocked | Blocked |
| Not Executed | Untested |
| In Progress | A custom execution status (one of up to three), or Untested when the project has no free custom status |
| A project's custom statuses | Up to three become custom execution statuses; the rest import as Untested. |
You review the field mapping first
Nothing is written until you have seen the field mapping. Every row can be changed: create a custom field with your own name and type, map into an existing field, append the content to Steps or Expected Result, or skip it. A field that no case fills is not created, so an unused Zephyr field never becomes an empty column in every case. Custom fields are capped at 20 per project and the preview reports any surplus, so you decide which ones matter before the import rather than after.
What you get on the Jira side afterwards
With Jira credentials, the issues traced to a test case become requirements with a link to the issue, so the requirements coverage you had in Zephyr is a coverage view on day one, and execution defects stay attached to the executions that found them. Once the import is done, connect the project to Jira through the Jira integration so new bugs are filed from failed executions the same way.
Good to know
- Partial failures are per item and reported in the summary; a project that fails entirely is removed, so nothing half-imported remains.
- No link back to Zephyr ids is stored, so a second import of the same project creates a second copy. The preview warns about it.
- One import of any tool (TestRail, Qase, Zephyr Scale or Xray) runs per organization at a time.
- Case numbers in QAM Hub are never reused, so links to a case keep resolving.
- Coming from TestRail or Qase instead? Those wizards follow the same steps. For anything else, CSV import covers cases, checklists and requirements.
Plans
The Zephyr Scale import is included on every plan and in the free trial.
Frequently asked questions
Does the import work with Zephyr Scale Server or Data Center?
No. The wizard reads Zephyr Scale Cloud through its API v2 and detects the region (US, EU, AU or DE) from the token. Server and Data Center instances are not supported.
Do I have to give the wizard my Jira credentials?
No, they are optional. Without them the import brings folders, cases, steps, cycles, results and attachments; with them it also names testers, matches your team, turns traced Jira issues into requirements, execution defects into linked issues and Jira versions into milestones. The preview tells you what your selection leaves behind.
What happens to a cycle that was executed in several environments?
It becomes one test run per environment. Each execution keeps its result history, date and comment, so results from different environments stay separate instead of being merged into one run.
Can I import the same Zephyr project twice?
You can, but you get a second copy. No link back to Zephyr ids is stored, so the import cannot update a project it already moved; the preview warns before you confirm.