test-case-management

「ログインをテストする」というテストケースに「正常に動作することを確認する」という期待結果を記載しても、どのレビューにも通ってしまい、何も見つかりません。2 人のテスターが異なる方法で実行し、どちらも失敗したかどうか判断できません。このスキルでは、決定論的なケース（個別の手順、各手順に 1 つの観測可能な期待結果、具体的なテストデータ）を作成し、ナビゲーションしやすいスイートに整理して、TestRail、Xray Cloud、Zephyr Scale、Qase 向けのツールに適した API／CSV ペイロードを出力します。これらのよく似た API は認証方式、エンドポイント、手順フィールド名が異なるため、エージェントが頻繁に取り違えます。

クイックルート

リクエスト	参照先
AC から適切なケースを 1 つ作成する	テストケースの構成
ストーリーからケースを一括生成する	一括作成 + ツールのセクション
「この手順をリンティングする／検証可能ですか？」	曖昧な手順のリンティング + references/linting.md
TestRail／Xray／Zephyr／Qase の API ペイロード	ツールのペイロード + references/tool-apis.md
TestRail にインポートする CSV	references/import-and-traceability.md（CSV セクション）
スイート／セクションを整理する	references/import-and-traceability.md（整理）
要件 ↔ テスト、カバレッジの不足	トレーサビリティ + references/import-and-traceability.md
手動テスト → 自動化の判断	自動化への移行

確認事項

まず、プロジェクトのルートにある .agents/qa-project-context.md でツール、プロジェクトキー、規約を確認し、記載されている項目は質問を省略します。ファイルがない場合は、qa-project-context スキルを使って作成することを提案してください。そのうえで、次の点を確認します。

• 使用するツールはどれですか — TestRail、Xray、Zephyr Scale、Qase？ ツールごとに API の認証方式、エンドポイントの形式、手順フィールド名が異なります。間違えると、401 または 400 が返されるペイロードになります。
• TestRail のみ：単一リポジトリモードですか、それとも複数のスイートを使いますか？ ケースを 1 つのスイート内のセクションに配置するか、別々のスイートに配置するかが変わります。これはすべての section_id と組織計画に影響します。
• Xray／Zephyr のみ：Jira Cloud ですか、それとも Server/DC ですか？ Cloud と Server ではベースパスと認証が異なります。このスキルの対象は Cloud です。Server では異なるエンドポイントを使います。
• ケースのソースは何ですか — 受け入れ条件、ユーザーストーリー、自由形式の機能説明？ これにより、生成するケース数とルールの分割方法が決まります。
• 要件トレーサビリティが必要ですか？ 必要な場合は、Jira／要件の課題キーを今のうちに記録しておくと、後から追加するのではなく、ケースの作成時にリンクできます。

---

基本原則

1. 期待結果は決定論的に確認できる必要があります。 別の人間、または機械が、推測せずに合格／不合格を判断できなければなりません。「動作する」「正しく見える」「問題ない」「少し待つ」は、この基準を満たしません。正確な値、名前と状態を指定した要素、特定のメッセージ、ステータスコード、件数、または時間制限付きの条件を明記してください。

2. 1ステップにつき1つのアサーションにします。 各ステップには、期待結果を1つだけ設定します。1つのステップに3つの確認を詰め込むと、どの確認が失敗したのか、どれを再実行すべきかが曖昧になります。

3. 巨大なテストケースを1つ作るのではなく、ビジネスルールごとに1つのケースを作ります。 「有効なコードで合計金額が下がる／期限切れコードでエラーになる／使用済みコードが拒否される」は、それぞれ独立して合否を判定できる3つのケースです。期待結果を段落に詰め込んだ1つのケースではありません。

4. ツールの API が仕様です。4つのツールを混同しないでください。 TestRail の custom_steps_separated、Qase の Token ヘッダー、Xray の2段階 GraphQL 認証、Zephyr の個別の teststeps 呼び出しは、互いに置き換えられません。該当するツールのセクションからコピーしてください。

5. トレーサビリティは、カバーされていない項目を明らかにするためのものです。 成果物は、ネイティブのカバレッジレポートから得られる、リンクされたテストが0件の要件リストです。陳腐化するスプレッドシートでも、「すべてのテストが何かにリンクされている」状態でもありません。

6. 自動化は量ではなく ROI に基づいて行います。 対応できるリソースが限られているため、安定性が高く、実行頻度の高い回帰テスト／スモークテストから優先して自動化し、探索的テスト、一度限りのテスト、変更頻度が高い、または不安定なテストは手動のままにします。「すべてを自動化する」と、候補として最も適さないものにリソースを浪費します。

