TestOps logo
Try TestOps

TestRail

TestRail export sends test cases and launch data from Allure TestOps into TestRail. It is a one-way outbound sync, not an identity-linking path and not a migration workflow.

Allure TestOps only supports exporting to TestRail projects that use multiple test suites. See Projects and their types in the TestRail documentation to change the project type if necessary.

It covers:

  • exporting test cases from TestOps to a TestRail project, suite, and section;
  • exporting launch data for the selected test-case set;
  • scoping the export with AQL;
  • mapping TestOps fields and workflow statuses into TestRail.

Before you begin

  • API access enabled in TestRail.
  • A TestRail API key.
  • The target TestRail project name, suite ID, and section ID.
  • The AQL filters that define which test cases and launches should be exported.

1. Enable TestRail API access and create the API key

Enable the API

  1. In TestRail, go to Administration → Site Settings → API.
  2. Check Enable API and Enable session authentication for API.
  3. Click Save Settings.

Create the API key

  1. In TestRail, click your name in the top right corner and select My Settings.
  2. Go to the API Keys tab.
  3. Click Add Key.
  4. Enter a name to identify the key, for example Key for Allure TestOps.
  5. Click Generate Key and copy the generated key.
  6. Click Add Key, then Save Settings.

2. Add the global TestRail integration

An instance administrator should:

  1. Open Administration → Integrations in TestOps.

  2. Click + Add integration.

  3. Select TestRail.

  4. Fill in the fields:

    • Name — a stable name for the integration, for example TestRail production.
    • Endpoint — the URL of the TestRail instance, for example https://example.testrail.io/.
    • TestRail version — 6.7 or later.

  5. If the TestRail instance uses a self-signed certificate, check Disable certificate validation.

  6. Click Add integration.

3. Enable TestRail in the TestOps project

  1. In TestOps, open the target project.

  2. Go to Settings → Integrations.

  3. Under Available integrations, find the TestRail integration and click Add integration.

  4. Fill in the fields:

    • Username — the email address used to sign in to TestRail.
    • API key — the API key from step 1.

  5. Click Test connection. If the credentials are correct, a "Connection established" message appears.

  6. Click Add integration.

4. Find the TestRail suite and section IDs

All test cases exported from Allure TestOps land in a single section of a single suite in TestRail. You need the suite ID and section ID before configuring the sync.

  1. In TestRail, open the target project.

    Note the project name — you will enter it in the Project field in step 5.

    The project name is at the top of the project page

  2. Go to the Test Suites & Cases tab and open the target suite (create one if needed).

    The suite ID is shown next to the suite name.

    The suite ID is next to the suite name

  3. In the tree view, click the target section (create one if needed).

    The section ID appears as the group_id parameter in the browser URL.

    The section ID is in the page URL when the section is selected

5. Create the TMS Sync export configuration

  1. In the TestOps project, go to Settings → Integrations and open the TestRail integration.

  2. Go to the TMS Sync tab and click Create.

  3. Choose the destination Project.

  4. Enter the Suite ID and Section ID from step 4. Use the numeric part only — for example, enter 29, not S29.

  5. Fill in the export scope:

    • Test Case AQL — an AQL expression for the test cases to export. Leave empty to export all test cases.
    • Launches AQL — an AQL expression for the launches to export. Leave empty to export all launches.
    • Disable Test Case create — enable after the initial export if the destination should only receive updates for already exported cases.
    • Disable Launches sync — enable if the job should export test cases without launch history.
    • Disable export — enable to pause the configuration without deleting it.

  6. Click Submit.

An empty Test Case AQL exports all test cases into the selected suite and section. An empty Launches AQL exports all launches for that scope.

The TMS sync is automatically disabled if the credentials are invalid, revoked, or have insufficient access. To restore sync, update the project integration credentials and re-enable the export.

6. Map fields when you need more than the default export

TestRail does not expose every TestOps field as a standard destination field. For fields such as description, precondition, expected result, or scenario, you need to create matching custom fields in TestRail first.

Create custom fields in TestRail

  1. In TestRail, go to Administration → Customizations.

  2. For each field to export, click Add Field and fill in:

    • Label — the display name in TestRail, for example Description or Precondition.
    • System Name — the unique identifier used by Allure TestOps, for example description or preconds.
    • Type — Steps for the scenario field if you want it step-structured; Text for all other fields.

  3. Click Add Projects & Options, go to the Selected Projects tab, select your project, and click OK.

  4. Click Add Field.

Configure mapping in Allure TestOps

  1. In the TestOps project, open the TestRail integration.
  2. On the TMS Sync tab, click Edit.
  3. For each field to export, enter custom_ followed by the system name you set in TestRail, for example custom_description.
  4. Click Submit.

7. Map workflow statuses when needed

If exported test cases should preserve TestOps workflow status, create a corresponding dropdown field in TestRail and map the status IDs.

Get TestOps status IDs

  1. In TestOps, go to Administration → Status.

  2. Note the numeric ID of each status.

    The statuses and their IDs are listed in the Status section

Create the status field in TestRail

  1. In TestRail, go to Administration → Customizations.

  2. Click Add Field and fill in:

    • Label — for example Status.
    • System Name — for example status.
    • Type — Dropdown.

  3. Click Add Projects & Options.

  4. On the Options tab, enter one status per line in the format identifier, Name, for example 1, Passed. The identifiers must be unique positive integers. Note each identifier — you will use them in the next step.

    The Configure Options dialog allows entering multiple statuses with their identifiers

  5. On the Selected Projects tab, select your project.

  6. Click OK, then Add Field.

Configure status mapping in Allure TestOps

  1. In the TestOps project, open the TestRail integration.

  2. On the TMS Sync tab, click Edit.

  3. Under Status Mapping, fill in:

    • Field name — the system name of the TestRail dropdown field, for example status.
    • Default value — custom_ followed by a TestRail status identifier, for example custom_1. Used when no mapping row applies.

  4. For each TestOps status, click Add and fill in:

    • Source ID — the TestOps status ID from Administration → Status.
    • Target ID — the matching TestRail status identifier.

  5. Click Submit.

Verify the integration

  1. Run the export configuration.
  2. Open the destination TestRail project and confirm that the expected test cases appear in the selected suite and section.
  3. If launch export is enabled, confirm that the expected execution data arrives for the exported cases.
  4. Check a mapped field or status on the TestRail side and confirm it uses the expected value.

Troubleshooting

The export configuration disables itself

The TestRail credentials are invalid, revoked, or no longer have sufficient access to the target project. Update the project integration and re-enable the export.

The test cases land in the wrong place

Recheck the Project, Suite ID, and Section ID in the TMS Sync configuration. TestRail expects numeric identifiers — enter 29, not S29.

© Qameta Software Inc. All rights reserved.