kos322/testrail-skill

TestRail API 技能

通过仓库本地的 Bash 包装器实现直接的 TestRail REST API 集成。

安装

首先克隆仓库：

git clone https://github.com/kos322/testrail-skill.git
cd testrail-skill

配置

设置以下环境变量：

• TESTRAIL_URL
• TESTRAIL_USER
• TESTRAIL_API_KEY

基础 URL：

${TESTRAIL_URL}/index.php?/api/v2

决策树

• 已知 PROJECT_ID + 简单的只读问题： 直接调用对应的封装器。
• 未知 PROJECT_ID： 调用 ./scripts/get_projects.sh。
• 环境/认证/设置问题或首次安装： 调用 ./scripts/doctor.sh。

常见查询

# 已知项目 ID：案例总数
./scripts/count_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# 已知项目 ID：完整案例列表（自动分页）
./scripts/list_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# 已知项目 ID：原始分页案例页面
./scripts/get_cases.sh PROJECT_ID [SECTION_ID] [--suite SUITE_ID]

# 任意时刻：读取单个案例
./scripts/get_case.sh CASE_ID | jq -r .title

# 无需手动解析 JSON 获取单个字段
./scripts/get_case_field.sh CASE_ID FIELD

# 前置条件快捷方式
./scripts/get_case_precondition.sh CASE_ID

# 未知项目 ID：发现可访问的项目
./scripts/get_projects.sh | jq '(.projects // .) | map({id, name})'

# 设置/认证问题：验证环境和访问权限
./scripts/doctor.sh

推荐封装器

• scripts/count_cases.sh — 可靠的案例总数统计
• scripts/list_cases.sh — 自动分页的完整案例列表
• scripts/get_cases.sh — 原始分页案例响应
• scripts/get_case.sh — 单个案例查询
• scripts/get_case_field.sh — 单个字段查询
• scripts/get_case_precondition.sh — 前置条件快捷方式
• scripts/get_projects.sh — 发现可访问的项目
• scripts/doctor.sh — 设置/认证冒烟检查
• scripts/create_run.sh, scripts/add_result*.sh, scripts/close_run.sh — 运行/结果流程
• scripts/get_reference_data.sh — 状态、字段、模板、用户

输出约定

目的	命令	输出
案例总数	count-cases	纯整数
案例列表	list-cases	默认为纯文本：C{id}: {title}
结构化案例列表	list-cases --format json	包含 count 和 cases 的 JSON 对象
单个案例	get-case	JSON 案例对象
单个案例字段	get-case-field	纯标量/字符串，数组/对象返回紧凑 JSON
案例前置条件	get-case-precondition	纯文本 / 原始字段值

分页

• get_cases、get_runs、get_results* 以及类似端点可能支持分页。
• 不要 假设 .size 是安全的总数，除非 _links.next 为空。
• 当问题是“有多少个案例？”时，使用 ./scripts/count_cases.sh。

Windows 支持

• 推荐：Git Bash / WSL。
• 仅 PowerShell 环境：使用 powershell/ 目录中的薄包装器。
• PowerShell 包装器仅启动 bash 脚本，不自行读取 .env 文件。

.\powershell\count-cases.ps1 1
.\powershell\list-cases.ps1 1
.\powershell\list-cases.ps1 1 --format json
.\powershell\get-case.ps1 93
.\powershell\get-case-field.ps1 2 custom_preconds
.\powershell\get-case-precondition.ps1 2
.\powershell\get-cases.ps1 1 10 --suite 1
.\powershell\get-sections.ps1 1 1
.\powershell\get-runs.ps1 1

按需文档

• scripts/README.md — 每个脚本的用法说明
• docs/api-reference.md — 端点说明和请求载荷格式
• docs/troubleshooting.md — 设置和认证失败排查
• docs/agent-guide.md — 针对 AI 代理的执行指南
• docs/maintenance/endpoint-status.md — 维护快照，非运行指南

示例

• examples/workflow_ci.sh
• examples/workflow_plans_milestones.sh
• examples/workflow_attachments.sh

官方 API 文档：https://support.testrail.com/hc/en-us/categories/7076541806228-API-Manual