---

テストケースの構成

適切に記述された手動テストケースには、5つの要素があります。事前条件またはテストデータが欠けているケースは再現できないため、すべての要素が必須です。

要素	内容	省略した場合の問題
タイトル	機能 — シナリオ — 期待される結果を1行で記述	検索不能、重複
事前条件	テストで前提とする状態（アカウントが存在する、ページ X を表示している、フラグがオンになっている）	テスターがセットアップを推測するため、不安定になる
ステップ	個別の操作を、1ステップにつき1つ記述	再現不能
期待結果	各ステップにつき、観測可能な事後条件を1つ記述	検証不能
テストデータ	使用する具体的な値（コード、メールアドレス、件数、時間）	再現不能

悪い例（曖昧なステップが1つ、検証不能な期待結果、事前条件なし、データなし）：

Title: Login test
Steps: Test the login.
Expected: Verify it works.

良い例 — AC「パスワードを5回間違えると、アカウントが15分間ロックされる」の例：

Title: Login — account locks for 15 minutes after 5 failed attempts
Preconditions: A registered account exists for [email protected]. The user is logged out
               on the /login page. Lockout policy: 5 attempts, 15-minute lockout.
Test Data: email [email protected], wrong password "WrongPass!", correct password "Passw0rd!"
Steps (one assertion per step / single expected result each):
  1. Action:   Submit the login form with [email protected] and "WrongPass!".
     Expected: Error "Invalid email or password." shows; the failed-attempt count is now 1.
  2. Action:   Repeat the wrong-password submit until 5 failed attempts total.
     Expected: On the 5th failure the account is locked; message reads
               "Account locked. Try again in 15 minutes."
  3. Action:   Immediately submit with the CORRECT password "Passw0rd!".
     Expected: Login is still blocked; the same lockout message is shown (lockout overrides
               valid credentials).
  4. Action:   Wait 15 minutes, then submit with the correct password.
     Expected: Login succeeds and the dashboard loads.

注：明示的な事前条件、具体的なテストデータ（5回の試行、15分間のロック）、個別のステップ、およびステップごとに1つの決定論的な期待結果が記載されています。

---

ストーリーからの一括作成

ストーリーまたは一連の受け入れ基準を受け取ったら、ルールごとにケースを分け、その後、ツール固有のペイロードを生成します。割引コードのストーリー（有効なコードで合計金額が下がる／期限切れコードでエラーになる／使用済みコードは拒否される）の例では、ケースは3つです。

1. 有効なコードを適用する → 合計金額が下がる（正常系）。
2. 期限切れの（無効な）コードを適用する → インラインエラーが表示され、合計金額は変わらない。
3. すでに使用済み／引き換え済みのコードを適用する → 拒否され、合計金額は変わらない。

チームがエッジケースのカバレッジを必要とする場合は、ストーリーから明らかに想定されるものの明記されていない否定ケース（空のコード、不正な形式のコード）も追加します。各ケースには個別のステップと、ステップごとに1つの期待結果を設定します。3つすべてのルールを網羅する巨大なケースを1つ作ってはいけません。スプリント全体で何をテストするかという範囲の決定には、このスキルではなく test-planning を使用します。

---

あいまいなステップのリンティング

スイートの「lint」を依頼された場合、あなたの役割は、非決定的なステップを指摘して書き直すことであり、「問題なさそうです」と同意することではありません。同意してしまう失敗モード（「すべて問題なく動作します」と安易に承認すること）を防ぐのが、このセクションの目的です。

期待される結果を決定論的に検証できないステップは不適切です。以下に該当するものはすべて指摘してください。

• あいまいな操作 — 「適当にクリックする」、「X をテストする」、「試してみる」→ 正確な要素と操作を明記します。
• あいまいなデータ — 「いくつかのデータ」、「値」、「何か」→ 具体的なテストデータを示します。
• 観測できない期待結果 — 「すべて問題なく動作する」、「正しく見える」、「問題ない」、「問題がない」→ 観測可能な結果を明記します。
• 上限のない待機 — 「しばらく待つ」、「少し経ってから」→ 「10 秒以内」／「スピナーが消えて行が表示されるまで」のように上限を設けます。
• 1 つのステップに複数のアサーションがある → 1 ステップにつき 1 つのアサーションに分割します。

