Migrating from Xray, step by step
This page assumes the decision is already made. It covers what actually has to come out of Xray, which parts survive the trip, which parts do not, and the question no other migration has to answer: what happens to the thousands of Jira issues Xray leaves behind.
The short version: test cases export easily because they are Jira issues, but steps and folders do not come with them. Requirement links survive a two-pass import. Execution history should stay where it is. Attachments are not supported in BesTest, which needs a conscious decision before you pick a date.
Still comparing the two tools rather than planning a move? Start with the Xray alternative comparison, or with what Xray actually costs if the renewal is what started this. Last reviewed 29 July 2026.
The half of an Xray migration nobody plans for
Xray represents tests and executions as Jira issue types. Test, Precondition, Test Set, Test Plan and Test Execution are all work item types added to your projects, which is why an Xray instance that has been running a few years usually has more Test Execution issues than any other kind of issue in Jira. Every run created one.
That has a real upside during a migration: the data is in Jira, so it is exportable with JQL and it survives on its own even after the app is gone. It also means migrating is only half the job. The other half is deciding what happens to all those issues, and it is a decision rather than a task. Nobody else can make it for you, and postponing it is how teams end up two years later with a backlog full of test artifacts from a tool they no longer run.
BesTest sits on the other side of that line: test data lives in a dedicated, secure database rather than as Jira issues, so no future migration off it leaves an issue cleanup behind. That is the architectural difference between the two tools, and during a migration it is the one you feel.
Leave the issues where they are
No effort, ongoing costNothing breaks on day one. But the Test and Test Execution issues stay in your backlog and keep turning up in JQL, boards, dashboards and reports, which is the exact problem many teams were leaving to solve. The trap is the app-provided fields: anything Xray contributes stops being usable once the app is uninstalled, so export what you still need out of those fields while the app is still installed.
Bulk-move them to an archive project
A day, reversibleCreate a dedicated archive project, bulk-move the Xray issue types into it, and take it out of your boards, filters and dashboards. History and issue links survive, the working backlog gets clean, and nothing is destroyed. The cost to know about: moving an issue between projects changes its key, so any external references to the old keys, in wikis, tickets or documents, stop resolving.
Delete them
IrreversibleThe cleanest end state and the only one you cannot undo. It is defensible if you have verified exports and no retention obligation, and reckless otherwise. Deleting also silently breaks anything pointing at those issues: links from stories, saved filters, dashboard gadgets and automation rules. If you go this route, do it long after cutover, not during it, and delete Test Executions before Tests.
Whichever you choose, do it after cutover, never during it, and audit your saved filters, boards, dashboards and automation rules first. Anything written against the Xray issue types will quietly stop matching the day those issues move or disappear.
What actually has to move
Six things travel, and only one of them travels without a caveat. The two-pass rows are where most Xray exports go wrong, because the export looks complete until you open it.
| What moves | Reality | What that means in practice |
|---|---|---|
| Test cases | Clean | Because an Xray test is a Jira issue, the Jira issue navigator will export the standard fields to CSV for any JQL you can write. That covers summary, description, labels, priority, components and your Jira custom fields without any extra tooling. |
| Manual test steps | Two passes | Steps are not a normal Jira field, so a default navigator export gives you empty test cases. You need the Manual Test Steps field added to the export, Xray exporting or reporting, or the Xray REST API. Check a single exported row for step data before you export ten thousand. |
| Test Repository folders | Two passes | The classic Xray export trap. The Test Repository folder path is not a native Jira field, so a plain issue navigator CSV does not carry your folder tree at all. Pull the folder path from Xray itself, then feed it into the Folder Path column of the BesTest import template and the tree rebuilds itself. |
| Requirement-to-test links | Two passes | In Xray, coverage is a Jira issue link between a Test issue and the story it validates, so the relationship exports as a pair of issue keys. Getting it into BesTest as real coverage takes a two-pass import, described below. This is the part a flat CSV import always loses. |
| Execution history | Hard | Every run in Xray produced a Test Execution issue, so the history is both voluminous and entangled with your Jira project. Our honest recommendation is not to migrate it. Keep it in Jira as a read-only archive, which is a genuine advantage of the issue-based model. |
| Attachments | Not supported | BesTest does not support file or screenshot attachments yet. On the Xray side the good news is that your evidence is already Jira issue attachments, so it survives on its own if you keep the issues. Read the section below before you plan a deletion. |
Getting the data out of Xray
Export in separate files, and check a sample before running anything at full size. The single most common wasted day in an Xray migration is exporting the whole library and only then noticing the steps or the folders are missing.
Take a full inventory first, with JQL
Before exporting anything, run a count per Xray issue type in the issue navigator: Test, Precondition, Test Set, Test Plan and Test Execution. Instances that have been running for a few years almost always have more Test Execution issues than everything else combined, because every run created one. Those five numbers determine whether the cleanup below is an afternoon or a project.
Export the tests through the issue navigator, with the step field added
The navigator CSV export handles standard Jira fields well, and every Xray test is a Jira issue, so this is the cheapest path. The catch is that manual test steps are not a normal field: add the Manual Test Steps field to your export, or use Xray exporting or the REST API instead. Verify on one row before you commit to a full run, because an export of ten thousand stepless test cases is a day lost.
Get the Test Repository folder path out separately
The Test Repository folder path is not a native Jira field, so it is not available in the navigator export. Pull it from Xray directly, whether through its own export, its reporting, or the REST API, and produce a simple two-column list of test key and folder path. Without this file, your entire library lands in one flat folder and someone spends a fortnight reorganising it by hand.
Export the coverage links as their own file
Requirement coverage in Xray is a Jira issue link between a Test issue and the story it validates. Export those links as a two-column list of test key and story key. This is the most valuable file in the migration, because it is what lets you rebuild traceability instead of re-creating it by hand.
The two-pass import that keeps your traceability
BesTest imports test cases and requirements from Excel or CSV through a four-step wizard: upload, map columns, validate, finish. The test case template has a Linked Requirements column and the requirement template has a Linked Test Cases column, and both take BesTest keys, which do not exist until the other side has been imported. That is why traceability takes two passes rather than one clever file.
Decide what becomes a requirement
Xray has no requirements module of its own, so it borrows your Jira stories and calls the link to them coverage. BesTest has first-class requirements, which means you get a choice: keep tracking coverage against Jira work items using the links, or promote the stories that represent lasting behaviour into BesTest requirements. Most teams do both, promoting the durable ones and leaving sprint-shaped stories where they are.
Import the requirements first, with no links
Fill the requirement template (Requirement Name, Folder Path, Description, Reference, Requirement Type, Complexity, Impact) and leave the Linked Test Cases column empty. Put the original Jira story key in the Reference column so you can join back to your export in the next pass, and so anyone reading the requirement later can find where it came from.
Download the result file, which is what makes pass two possible
The import summary offers a result CSV mapping every imported row to its new REQ key. Join it against your coverage-links file on the Jira story key, and you now have a lookup from each Xray test key to the BesTest requirement key it should link to.
Import the test cases with the links already in them
Populate the test case template, using the Folder Path column for the Test Repository path you exported, and the Linked Requirements column for the REQ keys from the lookup. Coverage is created as part of the import rather than as a re-linking exercise afterwards. The importer validates first, files cap at 10,000 rows or 10MB and load in batches of 100, and a skip-existing option lets you re-run a failed file without duplicating what already landed.
After each batch, compare counts per folder against your export file rather than against the importer summary. An importer can only report on the rows it decided to process, which is a distinction migrations tend to learn the expensive way.
The two fields no Xray export will give you
BesTest calculates a requirement’s Significance from Dev Complexity multiplied by Impact, and measures coverage against that. “Covered” does not mean “has at least one linked test case”, it means the requirement has enough coverage for how significant it is. That is the useful part of the model, and also the part no export can fill in, because Xray has no requirements module and therefore no such columns.
Do not stall the migration on it. Set both to a middle value on import, or bulk-set them per folder if your Test Repository tree already encodes risk, then refine during the first month of real use. Coverage will read approximately for a few weeks and then become the report you actually check before a release.
Execution history: leave it in Jira
Execution history is the hardest thing to carry across from any test management tool. A single execution is not one row: it is a result per test and per step, tied to a cycle, an environment, a build, a tester and a timestamp, in a structure that only fully makes sense inside the tool that recorded it. Reshaping that into a different model produces something that looks like history without being the same evidence, and an auditor will notice.
Coming off Xray you get the easiest possible answer to this. Your Test Execution issues are Jira issues, so the archive already exists and stays readable without keeping any app installed or paying anyone. Migrate the test cases, start fresh cycles in BesTest, and leave the history in Jira exactly where it is. Just export what you still need out of Xray-provided fields before the app comes off, because app-contributed field data stops being usable once the app is uninstalled.
The one exception worth making: if you need the last release cycle for continuity rather than for audit, re-running it in BesTest is usually faster than importing it, and it doubles as your pilot.
Attachments: BesTest does not support them yet
BesTest has no file or screenshot attachments on test cases or executions today, and no import path for them, because there is nowhere for them to land. This is a real gap and it is better to hear it now than in week three of your migration.
On an Xray migration it hurts less than it would elsewhere. Evidence attached to Test and Test Execution issues is ordinary Jira issue attachments, so it stays in Jira under your existing permissions and retention rules whether or not Xray is installed. It also means a decision to delete those issues is a decision to delete that evidence, which is worth saying out loud before anyone runs a bulk delete.
Going forward, the workaround is the same pattern: create or link a Jira work item from the test case or execution and attach screenshots, logs and files there. BesTest links bidirectionally with Jira work items, so evidence stays one click from the test.
Let an agent do the reshaping
The slow part of an Xray migration is rarely the import. It is the reshaping: three exports in three different shapes, joined on keys, folded into an import template, then done again when the first attempt reveals a field you forgot.
BesTest exposes an MCP server, so an AI agent can read your exports in whatever shape they arrived - a navigator CSV, a folder-path list, a spreadsheet of issue links - and rebuild the structure directly: folders, requirements, test cases with their steps, and the links between them in the same pass. The links are exactly what a flat CSV import loses, so that is the part worth handing to an agent. It works in batches you can watch and stop, and it runs under your own Jira permissions.
Being accurate about the status: the MCP server is in closed beta, available on request, with general availability to follow. It is a general-purpose interface to BesTest that happens to be very good at this job, not a finished migration product with a progress bar. If you want it for a move, ask us and we will enable it for your instance.
A phased plan that actually finishes
There is no one-click import from Xray to BesTest, and anyone offering you one is describing the easy 20% of the job. What works is one pilot project taken all the way through, then repetition, then the backlog cleanup as a separate decision at the end.
Pilot one project
- Pick an active project with a real release in the window, not the quiet one
- Export tests, folder paths and coverage links as three separate files
- Import requirements, then test cases with the links, and run one full cycle in BesTest
- Write down every field you had to drop, because that list is your mapping spec
Expand and run in parallel
- Repeat per project, reusing the column mapping settled during the pilot
- Set Dev Complexity and Impact as you go rather than in a later sweep
- Keep Xray authoritative for a project until that project has run a cycle in BesTest
- Audit saved filters, boards and automation rules that reference Xray issue types
Cut over, then clean up the backlog
- Switch new work to BesTest on a date people know about in advance
- Export anything you still need out of Xray-provided fields while the app is installed
- Only then archive or delete the leftover Test and Test Execution issues
- Treat the backlog cleanup as a separate project with its own decision and sign-off
Six weeks is a realistic shape for a mid-sized instance, plus a cleanup phase whose length depends entirely on which of the three options you choose. The pilot decides the outcome: once one real cycle has run end to end in BesTest, everything after it is repetition.
What people say goes wrong, and what we can promise
The recurring themes in public Xray reviews are rendering errors, support that is slow to respond, and delays getting data residency in a chosen region. We will not pretend to fix the first two for you by assertion. On the third we can be concrete: BesTest supports hosting your data in the EU, US or India, and other regions can be spun up on request.
Xray is a mature product with the largest install base in the category and genuinely deep automation tooling. If your testing lives in CI pipelines, it earns its price. The teams who leave tend to be the ones doing mostly manual testing and UAT, paying for surface area they never touch, and tired of a backlog full of test artifacts. If that is not you, the honest advice is to stay.
Common questions about leaving Xray
How do I export test cases from Xray?
Because Xray stores tests as Jira issues, the Jira issue navigator will export the standard fields to CSV for any JQL you can write, which covers most of a test case. Two things are not in that export by default. Manual test steps are not a normal Jira field, so you have to add the Manual Test Steps field to the export or use Xray exporting or the REST API. The Test Repository folder path is not a native Jira field either, so your folder tree has to come out of Xray separately. Check one exported row for both before running a full export.
What happens to all the Jira issues Xray created?
That is the question unique to an Xray migration, and it needs an explicit decision. You have three options. Leave them in place, which costs nothing but keeps the backlog cluttered and means Xray-provided field data becomes unusable once the app is uninstalled. Bulk-move them to a dedicated archive project, which keeps history and links, cleans up the working backlog and is reversible, at the cost of changing every issue key. Or delete them, which is the cleanest and the only irreversible option, and is only defensible with verified exports and no retention obligation. Whichever you pick, do it after cutover rather than during it.
Will my requirement-to-test links survive?
Yes, if you import in two passes. In Xray, coverage is a Jira issue link between a Test issue and the story it validates, so export those pairs as their own file. Import requirements into BesTest first with the Linked Test Cases column empty, putting the original Jira story key in the Reference column. Download the result file that maps each row to its new requirement key, join it against your links file, then import the test cases with those keys filled into the Linked Requirements column. Coverage is created as part of the import. A single flat CSV import cannot do this, which is why so many migrations end with traceability starting from zero.
Can I migrate Xray execution history?
You can export it, but in most cases you should not import it. In Xray every run produced a Test Execution issue with results per test and per step, tied to an environment, a build, a tester and a timestamp. Reshaping that into another tool gives you something that looks like history without being the same evidence. Xray users have an advantage here: because the executions are Jira issues, you can simply keep them in Jira as a read-only archive rather than paying to keep another app installed. Migrate the test cases, start fresh cycles in BesTest, and leave the history where it already is.
Does BesTest support attachments the way Xray does?
No. BesTest does not support file or screenshot attachments on test cases or executions yet, and there is no import path for them. On an Xray migration this hurts less than it might, because evidence attached to Test and Test Execution issues is ordinary Jira issue attachments and stays in Jira whether or not Xray is installed. Going forward, the workaround is to attach evidence to a linked Jira work item: BesTest links bidirectionally with work items, so it stays one click from the test and keeps your existing Jira permissions and retention rules.
How long does an Xray migration take?
Plan roughly six weeks for the migration itself on a mid-sized instance, in three phases: one or two weeks piloting a single project end to end, three to four weeks repeating it across the rest, then a cutover date. Then plan the Jira issue cleanup as a separate piece of work afterwards, because it involves a decision your team has to make rather than a task someone can just execute. Migrations that try to do the cleanup at the same time as the cutover are the ones that stall.
Ready to Get Complete
Testing Visibility?
Start using BesTest today and experience complete testing visibility from requirements to release. Free to get started!
Available on the Atlassian Marketplace. Install in seconds, free for up to 10 users.
Start Free on Marketplace