QAM Hub QAM Hub
Home / Features / Import & migration / Migration from Xray

Xray migration: move Xray tests into QAM HubNew

Import Xray Cloud projects: the Test Repository tree, manual, Cucumber and Generic tests, preconditions, covered issues, Test Executions and attachments.

Xray tests are Jira issues, so an Xray migration has to read two systems: Xray for the Test Repository, steps, preconditions, Test Executions and results, and Jira for the summary, labels, priority, description and people of every test. The QAM Hub import wizard reads both, keeps the Jira key on every case and turns one Jira project into one QAM Hub project after a field mapping you review before anything is written.

How the Xray migration works

  1. Open "Import from other TMS" on Org Home and choose Xray. Organization Admins only.
  2. Connect with an Xray API key: the client id and client secret. The regional Xray host is handled automatically.
  3. Add Jira Cloud credentials: the email and API token of a Jira user who can see the projects. They are required.
  4. Pick the projects and review the preview of what each contains.
  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 Xray Cloud only, through the Xray GraphQL API. Xray Server and Data Center are not supported.

Why Jira credentials are required

Xray stores the test itself: the steps, the type, the folder, the executions. The summary, labels, priority, description, custom fields and the people on a test are Jira issue fields, and the Xray API refers to them by id. Without Jira the import would produce cases with no title and executions with no tester, so the wizard asks for Jira Cloud credentials up front and uses them for the names, the covered issues, the defects and the Team step.

What comes across from Xray

In Xray and JiraIn QAM Hub
Test Repository foldersTop-level folders become suites with nested folders as groups, or one suite with the whole tree as groups. You choose. Tests outside any folder land in an "Unorganized" group.
Jira summaryThe case title.
Jira descriptionA Description custom field by default, converted from Jira wiki markup to Markdown; the mapping can send it to Pre-conditions, append it to Steps or skip it.
Manual test stepsSteps with action, data and expected result, one copy of each expectation under the step number.
Called testsExpanded inline into the calling test.
Cucumber testsThe Gherkin scenario, kept verbatim.
Generic testsThe test definition, kept as is.
PreconditionsEvery linked precondition issue, concatenated into the built-in Pre-conditions field.
Jira labelsTags.
Jira priorityThe built-in Priority field.
Jira custom fieldsCustom fields, up to 20 per project; the surplus is reported in the preview.
Jira key, dates, reporterThe Jira key is kept on the case in a "Jira key" text field; the original dates are kept, and the reporter when that person is in the workspace.
Covered issuesRequirements with source "jira", linked to the case.
Test ExecutionsTest runs: the newest 50, 200 or all per project.
Xray test runs inside an executionOne execution per test with one history entry, its tester, date and comment.
Execution defectsLinked Jira issues on the execution.
Attachments on tests, steps and resultsAttachments, deduplicated into the project library.
Jira usersMatched to workspace members by email; the rest can be invited.

How each Xray test type is converted

Xray test typeWhat the case contains
ManualNumbered steps, each with its action, its data and its expected result. The expectation appears once, under the step number, so a long case is not repeated at the bottom.
Manual with called testsThe called test's steps are expanded inline where the call sits, so the case is complete on its own.
CucumberThe Gherkin is kept verbatim, so Given, When and Then read exactly as the feature file did.
GenericThe definition is kept, so an automated test keeps the reference to what runs it.

Preconditions and covered issues

In Xray a precondition is its own issue, linked to one or more tests. The import does not create a case per precondition; every precondition linked to a test is concatenated into that test's built-in Pre-conditions field, so a tester reads the setup where it matters and the preconditions list does not become a suite of its own.

The issues a test covers in Xray become requirements in QAM Hub with source "jira", each linked to the case. That is the requirements coverage view from day one: covered and uncovered counts per requirement, filterable by source and milestone, with the latest result of every covering case.

Test Executions become test runs

Each Test Execution becomes a test run, and you choose how far back to go per project: the newest 50, the newest 200, or all of them. Inside an execution, each Xray test run becomes one execution of the case with one history entry carrying its tester, date and comment, and the defects raised on it become linked Jira issues on that execution.

Xray statusQAM Hub status
PASSEDPassed
FAILEDFailed
TODOUntested
EXECUTINGA custom execution status (one of up to three), or Untested when the project has no free custom status
ABORTEDA custom execution status (one of up to three), or Untested when the project has no free custom status
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 no case fills is not created, so a Jira custom field that exists in the project but was never filled on a test does not become an empty column. Custom fields are capped at 20 per project and the preview reports the surplus.

Your team comes with the projects

The Team step matches the Jira users found on tests and executions to workspace members by email and offers invites for the rest. Invited people are granted access to the imported projects, so the tester named on last month's execution can open it under their own name.

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.
  • A second import of the same project creates a second copy. Move each project once.
  • 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.
  • After the import, connect the project to Jira through the Jira integration: new bugs are then filed from failed executions and the covered issues can be refreshed from Jira on demand.
  • Coming from Zephyr Scale or TestRail instead? Those wizards follow the same steps. For anything else, CSV import covers cases, checklists and requirements.

Plans

The Xray import is included on every plan and in the free trial.

Frequently asked questions

Does the import work with Xray Server or Data Center?

No. The wizard reads Xray Cloud through the Xray GraphQL API with a client id and client secret, and the regional Xray host is handled automatically. Server and Data Center instances are not supported.

Why does the wizard ask for Jira credentials when I already gave it an Xray API key?

Because the summary, labels, priority, description, custom fields and people of an Xray test live in Jira, and Xray refers to them by id. The Jira Cloud email and API token are used to resolve those ids, to find the covered issues and defects, and to match your team.

What happens to Cucumber and Generic tests?

Cucumber tests keep their Gherkin verbatim, and Generic tests keep their definition. Manual tests keep their steps with action, data and expected result, and called tests are expanded inline so each case is complete on its own.

Are preconditions imported as separate test cases?

No. Every precondition linked to a test is concatenated into that test's built-in Pre-conditions field, so the setup is read where it is needed and no extra suite is created.

Read more

Try Migration from Xray on your own project