典型的な不適切な 4 ステップのスイート（「アプリが開く／すべて問題なく動作する／正しく見える／レポートの準備ができる」）では、4 つすべてがあいまいなため、明示的なセレクター、正確な値、上限のある条件を用いて指摘し、書き直す必要があります。「問題は見つかりませんでした」と返してはいけません。リンティングの完全なチェックリスト、この 4 ステップを書き直した例、リンティング出力の表形式については、references/linting.md を参照してください。

---

ツールのペイロード

4 つのツールは取り違えやすいものです。概要は以下のとおりです。curl／GraphQL のリクエストボディ全体については、references/tool-apis.md を参照してください。

| ツール | 認証 | 作成エンドポイント | ステップのフィールド | |------|-----------------|-------------| | TestRail | Basic email:api_key | POST add_case/{section_id} | {content, expected} の配列である custom_steps_separated | | Xray Cloud | POST /api/v2/authenticate → Bearer トークン | /api/v2/graphql の GraphQL createTest | steps[] {action, result}。Gherkin → testType: Cucumber + gherkin | | Zephyr Scale Cloud | Authorization: Bearer <JWT> | POST /v2/testcases の後に POST /v2/testcases/{key}/teststeps | 別個の teststeps 呼び出し。インライン形式は {description, expectedResult, testData} | | Qase | ヘッダー Token: <key> | POST /v1/case/{CODE}/bulk | steps[] {action, expected_result, data} |

リファレンスで説明されている、尊重すべきツール固有の注意点：

• TestRail — ステップを分割する場合は custom_steps_separated を使用します（通常の custom_steps テキストブロックではありません）。エンドポイントは add_case/{section_id} です（実行インスタンスである add_test ではありません）。ベース URL は {instance}/index.php?/api/v2 です。Qase 形式の POST /case は使用しないでください。
• Xray Cloud — まず認証します（client_id／client_secret を指定して /api/v2/authenticate を呼び出し、24 時間有効の Bearer トークンを取得します）。次に、GraphQL の createTest を優先します。Gherkin をインポートする場合は、Generic テストではなく Cucumber テストとしてインポートします。非推奨の Cloud パス /rest/raven/1.0/...、Server 形式の REST、Jira のユーザー名／パスワードによる Basic 認証は避けてください。
• Zephyr Scale Cloud — ベース URL は api.zephyrscale.smartbear.com/v2 で、JWT Bearer を使用します。ステップの追加には、別個の /testcases/{key}/teststeps 呼び出しを使用します。作成リクエストの本文にテキストブロックとして含めてはいけません。/v1/、誤ったホスト、Qase の Token ヘッダーは使用しないでください。
• Qase — 認証には Authorization: Bearer ではなく Token: <key> を使用します。N 回の単独 POST ではなく、cases 配列を含む POST /case/{CODE}/bulk を使用します。TestRail の add_case／custom_steps_separated は使用しないでください。

TestRail 用 CSV インポート（ヘッダー行をインポーターのフィールド Title、Section Hierarchy、Steps (Separated)、Expected Result、Priority、Type、Preconditions に対応付ける方法）については、references/import-and-traceability.md を参照してください。ヘッダー行を含む実際の CSV を使用し、自由形式の文章や単一の Description 列は使用しないでください。また、CSV が指定されている場合に JSON を使用してはいけません。

構成

階層を表すにはセクションとサブセクションを使い、浅く（3～4階層）保ちます。Web とモバイルの製品では、プラットフォームごとにトップレベルのセクション（Web、Mobile (iOS)、Mobile (Android)、Shared / API）を設け、その下に機能のセクションを配置する単一リポジトリモードをデフォルトとします。プラットフォームを別々のチームが担当し、リリースサイクルも異なる場合に限り、複数のスイートに分割します。

避けるべきこと：テストケースごとにフォルダーを作ること、7階層以上の深いネスト、すべてのケースをルートセクションに詰め込むこと、同じケースを複数のスイートに重複して登録すること（信頼できる情報源は一つに保ちます）。単一リポジトリと複数スイートのトレードオフ、および構成に関するすべてのルールについては、references/import-and-traceability.md を参照してください。

---

トレーサビリティ

目的：テストのないストーリー、つまりカバレッジされていない要件を示すカバレッジレポートを作成します。

