/testrail

name: "testrail"
description: >-
  Sync tests with TestRail. Use when user mentions "testrail", "test management",
  "test cases", "test run", "sync test cases", "push results to testrail",
  or "import from testrail".

TestRail Integration

Bidirectional sync between Playwright tests and TestRail test management.

Prerequisites

Environment variables must be set:

• `TESTRAIL_URL` — e.g., `https://your-instance.testrail.io`
• `TESTRAIL_USER` — your email
• `TESTRAIL_API_KEY` — API key from TestRail

If not set, inform the user how to configure them and stop.

> **The TestRail MCP server is not auto-registered (issue #978).** `pw-testrail` > was removed from the plugin's `.mcp.json` because it failed to connect for every > user (the plugin ships no `node_modules`). The `testrail_*` MCP tools used below, > and the `/pw:testrail` command, will fail with "tool not found" until it is > enabled manually — see the **Integrations** section of the plugin's `CLAUDE.md` > (`cd integrations/testrail-mcp && npm install`, then register the server in your > own user/project MCP config). Setting the env vars alone is not sufficient.

Capabilities

1. Import Test Cases → Generate Playwright Tests

/pw:testrail import --project <id> --suite <id>

Steps: 1. Call `testrail_get_cases` MCP tool to fetch test cases 2. For each test case:

• Read title, preconditions, steps, expected results
• Map to a Playwright test using appropriate template
• Include TestRail case ID as test annotation: `test.info().annotations.push({ type: 'testrail', description: 'C12345' })`

3. Generate test files grouped by section 4. Report: X cases imported, Y tests generated

2. Push Test Results → TestRail

/pw:testrail push --run <id>

Steps: 1. Run Playwright tests with JSON reporter:

   npx playwright test --reporter=json > test-results.json

2. Parse results: map each test to its TestRail case ID (from annotations) 3. Call `testrail_add_result` MCP tool for each test:

• Pass → status_id: 1
• Fail → status_id: 5, include error message
• Skip → status_id: 2

4. Report: X results pushed, Y passed, Z failed

3. Create Test Run

/pw:testrail run --project <id> --name "Sprint 42 Regression"

Steps: 1. Call `testrail_add_run` MCP tool 2. Include all test case IDs found in Playwright test annotations 3. Return run ID for result pushing

4. Sync Status

/pw:testrail status --project <id>

Steps: 1. Fetch test cases from TestRail 2. Scan local Playwright tests for TestRail annotations 3. Report coverage:

   TestRail cases: 150
   Playwright tests with TestRail IDs: 120
   Unlinked TestRail cases: 30
   Playwright tests without TestRail IDs: 15

5. Update Test Cases in TestRail

/pw:testrail update --case <id>

Steps: 1. Read the Playwright test for this case ID 2. Extract steps and expected results from test code 3. Call `testrail_update_case` MCP tool to update steps

MCP Tools Used

| Tool | When | |---|---| | `testrail_get_projects` | List available projects | | `testrail_get_suites` | List suites in project | | `testrail_get_cases` | Read test cases | | `testrail_add_case` | Create new test case | | `testrail_update_case` | Update existing case | | `testrail_add_run` | Create test run | | `testrail_add_result` | Push individual result | | `testrail_get_results` | Read historical results |

Test Annotation Format

All Playwright tests linked to TestRail include:

test('should login successfully', async ({ page }) => {
  test.info().annotations.push({
    type: 'testrail',
    description: 'C12345',
  });
  // ... test code
});

This annotation is the bridge between Playwright and TestRail.

Output

• Operation summary with counts
• Any errors or unmatched cases
• Link to TestRail run/results