generate-bat-tests

生成 BAT 测试

从 Mule 应用的源代码生成可运行的 BAT（黑盒 API 测试）BDD 套件，包括 DataWeave .dwl 文件和 bat.yaml 清单，并按质量维度组织测试，最后通过针对线上端点运行套件来验证。

何时使用此技能

当用户提出以下请求时使用此技能：

• “为此 API／应用生成 BAT 测试”
• “为订单服务编写 BAT 套件”
• “针对已部署的端点添加黑盒 API 测试／BDD 测试”
• “创建 Anypoint API Functional Monitoring 测试”
• “扩展现有 BAT 测试，覆盖新增错误情况”
• “API 变更后刷新／修复 BAT 套件”

触发关键词： BAT、BDD、.dwl 测试、黑盒测试、API 功能监控、功能性 API 测试、黑盒 · 生成／编写／添加／扩展／刷新测试 · 针对已部署／运行中／线上端点。

不要将此技能用于 MUnit。 MUnit 在构建时运行、在进程内执行，使用 XML，并通过 XSD 验证——它是使用不同工具、遵循不同工作流的另一类测试。BAT 针对已部署的 HTTP 端点运行，使用 DataWeave，且没有 XSD：正确性的唯一门槛是“能够解析，并且能通过针对运行中应用的测试”。这正是此技能的第 2 阶段。

---

BAT 简介（第 1 阶段前阅读一次）