Jira の Xray の場合：各テストから、要件の Jira 課題キーにネイティブの**「tests」課題リンクを追加します（Test Execution にはリンクしないでください。Test Execution は実行を記録するもので、カバレッジを記録するものではありません）。ストーリー単位のカバレッジは Story の Test Coverage パネルで、プロジェクト全体のカバレッジはトレーサビリティレポート／要件カバレッジレポートで確認します。次に、リンクされたテストが0 件**の要件を絞り込みます。そこが対処すべきギャップです。手動のスプレッドシートだけをトレーサビリティの仕組みとして提案したり、カバレッジされていない要件を無視したりしないでください。Zephyr Scale、Qase、TestRail での同等の機能（課題リンクと、それぞれのカバレッジ／トレーサビリティビュー）については、references/import-and-traceability.md を参照してください。

---

自動化への移行

各手動テストケースの ROI を評価します：value ≈ run_frequency × regression_importance ÷ (automation_cost × expected_maintenance)。キャパシティが限られている場合（例：Zephyr Scale に 400 件のバックログがある場合）は、次のようにします。

• 優先して自動化する： 実行頻度が高く（リリースごと／回帰テスト／スモークテストで実行）、安定していて変更頻度が低く決定論的な機能に対するケースで、重要な回帰テストやスモークテストの経路を守るもの。
• 手動のままにする： 探索的なケースや一度きりのケース、実行頻度の低いケース、変更が続いている UI、高い頻度で不安定になる／非決定論的な動作、人による判断が必要なケース。

「すべて自動化する」や「不安定で頻繁に変更される UI を最初に自動化する」といった方針は避けてください。どちらも、限られたキャパシティを ROI が最も低い候補に費やすことになります。完全な判断ルールについては、references/import-and-traceability.md を参照してください。ケースが自動化対象に移行した後の実際のテストコードは、ここではなく ai-test-generation またはフレームワークスキル（playwright-automation、api-testing）を使って作成します。

---

レビューの品質

• すべてのケースを1画面でレビューできるようにします。タイトルに結果を記載し、事前条件を明示し、ステップを個別に分け、期待結果を観測可能な内容にし、テストデータを具体的にします。
• 新しいケースをマージする前にリンティングのチェックリストを実施し、決定論的でない期待結果は却下します。
• 要件へのリンクは後から追加するのではなく、作成時に設定します。
• 実行時に絞り込めるよう、スイートにタグ（smoke／regression／platform）を付けます。タグのない 400 件のリポジトリは、リリース対象を選ぶ際に使いものになりません。

---

アンチパターン

1. 「動作を確認する」という期待結果を伴う曖昧なステップが1つだけ

「ログインをテストする → 動作を確認する」では実行できません。ステップを個別に分け、それぞれに観測可能な期待結果を1つずつ設定し、事前条件を明示して、具体的なテストデータを使います。

2. リンティングを依頼されたときに、スイートにお墨付きを与える

ステップを「問題なさそうです」と評したり、「すべてが動作する」や「少し待つ」を残したまま軽く言い換えたりするのは、リンティングで検出すべき問題を見逃すことです。検証できない期待結果をすべて指摘し、書き直してください。

3. 4つのツールの API を混同する

Qase で Bearer を使う（Qase では Token を使います）、Qase または Zephyr で add_case／custom_steps_separated を使う、Xray Cloud で /rest/raven/1.0/ を使う、Zephyr Scale Cloud で /v1/ を使う、Zephyr の作成リクエストボディでステップをテキストの塊として渡す。これらはすべて 4xx エラー、または誤ったフィールドへの意図しない書き込みにつながります。該当するツールのセクションを参照してください。

4. 複数のルールを持つストーリーに巨大なケースを1つ作る

「有効／期限切れ／使用済み」を1つのケースにまとめると、1回の合否判定で、どのルールが破綻したのかが分からなくなります。ルールごとにケースを1つ作ってください。

5. 自由形式の文章、または単一の Description 列としての CSV

ヘッダー行がなく、インポーターのフィールドに対応付けられていない TestRail インポートでは、手動での再マッピングが必要です。 Title、Section Hierarchy、Steps (Separated)、Expected Result などを指定してください。

6. 深い階層とケースごとのフォルダー

7 階層以上のツリーやケースごとに 1 つのフォルダーを作る構成では、リポジトリの操作が困難になります。セクションは浅い 3～4 階層に保ち、Web とモバイルの両方を扱う場合は、最上位にプラットフォームを配置してください。

7. 手動のスプレッドシートによるトレーサビリティ

手作業で管理するシートでは、「どのストーリーにテストがないか」という質問に確実に答えられません。ツール標準の要件→テストリンクとカバレッジ／トレーサビリティレポートを使用し、未カバーの要件を明示してください。

8. すべてを自動化する／不安定なものから自動化する

