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

# TestRail

> Index test cases from TestRail projects

The TestRail connector indexes test cases from your TestRail projects. Each case becomes one document,
with its steps and expected results as text and a link back to the case in TestRail.

## How it works

| Content     | Behavior                                                                                                                                                   |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Test cases  | One document per case. The document is named `<case key>: <title>` so a case is searchable by its TestRail key.                                            |
| Steps       | Separated steps and their expected results are indexed. When a case has no separated steps, Onyx falls back to its plain steps and expected-result fields. |
| Fields      | Custom field values are resolved to their labels, so a drop-down reads as its text rather than its stored number.                                          |
| Suites      | Onyx reads every suite in a project. A project in single-suite mode is read directly.                                                                      |
| Permissions | Not available. **Auto Sync Permissions** is not offered for TestRail, so the access type can only be **Public** or **Private**.                            |

## Before you begin

You need:

* The URL of your TestRail site, such as `https://example.testrail.io`
* A TestRail user that can read the projects you want to index
* An API key for that user
* TestRail's API enabled for the site
* An Onyx administrator account

See TestRail's [API accessibility
documentation](https://support.testrail.com/hc/en-us/articles/7077039051284-Accessing-the-TestRail-API)
for enabling the API and generating a key.

<Note>
  The connector reads only what its TestRail user can read.
</Note>

## Configure Onyx

<Steps>
  <Step title="Open the TestRail connector">
    In Onyx, go to **Admin Panel → Add Connector** and select **TestRail**.
  </Step>

  <Step title="Create a credential">
    Enter the site URL in **TestRail Base URL**, the user's login in **TestRail Username**,
    and the API key in **TestRail API Key**.

    <img className="rounded-image" src="https://mintcdn.com/danswer/vBRS5zOiPapSrc-h/assets/admins/connectors/testrail/TestRailCredential.png?fit=max&auto=format&n=vBRS5zOiPapSrc-h&q=85&s=0e01cb1d7c17c2da654aaea8ccf36440" alt="Create a TestRail credential with a base URL, username and API key" width="1920" height="1224" data-path="assets/admins/connectors/testrail/TestRailCredential.png" />
  </Step>

  <Step title="Choose the projects">
    Give the connector a name. In **Project IDs**, enter a comma-separated list of TestRail project IDs,
    for example `1,2,3`. Leave it empty to index every project the user can read.
  </Step>

  <Step title="Choose the access type">
    **Public** makes all indexed cases visible to every Onyx user.
    **Private** limits the connector to selected Onyx user groups, and is a paid feature:
    the Business and Enterprise tiers on Onyx Cloud, and the Enterprise Edition when self-hosted.
  </Step>

  <Step title="Connect and verify">
    Select **Create Connector**. Then open **Admin Panel → Existing Connectors**, select the connector,
    and confirm its first indexing attempt completes.
  </Step>
</Steps>

### Advanced settings

| Setting                       | Default | Purpose                                                                                          |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| Cases Page Size               | 250     | How many cases Onyx requests per API call. Lower it if TestRail times out on large projects.     |
| Max Pages                     | 10000   | A stop so a paging loop cannot run forever. Raise it only for a project larger than this allows. |
| Skip Document Character Limit | 200000  | A case whose text is longer than this is skipped rather than indexed. The skip is logged.        |

## Limits

| Limit             | Value             | Notes                                                                 |
| ----------------- | ----------------- | --------------------------------------------------------------------- |
| TestRail API call | 60s               | Set `REQUEST_TIMEOUT_SECONDS` to change it. This is a global setting. |
| Cases per page    | 250               | **Cases Page Size** above.                                            |
| Pages per project | 10000             | **Max Pages** above.                                                  |
| Case text         | 200000 characters | **Skip Document Character Limit** above. A longer case is skipped.    |

The connector indexes no attachments, so it has no file-size cap.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The credentials are rejected">
    `Invalid or expired TestRail credentials (HTTP 401)` means the username or API key is wrong,
    or the key has been revoked. Confirm the username is the user's login and create a new API key.
    Also confirm the API is enabled in TestRail's site settings.
  </Accordion>

  <Accordion title="Permission is denied">
    `Insufficient permissions to access TestRail resources (HTTP 403)` means the user cannot read the projects being
    indexed. Grant it access in TestRail, or narrow **Project IDs** to the projects it can read.
  </Accordion>

  <Accordion title="A project or case is missing">
    Confirm the user can open it in TestRail,
    and that its project ID is in **Project IDs** when that field is not empty.
    A case longer than **Skip Document Character Limit** is skipped and logged; raise the limit to index it.
  </Accordion>

  <Accordion title="Indexing is slow or times out">
    Lower **Cases Page Size** so each API call returns less,
    and raise `REQUEST_TIMEOUT_SECONDS` if TestRail is slow to answer.
  </Accordion>
</AccordionGroup>