testrail

与 TestRail 同步测试。 Use when user mentions "testrail", "test management", "test cases", "test run", "sync test cases", "push results to testrail", 或“从 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.

## 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:
   ```bash
   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:

```typescript
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

---

## 中文说明

# TestRail 集成

在 Playwright 测试与 TestRail 测试管理之间进行双向同步。

## 前置条件

必须设置以下环境变量：
- `TESTRAIL_URL` — 例如 `https://your-instance.testrail.io`
- `TESTRAIL_USER` — 你的邮箱
- `TESTRAIL_API_KEY` — 来自 TestRail 的 API 密钥

如果未设置，请告知用户如何配置它们，然后停止。

## 功能

### 1. 导入测试用例 → 生成 Playwright 测试

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

步骤：
1. 调用 `testrail_get_cases` MCP 工具以获取测试用例
2. 对于每个测试用例：
   - 读取标题、前置条件、步骤、预期结果
   - 使用合适的模板映射为一个 Playwright 测试
   - 将 TestRail 用例 ID 作为测试注解包含进来：`test.info().annotations.push({ type: 'testrail', description: 'C12345' })`
3. 按 section 分组生成测试文件
4. 报告：导入 X 个用例，生成 Y 个测试

### 2. 推送测试结果 → TestRail

```
/pw:testrail push --run <id>
```

步骤：
1. 使用 JSON reporter 运行 Playwright 测试：
   ```bash
   npx playwright test --reporter=json > test-results.json
   ```
2. 解析结果：将每个测试映射到其 TestRail 用例 ID（来自注解）
3. 为每个测试调用 `testrail_add_result` MCP 工具：
   - Pass → status_id: 1
   - Fail → status_id: 5，并包含错误信息
   - Skip → status_id: 2
4. 报告：推送 X 个结果，Y 个通过，Z 个失败

### 3. 创建测试运行

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

步骤：
1. 调用 `testrail_add_run` MCP 工具
2. 包含在 Playwright 测试注解中找到的所有测试用例 ID
3. 返回 run ID 以用于推送结果

### 4. 同步状态

```
/pw:testrail status --project <id>
```

步骤：
1. 从 TestRail 获取测试用例
2. 扫描本地 Playwright 测试中的 TestRail 注解
3. 报告覆盖率：
   ```
   TestRail cases: 150
   Playwright tests with TestRail IDs: 120
   Unlinked TestRail cases: 30
   Playwright tests without TestRail IDs: 15
   ```

### 5. 在 TestRail 中更新测试用例

```
/pw:testrail update --case <id>
```

步骤：
1. 读取此用例 ID 对应的 Playwright 测试
2. 从测试代码中提取步骤和预期结果
3. 调用 `testrail_update_case` MCP 工具以更新步骤

## 使用的 MCP 工具

| 工具 | 何时使用 |
|---|---|
| `testrail_get_projects` | 列出可用项目 |
| `testrail_get_suites` | 列出项目中的套件 |
| `testrail_get_cases` | 读取测试用例 |
| `testrail_add_case` | 创建新的测试用例 |
| `testrail_update_case` | 更新已有用例 |
| `testrail_add_run` | 创建测试运行 |
| `testrail_add_result` | 推送单个结果 |
| `testrail_get_results` | 读取历史结果 |

## 测试注解格式

所有关联到 TestRail 的 Playwright 测试都包含：

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

该注解是 Playwright 与 TestRail 之间的桥梁。

## 输出

- 带计数的操作摘要
- 任何错误或未匹配的用例
- 指向 TestRail run/results 的链接