Migrating from Zephyr Scale, step by step
This page assumes the decision is already made. It covers what actually has to come out of Zephyr Scale, which parts survive the trip intact, which parts do not, and how long each phase realistically takes.
The short version: test cases, steps and folders move cleanly. Requirement-to-test links survive, but only if you import in two passes and in the right order. Execution history is the hard one, and most teams should not try to move it. Attachments are not supported in BesTest, which needs to be a conscious decision before you pick a date.
Still weighing the two tools rather than planning a move? Start with the Zephyr Scale alternative comparison instead. Last reviewed 29 July 2026.
Why the reason you are leaving shapes the plan
The complaint that comes up most often in Zephyr Scale reviews is not the product, it is the licence. Marketplace apps are licensed for the whole Jira instance, so a team with a handful of testers pays for everyone.
“For a team with only 4-5 QA engineers, the pricing was not cost-effective.”
That constraint is Atlassian’s rather than SmartBear’s, and it applies to every paid app in the category, BesTest included. It matters here for one practical reason: a cost-driven move has a renewal date attached, and a deadline is exactly what pushes teams into trying to migrate execution history they never needed. If your driver is the renewal, start the pilot at least two months before it.
One thing in your favour: your tests are not Jira issues
Zephyr Scale keeps test cases in its own store rather than as Jira issues, and so does BesTest. That similarity makes this migration simpler than it looks, because leaving does not strand thousands of orphaned Test issues in your backlog, and no Jira filter, board, dashboard or automation rule breaks on the day the app goes read-only. You are moving a library, not renovating a Jira project.
Teams coming off tools that store tests as Jira issues have a second, larger problem to solve first. If that is you as well, the Xray migration guide covers it.
What actually has to move
Six things travel, and two of them travel badly. Read the last two rows before you promise anyone a date.
| What moves | Reality | What that means in practice |
|---|---|---|
| Test cases and steps | Clean | Zephyr Scale exports the test case library to a spreadsheet from the Tests view. BesTest imports Excel or CSV and understands both traditional step tables and BDD/Gherkin, so a step-by-step case arrives as a step-by-step case rather than a wall of text in a description field. |
| Folder structure | Clean | Do not rebuild the tree by hand. The BesTest import template has a Folder Path column that takes a path such as Auth/Smoke and creates the folders as it imports. Keep your Zephyr folder path as a column in the export and the tree rebuilds itself. |
| Requirement-to-test links | Two passes | This is the part a flat CSV import loses, and the part that was the actual value of your old library. It does survive, but only if you import one side first, take the result file, and use the new keys on the second pass. Full recipe below. |
| Custom fields | Partial | Map what has an equivalent and make a decision about the rest. Two BesTest fields have no source in any Zephyr Scale export because the concept does not exist there: Dev Complexity and Impact, which together drive significance-weighted coverage. |
| Execution history | Hard | The hardest thing to carry across from any tool, and the place migrations quietly go wrong. Our honest recommendation is not to move it in full. Keep Zephyr Scale read-only for the audit trail instead. |
| Attachments | Not supported | BesTest does not support file or screenshot attachments yet. There is no import path for them because there is nowhere for them to land. Evidence goes on a linked Jira work item instead. Read the section below before you commit to a date. |
Getting the data out of Zephyr Scale
Export more than you think you need, in separate files, before you touch the importer. Re-exporting later is cheap; re-deriving a relationship you did not capture is not.
Export the test case library
In Zephyr Scale, open the Tests view, select the cases you want and export them to a spreadsheet. Take the whole library in one pass if the instance is small; export folder by folder if it is not, because you will want to review each batch separately anyway. Zephyr Scale also has a REST API, which is worth the scripting effort above a few thousand cases.
Export the coverage links as their own file
In Zephyr Scale a test case gets its requirement coverage from a link to a Jira issue rather than from a field on the case, so the relationship does not always ride along with the test case export. Pull it out as a plain two-column list: test case key, Jira issue key. This is the single most valuable file in the whole migration, because it is what you rebuild traceability from.
Snapshot the execution history and park it
Export your cycles and results to a file and store them with your other records. Treat this as evidence you are keeping, not as data you are importing. Deciding that on day one stops the migration turning into an execution-history project in week four.
Inventory the custom fields before you map anything
One row per field: name, type, who actually fills it in, and where it lands in BesTest or the decision to drop it. Most teams find a third of their fields have been empty for a year. Dropping those in the inventory is much cheaper than discovering them mid-import.
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 needs two passes rather than one clever file.
Import the requirements first, with no links
Fill the requirement template (Requirement Name, Folder Path, Description, Reference, Requirement Type, Complexity, Impact) and leave Linked Test Cases empty. Put your old Zephyr identifier or the Jira issue key in the Reference column so you can join back to your export later. Requirements first is the easier order because there are usually far fewer of them.
Download the result file
When the import finishes, the summary screen offers a result CSV that maps every imported row to its new REQ key. This file is what makes pass two possible. Keep it, and keep it next to the export you joined it against.
Build the test case file with the links already in it
Fill in the test case template and populate the Linked Requirements column with the new REQ keys, joined from the result file on the Reference column you set in pass one. Coverage is created as part of the import rather than as a re-linking exercise afterwards, which is the whole point of doing it in this order.
Validate, then check the numbers yourself
The importer validates the common breakages before anything is written: invalid values in fixed-value fields, an owner account ID that does not exist. If a run fails part way through, the skip-existing option lets you re-run the same file without duplicating what already landed. Files cap at 10,000 rows or 10MB and import in batches of 100, so a large library is several files; split them on folder boundaries so a failed batch is easy to reason about.
Do not trust a success screen. Count the rows.
Teams who moved in the other direction, from Zephyr Squad to Zephyr Scale, left public reviews describing a migration that “showed a final status of Successful” while test cases went missing, and complaining there was “no option at all to migrate Test PLAN, Test Cycle (History)”.
Those are Zephyr Squad experiences rather than Zephyr Scale ones, but the lesson generalises to every tool in this category, ours included. After each batch, compare counts per folder against your export file, not against the importer’s summary screen. An importer can only report on the rows it decided to process.
The two fields no 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 your export cannot fill in, because no other test tool has those two columns.
Do not stall the migration on it. Set both to a middle value on import, or bulk-set them per folder if your folder tree already encodes risk, and refine during the first month of real use. The coverage numbers will be approximate for a few weeks and then become the most useful report you have.
Execution history: the part we tell people not to migrate
Execution history is the hardest thing to carry across from any test management tool, and it is where migrations quietly fail. A single execution is not one row. It is a result 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 it into a different model gives you something that looks like history without being the same evidence.
Our recommendation, even though it means you keep paying someone else for a while: keep Zephyr Scale installed and read-only for as long as your audit window requires, export the cycles to a file as a second copy, migrate the test cases, and start fresh cycles in BesTest. If an auditor ever needs a specific historical run they will accept the original system or its export. What they will not accept is a re-keyed approximation with a new set of timestamps on it.
There is a narrow exception. If you only need the last release cycle for continuity rather than for audit, re-running that cycle in BesTest is usually faster than importing it, and it doubles as the pilot.
Attachments: BesTest does not support them yet
BesTest has no file or screenshot attachments on test cases or executions today. There is 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.
The workaround keeps evidence in Jira, where your organisation already retains it: create or link a Jira work item from the test case or execution and attach the screenshots, logs and files there. BesTest links bidirectionally with Jira work items, so the evidence stays one click from the test and inherits your existing Jira permissions and retention rules.
For the migration itself, every attachment in Zephyr Scale needs a decision rather than a mapping. In practice most teams re-attach the handful that are still referenced to a Jira work item and leave the rest in the read-only archive.
Let an agent do the reshaping
The slow part of a migration is rarely the import itself. It is the reshaping: turning one tool’s export into another tool’s template, column by column, then doing it again when the first attempt reveals a field you forgot.
BesTest exposes an MCP server, so an AI agent can read your export in whatever shape it arrived - a spreadsheet, a CSV, a pasted table - and rebuild the structure directly: folders, requirements, test cases with their steps, and the links between them in the same pass. The links are precisely 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 to use 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 Zephyr Scale to BesTest, and anyone who offers you one is describing the easy 20% of the job. What works is one pilot project taken all the way through, then repetition.
Pilot one project
- Pick an active project with a real release in the window, not the quiet one
- Move its folder tree and test cases: requirements first, then cases with links
- Run one complete test cycle in BesTest before touching any other project
- Write down every field you had to drop, because that list is your mapping spec
Expand project by project
- Reuse the column mapping you settled during the pilot instead of re-deciding
- Set Dev Complexity and Impact as you go rather than in a later sweep
- Move evidence for open work onto linked Jira work items as you migrate each area
- Keep Zephyr Scale authoritative for a project until that project has run a cycle in BesTest
Cut over and archive
- Switch new work to BesTest on a date people know about in advance
- Make Zephyr Scale read-only rather than uninstalling it
- Keep it until your audit retention window closes, then export and remove
- Do not schedule the licence cancellation before that date
Six weeks is a realistic shape for a mid-sized instance. The pilot is the phase that decides the outcome: once one real cycle has run end to end in BesTest, everything after it is repetition. Migrations that skip the pilot and open with a full-library import are the ones that stall in month two.
Common questions about leaving Zephyr Scale
How do I export test cases from Zephyr Scale?
Open the Tests view in Zephyr Scale, select the test cases you want, and export them to a spreadsheet. Save the result as CSV if your next tool prefers it. For larger libraries, or if you want the export to be repeatable, Zephyr Scale has a REST API that returns the same data without the click path. Export the test-case-to-Jira-issue links separately, because coverage in Zephyr Scale comes from a link rather than from a field on the test case.
Do requirement-to-test links survive a migration?
They survive if you import in two passes. Import requirements first with the Linked Test Cases column empty, download the result file that maps each row to its new BesTest requirement key, then import your test cases with those keys filled into the Linked Requirements column. Coverage is then created as part of the import. A single flat import in either direction cannot do this, because the keys you need to link to do not exist until the other side has been imported.
Can I migrate my Zephyr Scale execution history?
You can move some of it, but in most cases you should not try. An execution is not one row: it is a result per step, attached to a cycle, an environment, a build, a tester and a timestamp, in a shape that only makes full sense inside the tool that recorded it. Reshaping that into another tool produces something that looks like history without being the same evidence. The cheaper and more defensible option is to keep Zephyr Scale read-only for as long as your retention window requires, migrate the test cases, and start fresh cycles in BesTest.
What happens to attachments on my Zephyr Scale test cases?
BesTest does not support file or screenshot attachments yet, so there is no import path for them. The workaround is to keep evidence on Jira: create or link a Jira work item from the test case or execution and attach the screenshots, logs and files there. BesTest links bidirectionally with Jira work items, so the evidence stays one click away from the test. During a migration, most teams re-attach only the handful that still matter and leave the rest in the read-only archive of the old tool.
How long does a Zephyr Scale migration take?
For a mid-sized Jira instance, plan roughly six weeks in three phases: one or two weeks to pilot a single project end to end, three to four weeks to repeat that across the remaining projects, then a cutover date followed by an archive period. The pilot is the phase that decides everything. If one real test cycle runs end to end in the new tool, the rest is repetition. Migrations that skip the pilot and start with a full-library import are the ones that stall.
Do I have to uninstall Zephyr Scale to start?
No, and you should not. Run both in parallel during the migration, with Zephyr Scale authoritative for any project that has not yet completed a cycle in the new tool. When a project cuts over, make Zephyr Scale read-only for it rather than removing the app. Keep the app installed until your audit retention window closes, since that read-only history is cheaper to keep than to reconstruct.
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