Skip to main content

Migrate & Export Test Cases

Bring your manual test cases into Agnox from Qase, TestRail, Xray, Zephyr Scale or any CSV, and turn them into ready-to-implement Playwright .spec.ts skeletons.

This page is the step-by-step guide. For every field, limit and error code, see the Import and export reference.


How a migration works​

  1. Export the test cases from your current tool as CSV (or JSON for Qase).
  2. Preview the file in Agnox. The preview is a dry run: it shows the detected format, how many cases and folders it will create, duplicates, and any row errors. Nothing is written yet.
  3. Import. Agnox recreates your folder tree, gives each case an AG-TC-N id, and records where it came from (importSource: format, original id, import time).

Who can do it: Admins and Developers can import. Every role can export.

Import from the dashboard​

  1. Open Test Cases and select the project.
  2. Click Import. The Import test cases dialog opens.
  3. Choose your file. Leave Format on Detect automatically, or pick one: TestRail CSV, Qase JSON or CSV, Xray CSV, Zephyr Scale CSV, Other CSV (Title, Steps, …), Agnox JSON or Agnox CSV.
  4. Choose what happens to cases that already exist with the same title in the same folder: Skip them (recommended for re-runs) or Import them again.
  5. Click Preview and review the counts, the folders to be created, the first cases, and any row errors.
  6. Click Import.

A row without a title is reported with its row number and skipped, and the rest of the file is still imported. Fix the reported rows and import the file again with Skip them, so only the missing cases are added.


Exporting from your current tool​

Agnox detects the format from the file's header row, so export with the tool's default columns. XML exports are not supported: use CSV, or JSON for Qase.

TestRail​

Export a CSV from the test suite or project. Both layouts are supported:

  • one row per case, with steps in a single cell
  • separated steps: one row per step
Agnox fieldTestRail column
TitleTitle
FolderSection Hierarchy (preferred) or Section
DescriptionDescription or Goals
PreconditionsPreconditions
Steps / expected resultsSteps (Step) + Steps (Expected Result), or Steps + Expected Result
SeverityPriority
TagsRefs or References
Original idID

Detected by: a Section or Section Hierarchy column.

Qase​

Export the project as JSON (recommended, because it keeps the nested suites tree) or CSV.

Agnox fieldQase field
Titletitle
Folderthe suite tree: nested suites in JSON, or suite_id / suite_parent_id in CSV
Descriptiondescription
Preconditionspreconditions
Steps / expected resultssteps_actions + steps_result
Severityseverity, then priority
Tagstags
Original idid

Detected by: a top-level suites array (JSON), or suite/suite_id + title columns (CSV). Qase's severity is read before priority, because only severity carries blocker and critical.

Xray (Jira)​

Export the tests to CSV with one row per step.

Agnox fieldXray column
TitleSummary
FolderTest Repository Path (preferred) or Test Set
DescriptionDescription
PreconditionsPrecondition or Pre-Condition
Steps / expected resultsAction (or Step) + Expected Result
SeverityPriority
TagsLabels
Original idIssue Key or TCID

Detected by: an Issue Key or Test Type column, together with Summary.

Zephyr Scale​

Export the test cases to CSV with step-by-step test scripts.

Agnox fieldZephyr Scale column
TitleName
FolderFolder
DescriptionObjective
PreconditionsPrecondition
Steps / expected resultsTest Script (Step-by-Step) - Step + Test Script (Step-by-Step) - Expected Result
SeverityPriority
TagsLabels
Original idKey

Detected by: a Name column, together with Folder or Test Script (Step-by-Step) - Step.

Any other tool, or a spreadsheet​

Save the sheet as CSV with a header row. Only a title column is required. Column names are matched case-insensitively:

Agnox fieldAccepted column names
Title (required)title, name, summary
Folderfolder, suite, section. Nest with /, > or /, for example Checkout / Payments
Stepssteps, action
Expected resultexpected, expected_result, expected result
Severitypriority, severity
Tagstags, labels (separated by ; or ,)
Title,Folder,Steps,Expected,Priority,Tags
Valid login,Login / Happy Path,"1. Open /login
2. Enter valid credentials
3. Submit",Dashboard is shown,High,smoke;auth
Wrong password,Login,"1. Open /login
2. Enter a wrong password",An error is shown,Medium,auth

Priority mapping​

Your valueAgnox severity
critical, blocker, highest, p0CRITICAL
high, major, p1HIGH
medium, normal, p2MEDIUM
low, minor, trivial, lowest, p3LOW
anything elseMEDIUM, with a warning in the preview

Import with the API​

Automate a migration with an API key and POST /api/v1/test-cases/import. Send a dry run first, then the real import:

# Build the request body from the export file
jq -n --rawfile content testrail-export.csv \
'{projectId: "665f…", format: "auto", filename: "testrail-export.csv",
content: $content, dryRun: true, duplicateStrategy: "skip"}' > import.json

# 1. Preview: parses and validates, writes nothing
curl -s -X POST https://api.agnox.dev/api/v1/test-cases/import \
-H "x-api-key: $AGNOX_API_KEY" -H "content-type: application/json" \
--data @import.json | jq '.data | {format, total, toCreate, duplicates, invalid, errors}'

# 2. Import for real
jq '.dryRun = false' import.json | curl -s -X POST https://api.agnox.dev/api/v1/test-cases/import \
-H "x-api-key: $AGNOX_API_KEY" -H "content-type: application/json" \
--data @- | jq '.data | {created, createdFolders}'

Limits per import: 5 MB file, 2,000 cases, 200 steps per case, folder depth 10. Split larger exports by folder or suite.


Export manual cases as Playwright skeletons​

Once your manual cases are in Agnox, generate Playwright specs for them so automation starts from the agreed steps instead of a blank file.

From the dashboard​

Test Cases → Export → Playwright spec downloads agnox-export.spec.ts. It exports the selected rows, else the open folder, else the whole project.

From the terminal​

The agnox CLI writes one spec per top-level folder straight into your repository:

export AGNOX_API_KEY="<your key>"
npx -p @agnox/mcp-server agnox export-specs --out tests/generated --project <project id>
# wrote tests/generated/checkout.spec.ts
# wrote tests/generated/login.spec.ts
# Exported 2 spec files to tests/generated

Add --folder /Checkout to export one folder. Existing files are never overwritten unless you pass --force.

What you get​

// Generated by Agnox from manual test cases. Each test is marked fixme until implemented.
import { test } from '@playwright/test';

test.describe("Checkout", () => {
test.describe("Payments", () => {
test("C1042: Pays with a saved card", { tag: ['@smoke'] }, async () => {
test.fixme(true, "Generated from C1042: implement the steps below");
// Step 1: Open the cart with one item
// Expected: The cart total is shown
// Step 2: Pay with the saved card
// Expected: The order confirmation page is shown
});
});
});
  • Folders become nested test.describe blocks.
  • Each manual case becomes a test() named after its original id and title, with its tags as Playwright tags.
  • Steps and expected results become comments, in order.
  • test.fixme(...) marks every test as not implemented yet, so a skeleton never passes, and never fails your suite, before someone writes it.
  • Automated cases are skipped, because they already have a spec. The file header says how many were skipped.

Close the loop​

After you implement a skeleton, register it as an automated test case, so Agnox tracks its stability and you can quarantine it:

  • run it once with the Playwright reporter, or
  • ask your assistant to call sync_test_cases through the MCP server, or call POST /api/v1/test-cases/sync directly.

Export to other formats​

Test Cases → Export also offers:

FormatUse it for
JSONA full Agnox bundle. Re-imports losslessly, for backups or moving cases between projects.
CSVSpreadsheets and other test management tools. Formula-like cells are escaped.
MarkdownA readable document, with a heading per folder and a step table per case

The format details are in the Import and export reference.