> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hymalaia.com/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, Hymalaia 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 | Hymalaia 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 Hymalaia 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.

## Configure Hymalaia

**1. Open the TestRail connector**

In Hymalaia, go to **Admin Panel → Add Connector** and select **TestRail**.

**2. 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**.

![Create a TestRail credential with a base URL, username and API key](https://mintcdn.com/hymalaia/L7O3OuitqD-U7MiJ/images/connectors/testrail/TestRailCredential.png?fit=max\&auto=format\&n=L7O3OuitqD-U7MiJ\&q=85\&s=12dc544a29bf55f235ae4a8f0fe33d4d)

**3. 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.

**4. Choose the access type**

**Public** makes all indexed cases visible to every Hymalaia user.
**Private** limits the connector to selected Hymalaia user groups, and is a paid feature, available in the Enterprise Edition.

**5. Connect and verify**

Select **Create Connector**. Then open **Admin Panel → Existing Connectors**, select the connector,
and confirm its first indexing attempt completes.

### Advanced settings

| Setting | Default | Purpose |
| - | - | - |
| Cases Page Size | 250 | How many cases Hymalaia 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

> **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.

> **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.

> **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.

> **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.


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