Query TestRail test runs and results from Guild agents

Integrations · TestRail

A Guild agent reads your TestRail projects, test runs, cases, and results using your instance credentials. Guild stores those credentials server-side and injects them into every request, so agent code never sees them. Credential policies let you restrict which operations each agent may call, and every request is logged for audit.

Book a demo

See how teams govern agents that use TestRail.

Start free

Connect TestRail and scope your first agent.

What the TestRail integration exposes

The integration provides read-only tools that cover projects, test suites, sections, cases, runs, tests, results, attachments, and users. Tools follow the testrail_ prefix convention, so get_projects is called as testrail_get_projects. All operations are GET-style reads; the integration does not create or update any TestRail data. Each TestRail instance requires its own credential entry in Guild.

How it works

Open Credentials in Guild

Go to Credentials in Guild and click TestRail. Credentials are entered directly; no OAuth flow is required.

Enter your instance details

Provide your TestRail instance URL, your account email, and an API key from My Settings > API Keys in TestRail. API keys are long-lived and do not expire.

Spread tools into your agent

Import testrailTools from @guildai-services/guildai~testrail and spread it into your agent’s tools object. Guild resolves and injects the credential server-side at runtime.

Why TestRail access needs governing

TestRail holds your organisation’s full test history, case libraries, and QA coverage data. Guild stores the API key in its credential store and injects it through the credential proxy, so the key never appears in agent code, prompts, or container state. You can scope a credential to a single workspace, a single member, or a single agent, so each agent resolves exactly the credential you intend. On top of scoping, credential policies let you write ALLOW and DENY rules that the proxy enforces before any request leaves Guild. A DENY rule always wins over an ALLOW rule, and a request that no rule allows is denied by default once you remove the auto-created allow-all policy. Because the TestRail integration is read-only by design, policies here are about limiting which projects or runs a given agent can see, not about blocking writes that do not exist.

About the TestRail integration

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

Open Credentials

Go to Credentials in Guild.

Connect TestRail

Click TestRail and enter your credentials.

Enter Base URL

Your TestRail instance URL (e.g., https://company.testrail.io).

Enter Email

Your TestRail account email.

Enter API Key

Found in TestRail under My Settings > API Keys.

No OAuth flow is required — credentials are entered directly.

Usage

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.

Tools

Tools in the latest published version of guildai~testrail:

Tool	What it does
`testrail_get_attachment`	Downloads an attachment by ID.
`testrail_get_attachments_for_case`	Returns the list of attachments for a test case.
`testrail_get_case`	Returns an existing test case by ID.
`testrail_get_cases`	Returns the list of test cases for a project.
`testrail_get_current_user`	Returns the current user.
`testrail_get_project`	Returns an existing project by ID.
`testrail_get_projects`	Returns the list of available projects.
`testrail_get_results`	Returns the list of test results for a test.
`testrail_get_results_for_case`	Returns the list of test results for a test case within a specific run.
`testrail_get_run`	Returns an existing test run by ID.
`testrail_get_runs`	Returns the list of test runs for a project.
`testrail_get_section`	Returns an existing section by ID.
`testrail_get_sections`	Returns the list of sections for a project and test suite.
`testrail_get_suite`	Returns an existing test suite by ID.
`testrail_get_suites`	Returns the list of test suites for a project.
`testrail_get_test`	Returns an existing test by ID.
`testrail_get_tests`	Returns the list of tests in a test run.
`testrail_get_users`	Returns the list of users.

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

Frequently asked questions

Can a Guild agent create or update test cases and runs in TestRail?

No. The integration exposes read-only operations only. No tools exist for creating or updating test cases, runs, or results.

Does TestRail trigger Guild agents automatically when a run finishes?

Not yet. TestRail does not support webhook triggers in Guild. The integration is API-access only, so agents must be invoked directly rather than in response to TestRail events.

How does Guild keep my TestRail API key secure?

Guild stores the key server-side and adds it to requests through its credential proxy. The key never enters agent code, the agent container, or the model prompt. You can read more about this on the credentials page.

Can I connect separate TestRail credentials for different workspaces?

Yes. Each TestRail instance requires its own credential entry, and Guild lets you scope a credential to a single workspace so agents in other workspaces use a different one. See Service credentials for scoping options.

Put a governed agent on TestRail this week

Book a demo

See how teams govern agents that use TestRail.

Start free

Connect TestRail and scope your first agent.

Also runs on Guild: Cypress Read: Docs: Credential policies · Credentials · Tools in agents

Overview

Models

Inference providers

Code & CI/CD

Communication

Project management

Testing

Productivity

Monitoring & observability

Data

Customer support

Sales & finance

Recruiting

Query TestRail test runs and results from Guild agents

Book a demo

Start free

What the TestRail integration exposes

How it works

Why TestRail access needs governing

About the TestRail integration

Authentication

Setup

Usage

Tools

Webhook events

Limitations

Frequently asked questions

Put a governed agent on TestRail this week

Book a demo

Start free

Book a demo

Start free

​What the TestRail integration exposes

​How it works

​Why TestRail access needs governing

​About the TestRail integration

​Authentication

​Setup

​Usage

​Tools

​Webhook events

​Limitations

​Frequently asked questions

​Put a governed agent on TestRail this week

Book a demo

Start free

​Related

What the TestRail integration exposes

How it works

Why TestRail access needs governing

About the TestRail integration

Authentication

Setup

Usage

Tools

Webhook events

Limitations

Frequently asked questions

Put a governed agent on TestRail this week

Related