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

# TestRail

> Give agents access to TestRail test management data.

The `@guildai-services/guildai~testrail` package provides agents with read-only access to the TestRail API for test management data.

## Authentication

* **Type:** Basic auth (email + API key)
* **Token expiration:** None — API keys are long-lived
* **Instance URL:** Each TestRail instance has its own base URL

### Setup

<Steps>
  <Step title="Open Credentials">Go to **Credentials** in Guild.</Step>
  <Step title="Connect TestRail">Click **TestRail** and enter your credentials.</Step>
  <Step title="Enter Base URL">Your TestRail instance URL (e.g., `https://company.testrail.io`).</Step>
  <Step title="Enter Email">Your TestRail account email.</Step>
  <Step title="Enter API Key">Found in TestRail under **My Settings > API Keys**.</Step>
</Steps>

No OAuth flow is required — credentials are entered directly.

## Usage

```typescript theme={null}
import { testrailTools } from "@guildai-services/guildai~testrail"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that analyzes TestRail test results",
  tools: { ...testrailTools },
})
```

Tools are named with the `testrail_` prefix — for example, `get_projects` becomes `testrail_get_projects`.

## API endpoints

<AccordionGroup>
  <Accordion title="Projects & suites">
    | Operation      | Method | Path                         |
    | -------------- | ------ | ---------------------------- |
    | `get_projects` | GET    | `/get_projects`              |
    | `get_project`  | GET    | `/get_project/{project_id}`  |
    | `get_suites`   | GET    | `/get_suites/{project_id}`   |
    | `get_suite`    | GET    | `/get_suite/{suite_id}`      |
    | `get_sections` | GET    | `/get_sections/{project_id}` |
    | `get_section`  | GET    | `/get_section/{section_id}`  |
  </Accordion>

  <Accordion title="Test cases">
    | Operation                  | Method | Path                                  |
    | -------------------------- | ------ | ------------------------------------- |
    | `get_cases`                | GET    | `/get_cases/{project_id}`             |
    | `get_case`                 | GET    | `/get_case/{case_id}`                 |
    | `get_attachments_for_case` | GET    | `/get_attachments_for_case/{case_id}` |
    | `get_attachment`           | GET    | `/get_attachment/{attachment_id}`     |
  </Accordion>

  <Accordion title="Test runs & results">
    | Operation              | Method | Path                                       |
    | ---------------------- | ------ | ------------------------------------------ |
    | `get_runs`             | GET    | `/get_runs/{project_id}`                   |
    | `get_run`              | GET    | `/get_run/{run_id}`                        |
    | `get_tests`            | GET    | `/get_tests/{run_id}`                      |
    | `get_test`             | GET    | `/get_test/{test_id}`                      |
    | `get_results`          | GET    | `/get_results/{test_id}`                   |
    | `get_results_for_case` | GET    | `/get_results_for_case/{run_id}/{case_id}` |
  </Accordion>

  <Accordion title="Users">
    | Operation          | Method | Path                |
    | ------------------ | ------ | ------------------- |
    | `get_current_user` | GET    | `/get_current_user` |
    | `get_users`        | GET    | `/get_users`        |
  </Accordion>
</AccordionGroup>

## Webhook events

TestRail does not support webhook triggers in Guild. This integration is API-access only.

## Limitations

* Read-only API operations — no creating or updating test cases, runs, or results
* No webhook or trigger support
* Each TestRail instance requires its own credential entry