generate-bat-tests

BAT テストの生成

Mule アプリのソースから、品質の観点ごとに整理した、実行可能な BAT（ブラックボックス API テスト）BDD テストスイート（DataWeave の .dwl ファイルと bat.yaml マニフェスト）を生成し、稼働中のエンドポイントに対して実行して検証します。

このスキルを使用する場面

ユーザーから次のような依頼があった場合に、このスキルを使用します。

• 「この API／アプリの BAT テストを生成して」
• 「orders サービスの BAT テストスイートを書いて」
• 「デプロイ済みエンドポイントに対するブラックボックス API テスト／BDD テストを追加して」
• 「Anypoint API Functional Monitoring のテストを作成して」
• 「新しいエラーケースをカバーするように既存の BAT テストを拡張して」
• 「API の変更後に BAT テストスイートを更新／修正して」

トリガーキーワード： BAT、BDD、.dwl テスト、ブラックボックステスト、API 機能 モニタリング、機能 API テスト、blackbox · テストを生成／作成／追加／拡張／ 更新 · デプロイ済み／実行中／稼働中のエンドポイントに対して。

MUnit にはこのスキルを使用しないでください。 MUnit はビルド時にプロセス内で実行され、XML 形式で、XSD による検証が必要です。BAT とは異なるツールであり、ワークフローも異なります。BAT は デプロイ済みの HTTP エンドポイントに対して実行され、DataWeave で記述され、XSD はありません。正しさを確認する唯一の条件は、「パースできること、かつ実行中のアプリに対してテストが合格すること」です。この条件が、このスキルのフェーズ 2 にあたります。

---

BAT とは（フェーズ 1 の前に一度お読みください）