BAT = 黑盒 API 测试，是 MuleSoft 的 API 功能监控框架。BAT 测试是一个 DataWeave .dwl BDD 文件，它会向已部署的 API 发出真实 HTTP 请求，并断言响应结果。它不会导入或查看 Mule 流——它在进程外运行，采用黑盒方式。一个套件由 tests/*.dwl 文件、bat.yaml 清单、包含环境设置的 config/，以及 run-bat.sh 执行脚本组成。使用 bat CLI 执行套件： bat --config=local。

由于没有 XSD，也没有构建时验证器，以下两点比生成 MUnit 测试时更重要：

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> 类型；列出 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（设置 chmod +x、JDK-17 JAVA_OPTS）和 tests/。可重复执行。	磁盘上的套件骨架
scripts/validate_bat_suite.sh <suite-dir> [--allowlist F]	步骤 9——静态 DSL 检查（导入、describe(...)、不得使用 mustNotBe、不得硬编码 URL／token、状态码须为 Number、bat.yaml 结构、文件与磁盘内容一致性，可选路径允许列表）。发现违规时以状态码 1 退出。	标准错误诊断信息

---

工作流结构（两个阶段）

此工作流分为两个阶段，并由一道严格的用户审批关卡隔开。

• 阶段 1：测试设计（步骤 1–6）。 验证工具链，读取应用的 OpenAPI 契约和 Mule XML（如果存在，也读取现有 BAT 基线）， 按质量维度标记测试清单，呈现清单摘要，并等待用户批准。阶段 1 不会向套件目录写入任何内容——只会写入相对于工作区的 tmp/bat-gen/ 摘要和清单 JSON。
• 阶段 2：生成并运行（步骤 7–11）。 搭建套件框架，编写 .dwl 文件和 bat.yaml，运行静态验证器，针对在线端点运行套件，并且只有在运行成功后才宣布完成。

在明确通过步骤 6 的审批关卡之前，绝不能启动阶段 2。 在清单获得批准之前生成 .dwl 文件，是此结构要防止的影响最大的失误——错误的维度划分或虚构的端点会导致生成 N 个错误的测试文件。

全流程规范（阶段 1 前阅读）

• 仅进行黑盒测试。 测试会调用已部署的 HTTP API。它们绝不会导入 Mule 流、直接读取 Object Store 或断言内部状态。如果用户需要进程内流断言，请使用 MUnit，而不是此技能。
• 端点只能来自源代码。 生成的测试中的每个路径和动词，都必须存在于应用的 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）——每个监听器路径对应的动词、<choice>/<when> 分支、raise-error 到状态码的映射（如果存在）状态机，以及 Authorization 的强制执行方式。
• 运行时上下文对应的 mule-artifact.json。

[BLOCKER] 不要仅根据 OpenAPI 契约生成测试。 契约描述预期行为；流 XML 描述实际行为。两者不一致时，以流 XML 为准，因为它代表已部署端点的实际行为，而 BAT 测试的正是已部署的端点。在报告中注明契约与代码之间的任何不一致。

---

步骤 3：读取现有的 BAT 基线（如果存在）

如果应用已有手写的 BAT 测试套件（通常位于 <app>/bat/ 下，或用户指定的目录中），请阅读它。它是了解团队如何编写 BAT 测试的事实依据——熟悉其惯用写法，确保生成的测试套件风格一致：

• 文件／测试命名风格（kebab-case 文件；双引号包裹的 describe(...) 标题；单引号包裹的 it must '...' 场景）
• 状态初始化模式（var context = HashMap()、execute [ context.set(...) ]、在下一个 URL 中使用 $(context.get(...))）
• 配置布局和 bat.yaml 的结构
• 团队使用的匹配器

如果存在基线，生成的测试套件 MUST 严格包含基线所覆盖的所有行为——不得出现回归。重新输出基线测试（使测试套件可以独立运行），在清单中将其标记为 existing，并且不得更改其语义（可以为保持一致而重命名）。如果不存在基线，请跳过此步骤。

---

步骤 4：起草测试清单

根据源代码（步骤 2）和任何基线（步骤 3），起草清单：每项对应一个拟议测试，并标注一个主要质量维度。使用 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_reason）。没有基线时，所有项均为 new。
• stateful: true 表示测试需要初始化调用和 context（多步测试）。
• 覆盖步骤 2 摘要中的每个端点 × 方法，以及每种 raise-error 类型。小型 API 目标为约 12–20 个测试；不要堆砌冗余变体。

名称采用 kebab-case，并与 .dwl 基名一致。

---

步骤 5：推导端点允许列表

写出规范化的端点允许列表，供 Phase-2 验证器检查生成的路径——每行一个路径，ID 段折叠为 {}：

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

将其保存到 tmp/bat-gen/endpoint-allowlist.txt。根据步骤 2 的 listener_paths[]（加上基础路径）推导，不要根据清单推导——这是对清单的独立检查。

---

步骤 6：展示清单摘要并征求批准

[BLOCKER] 仅在完成步骤 1–5 后展示。 每个清单条目都必须包含一个维度、允许列表中存在的端点，以及预期状态。如果缺少任何一项，或端点不在允许列表中，请在展示前修正——不要用“待定”搪塞。

展示简洁的摘要：

**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：生成并运行

步骤 7：（再次）确认运行时 URL 和 Token

测试套件将针对在线端点运行。在搭建测试框架前，确认 URL 和 bearer token：

• 如果用户提供了 URL/token，请使用它们。
• 如果应用是本地 fixture，默认值为 http://localhost:8082/api/v1 和 Bearer test-token。
• 如果两者都未知，请通过 AskUserQuestion 询问——指向错误 URL 的测试套件会让所有测试因错误的原因而失败。

---

步骤 8：搭建测试套件

创建测试套件骨架（配置、运行器、测试目录）：

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

这会写入 config/default.dwl、config/local.dwl（url/token/env）、run-bat.sh（设置 chmod +x，并包含 JDK-17 的 --add-opens JAVA_OPTS），以及一个空的 tests/。除非传入 --force，否则不会覆盖现有的 config/local.dwl——请保留用户已编辑的 url/token。

根据用户的项目约定选择 <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 — 一个请求，多个断言。
• 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 后，才能继续第 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. 一句话说明测试套件的覆盖范围。
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 — 用于标记和确定清单规模的准确性／稳健性／安全性／覆盖率分类体系。
• references/examples/ — 规范 .dwl 文件（单次调用、身份验证错误、多步骤有状态、JSON 正文／标头）及 bat.yaml 参考文件。