QAM Hub QAM Hub
Home / Features / Import & migration / Migration from Zephyr Scale

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

  1. Open "Import from other TMS" on Org Home and choose Zephyr Scale. Organization Admins only.
  2. 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.
  3. Optionally add Jira Cloud credentials: the email and API token of a Jira user who can see the projects.
  4. Pick the projects and review the preview of what each contains and what is left behind for your selection.
  5. Review the field mapping and change any row that is not what you want.
  6. 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 credentialsWithout
Executions carry the tester's name; the Team step matches Zephyr users to members and offers invitesExecutions are imported without attribution; no Team step
Traced Jira issues become requirements linked to the caseNot imported
Execution defects become linked Jira issuesNot imported
Jira versions become milestonesNot imported
Cases, folders, steps, cycles, results and attachmentsImported the same way

What comes across from Zephyr Scale

In Zephyr ScaleIn QAM Hub
Test case foldersEach 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 casesName, objective, precondition and steps, with the original created and updated dates.
StepsTest 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 scriptsKept verbatim.
PriorityThe built-in Priority field.
Status, component, owner, estimated time, web linksCustom fields, each with its own row in the mapping. Component and owner names are read from Jira, so they need Jira credentials.
LabelsTags.
Custom fieldsCustom fields, up to 20 per project; the surplus is reported in the preview.
Zephyr keyKept in a "Zephyr key" text field on the case.
Test cyclesTest runs: the newest 50, 200 or every cycle per project, one run per environment where a cycle covers several.
ExecutionsEach execution with its result history, date, comment and, with Jira credentials, its tester.
Custom result statusesUp to three custom execution statuses; the rest import as Untested.
Attachments on cases and resultsAttachments, deduplicated into the project library.
Traced Jira issues, defects, Jira versionsRequirements linked to the case, linked Jira issues, milestones. Jira credentials needed.
Zephyr usersMatched 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 statusQAM Hub status
PassPassed
FailFailed
BlockedBlocked
Not ExecutedUntested
In ProgressA custom execution status (one of up to three), or Untested when the project has no free custom status
A project's custom statusesUp 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.

Read more

Try Migration from Zephyr Scale on your own project