BAT は Blackbox API Testing（ブラックボックス API テスト）の略で、MuleSoft の API Functional Monitoring フレームワークです。BAT テストは、デプロイ済みの API に対して実際の HTTP リクエストを送信し、レスポンスを検証する DataWeave の .dwl BDD ファイルです。Mule フローをインポートしたり参照したりすることはありません。プロセスの外部で動作するブラックボックステストです。テストスイートは、tests/*.dwl ファイルのディレクトリ、bat.yaml マニフェスト、環境設定を含む config/、および run-bat.sh ランナーで構成されます。テストスイートは bat CLI で実行します。 bat --config=local

XSD もビルド時のバリデーターもないため、MUnit の生成と比べて次の 2 点が重要になります。

1. 作成時の規律 — DSL には、見落としやすい厳密なルールがあります（references/bat-authoring-rules.md を参照）。フェーズ 2 の静的バリデーターで、エンドポイントに対する往復テストに時間をかける前に、機械的に検出できるルールを確認します。
2. 実行が合格条件です — ./run-bat.sh を実行中のアプリに対して実行し、すべてのテストが合格する（または各失敗についてレポートで説明される）までは、テストスイートは「完了」ではありません。これにより、MUnit の XSD／コンパイルによる合格条件を置き換えます。

---

同梱スクリプト

このスキルには scripts/ 配下のスクリプトが含まれています。Bash ツールを使って実行してください。内容をインラインで記述しないでください。<skill-dir> は、「スキルが有効になりました」というメッセージで指定された絶対パス（この SKILL.md を含むディレクトリ）です。すべての呼び出しでこのパスを使用し、相対パスの ../scripts/... を組み立てないでください。

スクリプト	用途	出力
scripts/validate_prerequisites.sh	ステップ 1 — ツールチェーンを検証します（jq、$HOME/.bat/bat にある BAT CLI、Java 17 以降）。検証のみを行います。	tmp/bat-gen-env.json（ok、errors[]、bat_cli、java_version）
scripts/extract_endpoints.sh <app-dir>	ステップ 2 — Mule のソースから <http:listener> のパスと <raise-error> の型を grep で検索し、API 仕様ファイルを一覧表示します。インベントリの基点となります。	tmp/bat-gen/source-digest.json ＋標準出力
scripts/scaffold_suite.sh <suite-dir> [--url U] [--token T] [--force]	ステップ 8 — config/{default,local}.dwl、run-bat.sh（実行権限、JDK 17 用の JAVA_OPTS を設定）、および tests/ を作成します。冪等です。	ディスク上のテストスイートの骨組み
scripts/validate_bat_suite.sh <suite-dir> [--allowlist F]	ステップ 9 — DSL の静的チェック（インポート、describe(...)、mustNotBe がないこと、URL／トークンがハードコードされていないこと、ステータスコードが Number 型であること、bat.yaml の形式、ファイルとディスク上の内容の一致、任意のパス許可リスト）。違反があると 1 で終了します。	stderr の診断メッセージ

---

ワークフローの構成（2 つのフェーズ）

このワークフローは、ユーザーの明示的な承認ゲートで区切られた 2 つのフェーズで構成されます。

• フェーズ 1：テスト設計（ステップ 1～6）。 ツールチェーンを検証し、アプリの OpenAPI コントラクトと Mule XML（存在する場合は既存の BAT ベースラインも）を読み、 品質の観点別にタグ付けしたテスト一覧を作成して、一覧の概要を提示し、 ユーザーの承認を待ちます。フェーズ 1 では、スイートディレクトリには何も書き込みません。 ワークスペース相対の tmp/bat-gen/ ダイジェストと、一覧 JSON のみを書き込みます。
• フェーズ 2：生成と実行（ステップ 7～11）。 スイートのひな形を作成し、 .dwl ファイルと bat.yaml を書き込み、静的バリデーターを実行して、 ライブエンドポイントに対してスイートを実行し、正常に実行できた場合にのみ完了を宣言します。

ステップ 6 の承認ゲートを明示的に通過するまで、フェーズ 2 を開始してはなりません。 一覧が承認される前に .dwl ファイルを生成することは、この構成で防ぐ最も影響の大きい失敗です。 観点の分割を誤ったり、エンドポイントを捏造したりすると、誤ったテストファイルが多数生成されることになります。

ワークフロー全体の原則（フェーズ 1 の前に読むこと）

• ブラックボックステストのみ。 テストはデプロイ済みの HTTP API に対して実行します。 Mule フローをインポートしたり、Object Store を直接読み取ったり、内部状態を検証したりすることはありません。 ユーザーがプロセス内のフロー検証を希望する場合、それはこのスキルではなく MUnit の役割です。
• エンドポイントは必ずソースから取得します。 生成する各テストのパスと HTTP メソッドは、 アプリの Mule <http:listener> 設定と OpenAPI コントラクトの両方に存在しなければなりません。 API 名や学習時の推測からエンドポイントを作り出してはなりません。 ステップ 2 の extract_endpoints.sh ダイジェストを基準とし、フェーズ 2 のバリデーターが --allowlist でこれを強制します。
• ハードコードせず、設定値を使います。 すべてのテストで $(config.url) と config.token を使用します。.dwl ファイル内の http://localhost... や "Bearer ..." のリテラルは不備であり、バリデーターが拒否します。
• 実行結果が合格条件です。 「完了」とは、ライブアプリに対して ./run-bat.sh を 実行し、すべてのテストに合格すること、またはすべての失敗について理由を添えてレポートに記録することを意味します。 実行していないスイートを完了と宣言してはなりません。
• テストに合格させるためにアプリを修正してはなりません。 テストでアプリの実際のバグと思われるものが見つかった場合、 アプリを編集してはなりません。発見した不一致としてレポートに記載し、 アサーションはコードの実際の動作に合わせたうえで、人による確認が必要な不一致として記録します。

---

フェーズ 1：テスト設計

ステップ 1：前提条件の検証

前提条件バリデーターを実行します。これは検証のみを行い、検出内容を tmp/bat-gen-env.json に書き込みます。

bash <skill-dir>/scripts/validate_prerequisites.sh

ゼロ以外の終了コードが返された場合は、停止し、errors 配列をユーザーに提示します （一般的な原因は、BAT CLI がインストールされていないこと、または Java のバージョンが 17 未満であることです）。 実行できないスイートを作成しようとしてはなりません。実行が合格条件であり、実行できないスイートは合格できません。

---

ステップ 2：ソースを読み、エンドポイントの基準を作成する

テスト対象の Mule アプリのディレクトリを特定し、ダイジェストヘルパーを実行して、 実際のソースを基準とする一覧を作成します。

bash <skill-dir>/scripts/extract_endpoints.sh <app-dir>

これにより tmp/bat-gen/source-digest.json が書き込まれ、その内容が出力されます。 内容は、<http:listener> のパス（エンドポイントの許可リスト）、<raise-error> の型 （エラー型のカバレッジ一覧）、API 仕様ファイルのパスです。

次に、ダイジェストを基準として実際のソースを読みます。ダイジェストは読み取りの手がかりになりますが、 ソースの読み取りに代わるものではありません。

• OpenAPI/RAML コントラクト（api_specs[] に記載されたパス）— リクエストとレスポンスの 形式、必須フィールド、列挙値、ステータスコード。
• Mule フロー XML（src/main/mule/*.xml）— リスナーのパスごとの HTTP メソッド、 <choice>/<when> の分岐、raise-error からステータスコードへのマッピング、 存在する場合はステートマシンの動作、Authorization の適用方法。
• 実行環境のコンテキストについては mule-artifact.json を確認します。

[BLOCKER] OpenAPI コントラクトだけを根拠にテストを生成してはなりません。 コントラクトが意図を示すのに対し、フロー XML は動作を示します。両者が食い違う場合、 デプロイ済みエンドポイントの実際の動作を示すのはフロー XML であり、BAT はデプロイ済みのエンドポイントをテストします。 コントラクトとコードの不一致があれば、レポートに記載してください。

---

Step 3: 既存の BAT ベースラインを読む（ある場合）

アプリに手書きの BAT テストスイートがすでにある場合（通常は <app>/bat/ 配下、またはユーザーが指定したディレクトリ）、それを読みます。これはこのチームが BAT テストをどのように記述するかを示す根拠です。生成するスイートに一貫性を持たせるため、記述の慣習を把握します。

• ファイル／テストの命名スタイル（kebab-case のファイル名、ダブルクォートの describe(...) ヘッダー、シングルクォートの it must '...' シナリオ）
• 状態をシードするパターン（var context = HashMap()、execute [ context.set(...) ]、次の URL での $(context.get(...))）
• 設定のレイアウトと bat.yaml の形式
• チームが使用しているマッチャー

ベースラインがある場合、生成するスイートは、ベースラインがカバーする動作の厳密な上位集合でなければなりません。デグレードは禁止です。ベースラインのテストも再出力して（スイート単体で完結するようにするため）、インベントリでは existing としてマークし、意味を変えないでください（命名の一貫性を保つための変更は可能です）。ベースラインがない場合は、このステップをスキップします。

---

Step 4: テストインベントリを作成する

ソース（ステップ 2）とベースライン（ステップ 3、ある場合）を使用して、テストインベントリを作成します。提案するテストごとに 1 エントリを設け、主となる品質ディメンションをタグ付けします。references/quality-dimensions.md の分類を使用してください。

インベントリを tmp/bat-gen/test-inventory.json に書き込みます。形式は次の JSON 配列です。

{
  "name": "post-orders-happy-path",
  "file": "tests/post-orders-happy-path.dwl",
  "dimension": "Accuracy",
  "subdimension": "data-integrity",
  "endpoint": "POST /orders",
  "rationale": "one sentence — why this test is worth running",
  "expected_status": 201,
  "expected_error_code": null,
  "exercises_raise_error_type": null,
  "covers": ["Coverage:endpoint", "Accuracy:data-integrity"],
  "provenance": "new",
  "stateful": false
}

• provenance は existing | new | refined です（ベースラインのテストを改善した場合は refined とし、1 行の refined_reason を追加します）。ベースラインがない場合は、すべて new です。
• stateful: true は、シード呼び出しと context が必要なテスト（複数ステップ）を示します。
• ステップ 2 のダイジェストにあるすべてのエンドポイント × メソッドと、すべての raise-error タイプをカバーします。小規模な API なら約 12～20 件を目安とし、冗長なバリエーションを増やしすぎないでください。

名前は kebab-case とし、.dwl のベース名と一致させます。

---

Step 5: エンドポイントの許可リストを作成する

Phase 2 バリデーターが生成パスを照合する、正規化済みのエンドポイント許可リストを書き込みます。1 行につき 1 パスとし、ID セグメントは {} にまとめます。

/orders
/orders/{}
/orders/{}/confirm
/orders/{}/ship
/orders/{}/cancel

tmp/bat-gen/endpoint-allowlist.txt に保存します。インベントリではなく、ステップ 2 の listener_paths[]（およびベースパス）から導出してください。これはインベントリに対する独立したチェックです。

---

Step 6: インベントリの概要を提示し、承認を得る

[BLOCKER] ステップ 1～5 がすべて完了してからのみ提示してください。 すべてのインベントリエントリにはディメンション、許可リストに存在するエンドポイント、期待されるステータスが必要です。いずれかが不足している場合、またはエンドポイントが許可リストにない場合は、提示前に修正してください。「TBD」でごまかしてはいけません。

簡潔な概要を提示します。

**BAT Test Inventory Summary**

**App under test:** <app dir> · runtime URL <config.url>
**Source read:** <OpenAPI spec path>, <flow XML path(s)>
**Baseline:** <none | N existing tests at <path>>

**Coverage:**
- Endpoints: <M of N listener paths × methods covered>
- raise-error types: <list each type from the digest and the test that triggers it; flag any not covered>
- State transitions: <list, if the app has a state machine>

**Inventory (<count> tests):**
- By dimension: Accuracy <n> · Robustness <n> · Security <n>
- By provenance: existing <n> · new <n> · refined <n>   (omit if no baseline)

**Items flagged for human review:**
- <contract↔code disagreements, suspicious validation, dead branches — or "none">

次に、明示的な承認を求めます。

上記のインベントリを確認してください。スイートを生成して実行しますか（Phase 2）？

• はい。スイートを生成して実行します。
• いいえ。インベントリを変更します。
• いいえ。キャンセルします。

[BLOCKER] ステップ 7 に進む前に、明示的な「はい」を待ってください。 「インベントリを変更する」と回答された場合は、変更内容（カバレッジ、ディメンション、具体的なテスト）を尋ねて、手順を繰り返します。「キャンセル」と回答された場合は、丁寧に終了します。

---

Phase 2: 生成して実行する

Step 7: 実行時 URL とトークンを（再）確認する

スイートは稼働中のエンドポイントに対して実行されます。スキャフォールディングの前に URL とベアラートークンを確認します。

• ユーザーが URL／トークンを指定した場合は、それらを使用します。
• アプリがローカルフィクスチャの場合、既定値は http://localhost:8082/api/v1 と Bearer test-token です。
• どちらも不明な場合は、AskUserQuestion を使って尋ねます。誤った URL を指定したスイートは、すべてのテストが誤った理由で失敗します。

---

Step 8: スイートをスキャフォールディングする

スイートの骨組み（設定、ランナー、テストディレクトリ）を作成します。

bash <skill-dir>/scripts/scaffold_suite.sh <suite-dir> --url "<config.url>" --token "<bearer>"

これにより、config/default.dwl、config/local.dwl（URL／トークン／環境変数）、run-bat.sh（実行権限を付与し、JDK-17 の --add-opens 用 JAVA_OPTS を設定）、空の tests/ が書き込まれます。--force を渡さない限り、既存の config/local.dwl は上書きされません。ユーザーがすでに編集した URL／トークンを尊重してください。

ユーザーのプロジェクトの慣例に従って <suite-dir> を選びます（例：<app>/bat-generated/ またはユーザーが指定したパス）。手書きのベースラインディレクトリには書き込まないでください。

---

ステップ 9：.dwl ファイルと bat.yaml を作成し、検証する

インベントリ内で由来が dropped ではない各項目について、 references/bat-authoring-rules.md のすべてのルールに従って tests/<name>.dwl を作成します。標準的な形式は references/examples/ にあります。内容を確認し、スタイルを合わせてください。

• single-call-happy-path.dwl — 1 つのリクエストと複数のアサーション。
• auth-401.dwl — 否定テスト／エラーコードのテスト。
• multi-step-stateful.dwl — シード呼び出し + context + 依存する呼び出し（インベントリ項目が stateful: true の場合）。
• json-body-and-headers.dwl — パース済み JSON ボディのフィールドと、文字セットを含む Content-Type ヘッダーを検証するテスト（ルール 7b／7c を参照）。

続いて bat.yaml を作成します（スキーマは作成ルール／references/examples/bat.yaml を参照）。 suite.name、各 .dwl ファイルに対応する files: エントリー、および reporters:（HTML + JSON）を含めます。トップレベルの config: キーは指定しないでください。

作成後の最初のツール呼び出しとして、ステップ 5 のエンドポイント許可リストを使って静的バリデーターを実行します。

bash <skill-dir>/scripts/validate_bat_suite.sh <suite-dir> --allowlist tmp/bat-gen/endpoint-allowlist.txt

終了コードが 0 以外の場合は、報告されたファイルを修正してバリデーターを再実行します。終了コードが 0 になるまで、ステップ 10 に進まないでください。バリデーターの実行とスイートの実行は、別々の応答で行ってください。

---

ステップ 10：稼働中のエンドポイントに対してスイートを実行する

これがゲートです。この応答では、唯一のツール呼び出しとして次を実行します。

cd <suite-dir> && ./run-bat.sh

出力を確認します。

• すべてのテストに合格 → ステップ 11 に進みます。
• テストが失敗 → 原因を診断します。
  • BAT-DSL／構文エラー → .dwl を修正し、バリデーターを再実行（ステップ 9）してから、スイートを再実行します。
  • 誤って推測したアサーション（アプリの実際の動作がテストのアサーションと異なる） → デプロイ済みの動作に合わせてアサーションを修正し、その修正をレポートに記載します。
  • 実際のアプリのバグと思われるもの → アプリを修正してはいけません。発見した不一致としてレポートに記載し、実際の動作に合わせてアサーションを設定し、人によるレビュー対象としてマークします。
  • 接続拒否／すべてのテストが 401／404 → ランタイムが停止しているか、URL／トークンが誤っています。ステップ 7 の設定を修正（scaffold_suite.sh --force を再実行するか、config/local.dwl を編集）して再実行します。これはテストの不具合ではありません。

すべてのテストに合格するまで、または残りの失敗がすべて記録されるまで、反復します。失敗を伏せたままスイートを提出しないでください。この応答では ./run-bat.sh だけを実行し、ほかのツール呼び出しを併せて行わないでください。

---

ステップ 11：レポートを作成し、完了を宣言する

**前提条件：**直前の応答で ./run-bat.sh を実行し、その合否出力を取得していること。そうでない場合は、ステップ 10 に戻ってください。

スイートと同じ場所に、短い REPORT.md を作成します。

• ディメンション別および由来別のテスト数。
• カバレッジ表：各 raise-error タイプがテストでカバーされているかどうか、および各エンドポイント × メソッド。
• 実行時の合格率（X/Y）。
• 発見した不一致（契約とコードの相違、アプリのバグの疑い）— 人によるレビュー用。
• まだ失敗しているテストとその理由（解決できず、黙って削除するのではなく、フラグ付けすることにした場合のみ）。

その後、簡潔なメッセージで完了を宣言します。ユーザーはファイルと実行ログを確認できます。次の項目を必ず含めてください。

1. スイートのディレクトリパスとテスト数。
2. スイートが何をカバーしているかを示す 1 文。
3. ライブ実行の合格率。
4. 人によるレビュー用にフラグ付けした事項（または「なし」）。

機能一覧や次の手順を付け加えて冗長にしないでください。

---

クイックリファレンス

# Step 1: validate toolchain (jq, BAT CLI, Java 17+) — validation-only
bash <skill-dir>/scripts/validate_prerequisites.sh

# Step 2: anchor the inventory in the real source
bash <skill-dir>/scripts/extract_endpoints.sh <app-dir>   # → tmp/bat-gen/source-digest.json

# Step 8: scaffold the runnable suite skeleton
bash <skill-dir>/scripts/scaffold_suite.sh <suite-dir> --url "<config.url>" --token "<bearer>"

# Step 9: static DSL validation before spending a live run
bash <skill-dir>/scripts/validate_bat_suite.sh <suite-dir> --allowlist tmp/bat-gen/endpoint-allowlist.txt

# Step 10: the gate — run against the deployed endpoint
cd <suite-dir> && ./run-bat.sh

参考資料

• references/bat-authoring-rules.md — BAT DSL のルール（R1～R10）、bat.yaml スキーマ、設定ファイル、run-bat.sh。.dwl を作成する前に読んでください。
• references/quality-dimensions.md — インベントリのタグ付けと規模設定に使う Accuracy／Robustness／Security／ Coverage の分類体系。
• references/examples/ — 標準的な .dwl ファイル（単一呼び出し、認証エラー、複数ステップのステートフル、JSON ボディ／ヘッダー）と、参考用の bat.yaml。