Migrate TestRail Test Cases to Markdown in Git
To move TestRail test cases into git, import them into TestChimp, where each case becomes a scenario stored as a Markdown file. Then sync those files to your repo as a pull request, review and merge it, and link your Playwright tests to the scenarios. Sync stays two-way afterwards.
Last updated: 2026-10-01
What do you need before you start?
- A TestChimp project with your git repo connected (GitHub or GitLab) and a plans folder mapped. See Code repository overview.
- TestRail API access enabled: in TestRail, go to Admin, then Site Settings, then API.
- A TestRail API key, generated under My Settings in TestRail (not your account password), and the login email you use for TestRail.
- Optional: Jira or Linear access, if your user stories live there and you want TestRail cases linked to them.
Credentials are used by the import wizard for that import and are not stored.
How do you migrate, step by step?
Step 1: Import your stories first (optional, recommended if you use Jira)
If your stories live in Jira, import them before the TestRail cases, so cases that reference Jira tickets can be linked automatically.
- In Test Planning, open the Import / Export menu and choose Import from..., then Jira.
- Enter your Jira URL, email, an Atlassian API token and the project key. Optionally add a JQL query to narrow what is imported.
- Choose the Jira issue type to treat as a user story. Leave the test scenario issue type blank if your test cases live in TestRail, so only stories are imported.
- Choose file naming (external ID, TestChimp ID, or AI deduce) and folder structure, check the preview counts, then start the import.
Linear works the same way: you provide an API key and team key, pick the labels that identify stories and scenarios, and scenarios must be sub-issues of their parent story for linking to work.
Step 2: Import TestRail cases as scenarios
- In Test Planning, open Import / Export, then Import from..., then TestRail.
- Enter your TestRail URL, login email and API key.
- Select the TestRail project. If it uses multiple test suites, select the suite too. You can add an optional title filter.
- On the preview step, click Count test cases to see how many cases match. If Jira-imported stories exist, they are used for linking.
- Choose file naming (external ID such as
C4075, TestChimp ID such asTS-1, or AI deduce) and folder structure (the TestRail section hierarchy, or AI deduce). - Click Start import. The job runs asynchronously and shows progress. When it finishes you see how many scenarios were created or updated and how many story links were created from Jira references.
Each TestRail case becomes a TestChimp scenario, a Markdown file with frontmatter. Cases whose references do not match an imported story are still imported, just without the link; you can link them later in Test Planning.
Step 3: Check the result
Open a few imported scenarios and compare them with the TestRail originals. The docs describe cases becoming scenarios but do not describe run history, attachments, custom fields or shared steps, so check those on a sample before you rely on them.
If something is wrong, use Import / Export, then Revert recent import, which deletes everything created by the most recent import. Then adjust options and import again.
Step 4: Sync the Markdown to your repo
- In Test Planning, open Import / Export and choose Sync to Git Repo.
- TestChimp compares your files with the repository and shows a diff.
- Create the pull request. TestChimp opens it on a branch prefixed
testchimp-. - Review and merge it like any other change.
From here, the scenarios are Markdown in your repo. Sync is two-way: changes you make in TestChimp arrive as pull requests, and commits to the mapped plans folder come back into TestChimp.
Step 5: Link your automated tests to scenarios
Add a Playwright annotation to each test with the scenario's ordinal:
test('successful login', {
annotation: [{ type: 'scenario', description: '#TS-101' }],
}, async ({ page }) => {
// ...
});
TestChimp links the test to the scenario by its #TS-<n> ordinal and tracks results from CI runs reported by the @testchimp/playwright plugin. One test can list several scenarios. See Requirement traceability.
Step 6: Run both systems in parallel, then retire TestRail
Keep TestRail available for historical audit until coverage in TestChimp overlaps what you rely on. Many teams treat the git-synced Markdown as the source of truth and keep the old tool only for history.
What are the limits of the import?
| Topic | What to know |
|---|---|
| Free trial limits | Up to 100 imported TestRail cases and up to 25 imported stories (Jira or Linear) |
| What a case becomes | A scenario, as a Markdown file |
| Story links | Created automatically when a TestRail case references a Jira ticket that was already imported |
| Credentials | Used for the import and not stored |
| Undo | Revert recent import removes everything from the most recent import |
| Run history, attachments, custom fields, shared steps | Not described in the docs. Do not assume they are carried over; check on a sample |
| Sources | Jira, Linear and TestRail |
What happens after the migration?
Once the scenarios are in git, TestChimp runs the QA process as a closed feedback loop on top of them. Developers run /testchimp run QA after a pull request, agents work through coverage gaps, and results flow back. Meet-Bots and AgentWatch keep the scenarios current from meetings and coding-agent chats, so tests are written against up-to-date requirements. Governance signals (Verified Tests, API schema coverage, TrueCoverage and semantic coverage) show what is covered and who verified it.
Only Verified Tests status lives solely in TestChimp. Everything else is in your git repo or covered by the full download of data not stored in git. For the full picture see A git-native TestRail alternative.
Frequently asked questions
Can I import TestRail test cases from a CSV file?
No. TestChimp does not import from CSV files. The TestRail import uses the TestRail API with your URL, login email and API key.
Do I need Jira to import from TestRail?
No. TestRail cases import as scenarios on their own. Importing Jira stories first only adds automatic links between cases and stories.
Does my TestRail history come across?
The docs describe cases becoming scenarios. They do not describe run history, results or attachments, so do not plan on them. Keep TestRail for historical audit.
Can I undo an import?
Yes. Import / Export, then Revert recent import, deletes everything created by the most recent import.
Is there a limit on the free trial?
Yes: up to 100 TestRail cases and up to 25 Jira or Linear stories.
Will my Markdown files stay in sync with TestChimp?
Yes. Sync is two-way. Changes made in TestChimp reach your repo as pull requests, and commits to the mapped folders come back.