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	JSON 物件，包含 count 和 cases
單一案例	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 — 代理專用的執行指引
• 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