Runbook: move Zephyr Scale test cases into TestWarden

To migrate Zephyr Scale test cases into TestWarden, export the cases from the Zephyr Scale test library, save the exported sheet as UTF-8 CSV, open the Migration Center, choose Zephyr Scale CSV, read the preview, import and reconcile. The adapter detects the column mapping from the file’s headers, folds multi-row step tables into structured steps, and preserves every column it does not map as a custom field. What it cannot do is bring your history, and this runbook spends as much time on that boundary as on the mechanics.

A note on scope before the details. This page is about Zephyr Scale on Jira Cloud, formerly TM4J, and describes the Cloud export menu. Zephyr Squad is a different product, and Zephyr Scale Server and Data Center have their own export documentation. If a file from another edition arrives with the same headers, the preview will still tell you whether it parses, and that is a more reliable test than any edition checklist. We describe the capabilities SmartBear documents, and where their documentation is silent we say so rather than infer an API or export feature that may not exist.

The visual follows a file through export format, CSV conversion, header mapping, step mapping, preview and reconciliation using invented rows, and its coverage matrix can be filtered by what transfers, what is kept as a custom field, what you rebuild and what does not transfer. Everything it shows is also stated in the text below.

Before you start: migrate, keep, or run side by side

Most teams reading a migration runbook have already decided to leave their current test manager. Some have not, and for them the best outcome of reading is to realise that migration is not the only way to get value from TestWarden. It is an independent, policy-driven verification layer above test-management tools, CI systems, scanners and AI coding agents. You can keep Zephyr Scale as your test manager, let your pipeline submit JUnit XML or SARIF to The Warden, and have The Warden decide whether the combined evidence is enough for an exact build. The same Jira app is also a full native test manager, which is what you are moving into if you proceed.

Whichever route you take, write down three things first: which projects move, what you will do with historical cycles and executions, and who owns the cutover date. The rest of the runbook assumes you are migrating one project at a time, because a pilot teaches you more per hour than a big-bang migration, and the second project goes in a fraction of the time.

Step 1: export from Zephyr Scale

SmartBear documents the export in Working with Test Cases: select the test cases in the library, open the More menu and choose Export to Excel, or Export to XML. The TestWarden adapter reads CSV, so use the Excel export. Keep the exported header row exactly as it is; the adapter recognises the headers by name, and renaming a column to something you find tidier will make it unrecognisable.

The adapter recognises headers such as Name, Key, Objective, Precondition, Priority, Status, Labels, Folder, Component, Coverage Issues and the step-by-step columns for the step, its test data and its expected result. Plain-text and BDD script columns are also recognised. SmartBear’s documentation does not state export limits or enumerate the fields in the Excel file, so we cannot tell you how many cases one export can hold or which of your custom fields appear. Check your own file.

Choosing what to select

Export by folder where you can. Folder boundaries are the most natural unit of migration, they keep each file small, and they give you a clean reconciliation target: the number of cases in the folder equals the number you expect to import. A test with many steps occupies many rows in the export, so a folder of 300 tests might produce several thousand rows and approach the 10,000-row limit on its own. If a folder is large, split it, and keep the files separate and clearly named.

Use the same moment to prune. A migration is the cheapest opportunity you will ever have to decide that some tests are obsolete. Deprecated cases can be left behind in Zephyr Scale if you keep it readable, or imported and archived if you prefer a complete record; either is defensible, and the point is that you chose.

Step 2: convert to CSV without damaging it

Open the Excel export and use your spreadsheet application’s Save As to write a UTF-8 CSV, choosing a UTF-8 option if one is offered. Three things commonly go wrong at this step, and none are the importer’s fault.

• Encoding. A CSV saved in a legacy code page turns accented characters and typographic symbols into question marks. If your tests contain non-ASCII text, open the saved file in a UTF-8 aware editor and look.
• Multi-line cells. Step text often contains line breaks inside a cell. A well-formed CSV quotes those cells. A hand-edited one may not. If the preview shows steps cut off or shifted, a broken quote is the likeliest cause.
• Lost leading zeros and date coercion. Spreadsheet applications helpfully convert some text into numbers or dates. If a custom field holds codes such as 007, check it survives.

Keep the original Excel file and the CSV you produced from it. The first is your evidence of what Zephyr Scale exported. The second is your input, and the one you re-run if the mapping needs adjusting.

Step 3: prepare the account and the plan

• Role. You need the QA Admin role in TestWarden. Migration is admin-only.
• Limits. 10 MB and 10,000 rows per job. Rows, not tests, are what count, so multi-step tests weigh more.
• Status mapping. Decide in advance what the Zephyr statuses mean to you. Approved and Ready map to Ready. Draft and Deprecated map to Draft. Other values, such as a custom “In review”, fall back to the TestWarden default with a warning.
• Naming. A test must have a name; a row without one is skipped with a stated reason.

Step 4: header mapping and structured steps

