qa-test-script-generator

QA Test Script Generator — スクリプト生成

CLI 呼び出し規約：このツールキットの CLI は quality-assurance-agent/scripts/qa_agent.py です。 PATH コマンドとして配布されていません——コマンドはあなた（エージェント）が実行し、人が手入力する必要はありません。 作業を始める前に skill ディレクトリを一度解析し、その後のコマンドはすべて python "$QA_AGENT_DIR/scripts/qa_agent.py" <cmd> の形式で記述します：

QA_AGENT_DIR="${QA_AGENT_CLI:-$(dirname "$(find ~/.claude/skills ~/.agents/skills ~/.codex/skills .claude/skills .agents/skills .codex/skills -maxdepth 2 -name SKILL.md -path '*quality-assurance-agent/*' 2>/dev/null | head -1)")}"

実行環境でこの skill ディレクトリがすでに通知されている場合（Claude Code では通知されます）は、そのまま使用し、上記の検索を実行する必要はありません。 コマンド構文の全体は $QA_AGENT_DIR/references/cli-reference.md を参照してください。

あなたの役割

あなたは、テストケースから実行への変換レイヤーです。qa-testcase-designer が生成するのは人が読むテストケースであり、あなたが生成するのは実行段階で実行する task です。 spec-task の記述が不正確だと、後続の実行段階で pass/fail を確実に判定できません。

あなたはタスクを実行せず、pass/fail を付けず、準備完了かどうかも判断しません。実装状態は implemented までとし、実行状態は not-run のままにします。

CLI コマンド

この段階で使用するすべてのコマンドの構文と引数の説明は、メイン skill（quality-assurance-agent）→ CLI コマンドリファレンス → 段階 3を参照してください。ここではコマンド構文を重複して管理しません。

生成レベルの規約

スクリプトレイヤーでは完全なテストピラミッドを採用します（generate-spec-tasks のデフォルト動作）：各テストケースを「ユニット > 統合 > API > E2E」の順に段階的に細分化します。受け入れテストにもユニットテストを含める必要があります（資金計算、状態マシン、検証ロジックなどのホワイトボックス動作をテストします）。どのレイヤーも 0 にしてはいけません。

デフォルトの最小 task 数：P0=8、P1=5、P2=3、P3=1。デフォルト比率は unit 60% / integration 20% / api 15% / e2e 5% です。バックエンドのみの scope（フロントエンド UI なし）では、E2E は自動的にスキップされます。

ワークフロー

1. テストケースを検証する

まず validate-cases を実行し、テストケース自体に schema の問題がないことを確認します。task を生成するのは confirmed 状態のテストケースのみです。

2. spec-task を生成する

まず $QA_AGENT_DIR/references/spec-task-planning.md を読み、spec-task のフィールド契約、カバレッジルール、完了ゲートのルールを確認します。

generate-spec-tasks を実行します。次の点を確認してください：

• 各 task に oracle.ui/api/db/sideEffects/negativeAssertions フィールドがあること
• 各 P0/P1 リスク（risk-analysis.json 由来）が、対応する task の assertions または oracle に含まれていること

3. カバレッジを検証する

coverage-balance --strict を実行します。失敗した場合は、無理に通すのではなく spec-task の計画を修正します。

3.5 スクリプト実装の実在性を検証する（マッピング ≠ 実装）

python "$QA_AGENT_DIR/scripts/qa_agent.py"
assert-script-implementation --spec-tasks .qa-agent/current/test-spec-tasks.json --repo .

ゲート検証：各 targetFile のファイルが存在し、プレースホルダーの stub ではなく、検出可能なテストメソッド数 ≥ そのファイルにマッピングされた task 数であること。

• 1 つの targetFile に 54 個の task がマッピングされていても、@Test メソッドが 7 個しかない場合 → ゲート fail（実装を水増ししています）。
• プレースホルダーの stub スクリプト（echo "BLOCKED"; exit 0）→ ゲート fail（実際には実装されていません）。

4. テストファイルを実装する

spec-task に従って、各テストスクリプトを実装します：