一度限りの探索的テストケースや、変更が頻繁で不安定な UI の自動化を最初に行うと、投資対効果がマイナスになり、リソースを浪費します。安定性が高く、実行頻度の高い回帰テスト／スモークテストから順に進めてください。

---

検証

引き渡す前に、生成した成果物が実際に機能することを、最小のチェックから順に確認してください。

• **自分の出力をリントする：**生成したケースに禁止された期待結果が含まれていないか、grep で確認します — grep -niE "verify it works|looks right|is fine|wait a bit|no problems|everything works" cases.* は何も返してはなりません。該当箇所があれば、それは非決定的な期待結果なので書き直してください。
• **TestRail CSV：**ファイルを開き、Title、Section Hierarchy、Steps (Separated)、Expected Result を含むヘッダー行があることを確認します — head -1 cases.csv で、単一の Description ではなく、これらの列が表示されるはずです。インポートウィザードでドライランを実行してください。ヘッダーが正しければ、ウィザードは手動で再マッピングしなくても列を自動照合します。
• **API ペイロード、実際の POST の前に：**JSON を検証し（jq . payload.json の終了コードが 0）、認証ヘッダーとエンドポイントがツールのペイロードにある対象ツールの記述と一致することを確認します — Qase は Authorization: Bearer ではなく Token:、TestRail は add_test ではなく add_case/{section_id} です。応答に 201／テスト ID が含まれていれば（Zephyr の場合は新しいケースの key を含む 200）、作成が確認できます。401 は認証方式の組み合わせが誤っていることを、400 はステップフィールドが誤っていることを意味します。
• **トレーサビリティ：**ツールのカバレッジ／トレーサビリティレポートを実行し、リンク済みテストが 0 件の要件が表示されることを確認します。「未カバー」列が空ならリンクは正しく登録されています。値が入っている場合は、解消すべきギャップの一覧です。

---

完了条件

• 生成された各ケースに、タイトル、事前条件、個別のステップ、各ステップにつき 1 つの観測可能な期待結果、および具体的なテストデータが含まれていること — 「verify it works」／「looks right」／「wait a bit」といった期待結果は使用しません。
• 複数のルールを含むストーリーからは、すべてを組み合わせた 1 つのケースではなく、ルールごとに 1 つのケースが生成されていること。
• 出力される API ペイロードで、対象ツールに合った認証方式、エンドポイント、ステップフィールド名が使用されていること（TestRail は custom_steps_separated+add_case/{section_id}、Xray は 2 段階認証 + GraphQL createTest、Gherkin には Cucumber、Zephyr は /v2 Bearer + 個別の /teststeps、Qase は Token ヘッダー + /case/{CODE}/bulk）。
• TestRail CSV に、列をインポーターのフィールドに対応付けるヘッダー行（Title、Section Hierarchy、Steps (Separated)、Expected Result）があること。
• リント済みのスイートで、曖昧なステップがすべて指摘され、書き直されていること — 問題の兆候がある場合に「問題なし」としてはなりません。
• トレーサビリティでツール標準の要件→テストリンクと、未カバーの要件を一覧表示するカバレッジレポートを使用していること。
• 自動化への移行で、ROI 順（安定性が高く、実行頻度の高い回帰テスト／スモークテストを優先）のリストが作成され、手動のままにするものが明示されていること。

---

関連スキル

• ai-test-generation — 手動テストケースから自動化されたテストコードを作成する場合に使用します。このスキルの対象は手動／ハイブリッドのケースと、そのインポート用ペイロードまでです。
• test-planning — スプリント／リリースで何をテストするか選定する場合に使用します。このスキルでは、対象範囲が決まった後にケースを作成します。
• exploratory-testing — 手動のままにする一度限り／チャーター形式のケースの作成元です。このスキルで行う自動化への移行判断と併用します。
• qa-project-context — 共通の依存スキルです。ペイロードを生成する前に、このスキルが参照するツール、プロジェクトキー、規約を確認します。

---

参考ファイル（references/ 内）

• tool-apis.md — TestRail / Xray Cloud / Zephyr Scale / Qase の完全なテストケース作成ペイロード （curl + GraphQL）、認証フロー、ツールごとの連携時の落とし穴。
• linting.md — あいまいなステップのリントチェックリスト、よくある4つの不適切なステップの書き換え例、リント出力テーブルの形式。
• import-and-traceability.md — 3件のケース例を含む TestRail CSV の列→フィールドのマッピング、 スイート／セクションの整理ルール、要件トレーサビリティ＋カバレッジギャップレポート、自動化への移行判断ルール。