Open Migration, choose Zephyr Scale CSV and upload the file. Because the adapter recognises Zephyr Scale headers, the column mapping is detected automatically and you review it rather than build it. Here is what it does with the common columns.

The step mapping is the part most worth checking. Zephyr Scale stores a test’s steps as a table, and the export writes one row per step, repeating the test’s identity. The adapter folds those rows into a single test with several structured steps, each carrying an action, test data and an expected result. Plain-text and BDD script columns are also recognised, for tests that were written as scripts rather than step tables. After the preview, open a test you know well and compare its steps one by one with Zephyr Scale; if the count is right and the order is right, the folding worked.

Why the objective and preconditions are merged

Zephyr Scale separates objective and precondition; TestWarden’s test has a description. Merging them keeps the reason for the test and the state it assumes in one place, which is where a tester looks first. If you prefer them separate, map the columns to custom fields instead; the cost is that they will not appear in the description until you copy them.

Step 5: preview and import

1. Read Will import, Will skip and Total rows, then read every skip reason. A skip is a row you must agree should not import.
2. Confirm that multi-row step tables were folded into one test with several steps, and sample a test from each folder.
3. Check statuses in the sample. Approved and Ready should show as Ready; anything that fell back to the default has a warning.
4. Commit. Batches of 200 run in the background with checkpoints, and the job is resumable and idempotent: re-running the same file and mapping does not create duplicates.

Step 6: reconcile

Filter the report by Imported, Imported with warnings, Skipped and Failed. Compare the imported count with the number of cases you exported. Open several complex tests next to their Zephyr originals. Treat the warnings as a to-do list: each one is a value TestWarden did not recognise, which you can accept or fix with bulk edit after the import. Keep the report with the original export; together they are the record of exactly what moved and what did not.

Step 7: rebuild structure and links

• Folders. Recreate folders and tags in the shared Library from the preserved Folder field, then file tests in bulk.
• Requirement links. Re-link requirement coverage to Jira issues, using the preserved coverage-issue values as your list.
• Plans and cycles. Create plans and cycles from the imported library. Each attempt is version-pinned, so later edits do not rewrite what a past run verified.
• Components. Decide whether the preserved component values should become tags, or stay as a field you filter on.

Historical data: what you will not carry across

This is the part of any Zephyr migration that deserves the most thought. The CSV path brings test case definitions. It does not bring test cycles, test plans, execution history, folders as structure, requirement links or attachments. Historical results stay in Zephyr Scale.

As noted, we could not verify a documented bulk export of cycles and executions for the Cloud edition from SmartBear’s test-case export page, so check Zephyr Scale’s own reporting and export options for what you must retain, and keep read access to it until that obligation ends. Attachments are a separate case. Xray’s published Zephyr Scale import guide notes that attachments are not included in the XML export, and nothing in the CSV path carries them either.

The cleanest cutover is a dated one. Choose a date after which new attempts are recorded in TestWarden, write it down, and keep Zephyr Scale readable until your longest retention period for older releases has passed. After that date, the history of decisions, evidence receipts and attempts accumulates in Quality Memory, per tenant and append-only. For a release audited later, where the evidence lives is then a matter of the date, not a hunt.

Zephyr Scale CSV migration versus a live collector

As with the other sources, there are two different things to keep apart. The CSV migration in this runbook copies cases once. TestWarden also has a Zephyr Scale Cloud collector in source, which is a read-only collector that runs in your own CI with a Zephyr API access token you hold in your CI secret store. It reads the cycle’s executions from the Zephyr Scale Cloud REST API, version 2, and an attestor signs the result before The Warden evaluates it for an exact build. That collector targets Zephyr Scale Cloud, not Squad, Server or Data Center.

Its status is the same as the other four providers: documented-contract HTTP tests and a signed offline HELD-to-repaired-CLEARED test pass, and live vendor certification is pending. No vendor is certified. Repeated historical attempts must remain distinguishable and the collector must see the complete expected inventory, otherwise it refuses to produce a signed result. Treat it as a direction under acceptance rather than something to plan a release around. The Integrations page is kept current, and the developer documentation explains the evidence formats that already work today, which are JUnit XML, SARIF 2.1.0 and provider-neutral JSON from your CI.

Troubleshooting the preview

If the preview does not read the way you intended, resist editing records after import. It is almost always faster to correct the file and preview again, because the preview writes no tests until you commit and re-running the same file and mapping reuses the job.

Once the preview matches your expectations the import is routine. The effort in a Zephyr Scale migration lies in the decisions around it: which projects move, what you keep readable, and when you cut over. Those are people decisions, and the earlier you make them, the less the technical steps matter.

Frequently asked questions

Comparing tools first? See the Zephyr Scale alternative page and choosing test management for Jira Cloud. The sibling runbooks cover Xray and AIO Tests, and the Migration Center overview lists each source and its limits. To run a pilot on one folder, contact us or review pricing and the evaluation terms; the preview shows what will happen before any test is created.