> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qa.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# TestRail

> Pull your existing TestRail cases into the QA.tech AI chat and turn them into tests

The TestRail integration lets the [AI Chat Assistant](/core-concepts/ai-chat-assistant) read the test cases you already have in TestRail. You can explore them in chat and turn any of them into a QA.tech test without re-authoring the steps by hand. Nothing is synced in the background. Cases are fetched on demand when you ask for them.

<Note>
  **Authentication:** email plus API key (HTTP Basic auth). The key is stored
  encrypted and is never shown again after you save it.

  **Reachability:** your TestRail instance must be reachable over **HTTPS** at a
  public address. Instances that are only available on an internal or private
  network are not supported.

  Both TestRail Cloud and self-hosted TestRail work, as long as the instance is
  reachable over HTTPS.
</Note>

## How it compares to Custom MCP

TestRail is a first-party integration: you enter your credentials and QA.tech handles the connection. This is different from [Custom MCP servers](/core-concepts/ai-chat-assistant#custom-mcp-servers), where you bring your own MCP server. If you only need to read TestRail cases into chat, use this integration. Use Custom MCP to connect a different MCP server, whether you host it yourself or point at a hosted one.

## Before you start

Enable the API and generate a key in TestRail. Both steps need TestRail administrator access for the first one, and any user can create their own key.

<Steps>
  <Step title="Enable the TestRail API">
    In TestRail, go to **Administration → Site Settings → API** and turn on
    **Enable API**. This requires TestRail administrator access.
  </Step>

  <Step title="Create an API key">
    Click your avatar, then **My Settings → API Keys → Add Key**, and copy the
    generated key. TestRail shows it only once. The email you use to connect
    must be the account this key belongs to. See the [TestRail API
    docs](https://support.testrail.com/hc/en-us/articles/7077039051284-Accessing-the-TestRail-API)
    for details.
  </Step>
</Steps>

## Setup

<Steps>
  <Step title="Open the TestRail integration">
    In your project, go to **Settings → Integrations** and select **TestRail**.
  </Step>

  <Step title="Enter your credentials">
    Fill in:

    * **Instance URL:** your TestRail address, for example `https://yourco.testrail.io`
    * **Account email:** the email the API key belongs to
    * **API key:** the key you generated above

    Then click **Connect TestRail**.
  </Step>

  <Step title="Test the connection">
    Click **Test connection** to confirm QA.tech can reach your instance. It
    reports how many projects the credentials can see, which is a quick way to
    confirm the key and email match.
  </Step>
</Steps>

To change the key later, open the integration, enter a new key, and save. Leave the API key field blank to keep the stored one and update only the URL or email.

## Using TestRail in chat

Once connected, ask the [AI Chat Assistant](/core-concepts/ai-chat-assistant) to work with your TestRail cases. It reads them through your project's credentials.

| You ask for | What the assistant does |
| - | - |
| Your TestRail projects | Lists the projects the credentials can see, so you can pick the right one |
| Cases in a project | Lists case titles, paginated so large projects stay readable |
| Cases in a specific suite | Scopes the list to one suite (needed for multi-suite projects) |
| Cases matching a word | Filters the list by a case-insensitive match on the case title |
| A single case in full | Fetches the title, preconditions, and steps for one case |
| A QA.tech test from a case | Reads the case in full and drafts an equivalent QA.tech test |

Example prompts:

> "List our TestRail projects"

> "Show the test cases in the Checkout suite"

> "Open TestRail case 1234 and create an equivalent QA.tech test"

<Tip>
  For projects with more than one suite, tell the assistant which suite you
  mean, or ask it to list the suites first, so it can scope the cases correctly.
  If you do not name a suite, it will ask which one you want.
</Tip>

### Test types it can read

The assistant reads both step-based cases and cases that store their steps in a
single text field. Preconditions come across as context for the test. Fields
that TestRail stores as custom values, such as references and priority, are read
for context but do not always map to a QA.tech field.

## Linked test cases

When you create a QA.tech test from a TestRail case, the new test keeps a link
back to the case it came from.

* Before you approve the suggestion, the chat shows a **Reports results to** line
  with the source case, so you can catch a wrong link early.
* In your **Test Cases** list, the test shows a **TestRail** badge next to its
  labels, for example `TestRail 1234`. Click the badge to open the case in
  TestRail.

Duplicating or copying a linked test does not carry the link over, so two tests
never point at the same TestRail case by accident.

## Limitations

| Supported | Not supported |
| - | - |
| Read cases on demand in chat | Background sync or webhooks |
| List projects, suites, and sections | Editing TestRail cases from QA.tech |
| Filter cases by a word in the title | Full TestRail query syntax in chat |
| Fetch one case in full, with steps | Bulk import of a whole project in one action |
| Create a QA.tech test from a case | Pushing QA.tech run results back into TestRail |
| TestRail reachable over HTTPS on a public address | Internal or private-network instances |

## Removing the integration

To disconnect, open **Settings → Integrations → TestRail** and click **Remove**.
This deletes the stored credentials, including your API key. Test cases you have
already created in QA.tech are not affected, and they keep their TestRail badge.

## Related documentation

* [Xray](/integrations/xray): the same capability for Xray tests in Jira
* [Custom MCP servers](/core-concepts/ai-chat-assistant#custom-mcp-servers): connect any other MCP server, self-hosted or hosted
* [AI Chat Assistant](/core-concepts/ai-chat-assistant): where you work with your cases
* [Exporting test cases](/api-reference/exporting-test-cases): export QA.tech tests for use elsewhere


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.