• api レイヤーの task：bash スクリプト（curl + python3 で JSON を解析してアサーション）または JUnit 統合テストクラスを使用し、バックエンド API を直接呼び出します
• integration レイヤーの task：データベースの照合が必要な場合は、スクリプトと MySQL MCP read_query を組み合わせます
• e2e レイヤーの task：spec ファイルのパスは tests/e2e/<module>/<case-id>.spec.ts（@playwright/test 形式）とし、実行コマンドは npx playwright test <targetFile> とします。spec ファイルの内容は Playwright Test Agent（planner → generator）が生成するか、手動で記述します。チームで共有する fixture は tests/e2e/lib/e2e-fixture.js（init-project が自動でデプロイ）にあり、loginAsQA() などの再利用可能な操作を提供します
• 既存テストを再利用する場合：targetFile/testName/command/assertions/oracle/evidence を spec-task に正確にマッピングします

テストスクリプトの共通規約：

• python "$QA_AGENT_DIR/scripts/qa_agent.py"
run-with-env --repo . --script <path> で実行します。環境変数が自動的に読み込まれます
• 引数は --extra KEY=VAL で渡します（パスワードやパスをハードコードしないでください）
• 終了コード 0 = pass、0 以外 = fail
• 各 task の実装後、implementationStatus=implemented に更新し、executionStatus は not-run のままにします

5. spec-task の必須フィールドを記述する

各 task には次のフィールドが必要です：

• sourceCaseId——テストケースへのトレース用
• priority——対応するテストケースと一致させる必要があります（一致しない場合、assert-completion によって除外され、filter 診断が出ます）
• layer——unit / integration / api / e2e
• targetFile——テストファイルのパス
• testName——読みやすいテスト名
• command——コピーして実行できるコマンド
• assertions——テストケースの businessAssertions から導出し、重複を除去します（テンプレートのプレースホルダーは使用しないでください）
• oracle——ui / api / db / sideEffects / negativeAssertions に分類します。各項目は構造化オブジェクト {"type","assertion","sourceRiskId"?,...} であり、文字列ではありません
• traceability——関連する risk ID のリスト
• dataBindings——テストケースの data から導出するスクリプト引数（業務 ID のハードコードは禁止）
• implementationStatus——implemented または not-implemented
• executionStatus——ここでは常に not-run とし、実行段階で変更します

ルートレベルのフィールド：generationProfile（development に固定。完全なピラミッドを意味します）、minSpecsByPriority、targetRatio——coverage-balance はこれらのメタデータを読み取り、比率を自動的に照合します。

oracle の構造化契約

{
  "type": "db",
  "assertion": "t_user.virtual_usd_balance 减少 totalDeducted",
  "sourceRiskId": "RISK-P0-001",
  "tableHint": "t_user"
}

• DB oracle には具体的なクエリオブジェクトと期待値を含める必要があります。「コア状態が一致する」のような一般的な記述は認められません。
• データ完全性のテストケース（確率テーブルの gap 検証など）では、verificationMode: direct-db の task を生成し、oracle.db は空でない状態にする必要があります。
• requiresE2E=true のリスクについては、比率によって e2e が 0 に押し下げられた場合でも、少なくとも 1 つの e2e task を必ず追加生成します。

E2E 层输出约定

统一使用 @playwright/test 格式，通过 Playwright Test Agent（planner → generator）或手写生成 spec 文件。

项	约定
targetFile	tests/e2e/<module>/<case-id>.spec.ts（小写 ID，如 tc-p1-011.spec.ts）
command	npx playwright test <targetFile>
共享 fixture	require('../lib/e2e-fixture')（init-project 自动部署 e2e-fixture.js）
配置来源	config/env.shared（团队共享）→ local/.env（个人密钥）
浏览器驱动	@playwright/test（test()、expect()、page fixture）

E2E fixture（tests/e2e/lib/e2e-fixture.js）由 init-project 首次部署，提供 loginAsQA()、getTestValue() 等可复用操作。团队后续可一起维护此 fixture。

容错与降级

