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]

# 任意のタイミング: 1つのケースを読み込む
./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オブジェクト
1つのケース	get-case	JSONケースオブジェクト
1つのケースフィールド	get-case-field	スカラー/文字列、または配列/オブジェクトの場合はコンパクトJSON
ケースの前提条件	get-case-precondition	プレーンテキスト / 生のフィールド値

ページネーション

• get_cases、get_runs、get_results* および類似のエンドポイントはページネーションされる場合があります。
• _links.next が空でない限り、.size が安全な総数であると想定しないでください。
• 「ケースはいくつありますか？」という質問には ./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