• 上游产物缺失：test-cases.json 不存在或未确认时，退回 qa-testcase-designer 阶段，不生成 task。
• 用例 schema 校验失败：validate-cases 不通过 → 退回修正，不强行生成 spec-task。
• coverage-balance 失败：修 spec-task 计划而非强行通过门禁。
• 编码损坏：test-spec-tasks.json 写完必须跑 check-mojibake --strict。U+FFFD → safe-write-json 重写。
• 测试文件写入冲突：路径已存在且有内容时，先读已有文件，做增量合并而非盲目覆盖。

禁令

• 不标记 task 为 passed/failed。执行才能做这件事。
• 不为了好过 completion 而减少 task 数量。
• 不绕过 P0/P1 最小 task 数约束和风险衍生的 oracle 要求。
• 不把已有测试套件的整体通过等同于 spec-task 映射。必须有精确的文件/命令/断言映射。
• 不创建过量 E2E task，除非 scope 明确配置了 E2E 覆盖。保持 unit > integration > api > e2e 倒金字塔。
• 不能因为"生成完了"就说工作完成。你的工作在上游用例确认后才开始，到 spec-task 和测试文件落地才结束。完成判断不在你这里。
• 禁止生成占位 stub 脚本。任何脚本不得以 echo "BLOCKED: ..."; exit 0 形式存在。如果数据准备确实无法自动化（需破坏性 DB 操作等），应在 test-spec-tasks.json 中将 task 标记为 blocked，写清楚 blocker/owner/nextAction；不要用一个假脚本掩盖阻塞状态。

DB 断言固化与 MCP 数据准备规范

DB 断言不得「外包」给执行 runner 手工核对——必须固化为可执行的结构化校验。bash 脚本无法直接调用 MySQL MCP（MCP 是 Claude 的工具而非 shell 命令），因此分两类：

数据完整性用例（direct-db）

对「数据完整性」类用例（如概率表 gap 校验），生成 verificationMode: direct-db 的 task，oracle.db 必含「具体 SQL + 期望值」，由 runner 逐条执行并记录结果，不作为自由手工核对项。

{
  "verificationMode": "direct-db",
  "oracle": {
    "db": [
      {
        "type": "db",
        "assertion": "每个概率表首条 outcome_from=0，末条 outcome_to=1",
        "query": "SELECT product_id, MIN(outcome_from) f, MAX(outcome_to) t FROM t_product_prize GROUP BY product_id",
        "expect": "f=0 且 t=1.0",
        "sourceRiskId": "RISK-P1-005"
      }
    ]
  }
}

API 调用类用例（数据准备 PRE/POST）

脚本包含完整 API 调用 + 断言逻辑；数据准备用注释标注，由 runner 通过 MCP 在脚本前后完成。数据准备是输入准备，DB 断言仍必须进 oracle.db 结构化字段。

#!/usr/bin/env bash
# Test: TC-P2-032 - Exchange软删除
# MCP 数据准备（执行 runner 在脚本前后完成）：
#   PRE:  mcp__mysql_mcp__write_query "UPDATE t_user_open_record SET is_deleted=1 WHERE id=<PENDING_ID>"
#   POST: mcp__mysql_mcp__write_query "UPDATE t_user_open_record SET is_deleted=0 WHERE id=<SAME_ID>"
set -u
# ... login, API call, assertions ...

错误模式（禁止）

#!/usr/bin/env bash
echo "BLOCKED: Requires data preparation"
exit 0  # ← 永远禁止！这是在伪造"执行过"

执行 runner 的职责

qa-test-runner 遇到 verificationMode: direct-db 的 task 或标注 PRE:/POST: 的脚本时：

1. 通过 MySQL MCP 执行 PRE 数据准备
2. 运行脚本（API 调用 + 断言）
3. 通过 MCP 执行 oracle.db 逐条校验，记录「查询摘要 + 期望 + 实际 + 状态」到 evidence
4. 通过 MCP 执行 POST 数据还原
5. 所有 MCP 操作失败也记录在 evidence 中；oracle.db 为空视为 spec-task 未完成，不得进入执行阶段