generate-bat-tests

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Generate BAT Tests

生成BAT测试

Generate a runnable BAT (Blackbox API Testing) BDD suite — DataWeave

.dwl

files plus a

bat.yaml

manifest — from a Mule app's source, organized by quality dimensions, and validated by running it against the live endpoint.

生成可运行的BAT（Blackbox API Testing）BDD测试套件——包含DataWeave

.dwl

文件以及

bat.yaml

清单——基于Mule应用源码，按质量维度组织，并通过针对实时端点运行来验证。

When to Use This Skill

何时使用此技能

Use this skill when users request:

"Generate BAT tests for this API / app"
"Write a BAT suite for the orders service"
"Add black-box API tests / BDD tests against the deployed endpoint"
"Create Anypoint API Functional Monitoring tests"
"Extend the existing BAT tests to cover the new error cases"
"Refresh / fix the BAT suite after the API changed"

Trigger keywords: BAT, BDD,

.dwl

test, black-box test, API functional monitoring, functional API test, blackbox · generate / write / add / extend / refresh tests · against the deployed / running / live endpoint.

Do NOT use this skill for MUnit. MUnit is build-time, in-process, XML, and XSD-validated — a different tool with a different workflow. BAT runs against a deployed HTTP endpoint, is DataWeave, and has no XSD: the only gate on correctness is "it parses AND it passes against the running app". That gate is this skill's Phase 2.

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

"为该API/应用生成BAT测试"
"为订单服务编写BAT测试套件"
"针对已部署端点添加黑盒API测试/BDD测试"
"创建Anypoint API Functional Monitoring测试"
"扩展现有BAT测试以覆盖新的错误场景"
"API变更后刷新/修复BAT测试套件"

触发关键词： BAT、BDD、

.dwl

测试、黑盒测试、API functional monitoring、功能API测试、blackbox · 生成/编写/添加/扩展/刷新测试 · 针对已部署/运行/实时端点。

请勿将此技能用于MUnit。 MUnit是构建时、进程内、基于XML和XSD验证的工具——与BAT属于不同工具，工作流也不同。BAT针对已部署的HTTP端点运行，基于DataWeave，且无XSD验证：判断测试正确性的唯一标准是“可解析且针对运行中的应用执行通过”。这也是本技能第二阶段的核心验证环节。

What BAT is (read once before Phase 1)

BAT是什么（进入第一阶段前请阅读）

BAT = Blackbox API Testing, MuleSoft's API Functional Monitoring framework. A BAT test is a DataWeave

.dwl

BDD file that issues real HTTP requests against a deployed API and asserts on the responses. It does not import or see the Mule flows — it is out-of-process and black-box. A suite is a directory of

tests/*.dwl

files, a

bat.yaml

manifest, a

config/

with environment settings, and a

run-bat.sh

runner. The suite is executed with the

bat

CLI:

bat --config=local

Because there is no XSD and no build-time validator, two things matter more than in MUnit generation:

Authoring discipline — the DSL has exact, easy-to-miss rules (see
```
references/bat-authoring-rules.md
```
). The Phase-2 static validator catches the mechanical ones before you spend a round-trip against the endpoint.
The run is the gate — a suite is not "done" until
```
./run-bat.sh
```
has been executed against the live app and every test passes (or each failure is explained in the report). This replaces MUnit's XSD/compile gate.

BAT = Blackbox API Testing，是MuleSoft的API功能监控框架。BAT测试是一个DataWeave

.dwl

格式的BDD文件，会向已部署的API发送真实HTTP请求并验证响应。它不会导入或查看Mule流——属于进程外的黑盒测试。一个测试套件包含

tests/*.dwl

文件目录、

bat.yaml

清单、存放环境设置的

config/

目录，以及

run-bat.sh

运行脚本。套件通过

bat

CLI执行：

bat --config=local

。

由于没有XSD验证和构建时校验工具，相比MUnit生成，以下两点更为重要：

编写规范——DSL有严格且容易遗漏的规则（详见
```
references/bat-authoring-rules.md
```
）。第二阶段的静态验证器会在你花费时间与端点交互前，先捕获这些机械性错误。
运行即验证——只有当
```
./run-bat.sh
```
针对运行中的应用执行且所有测试通过（或每个失败都在报告中说明原因）时，套件才算“完成”。这替代了MUnit的XSD/编译验证环节。

Bundled scripts

捆绑脚本

This skill ships scripts under

scripts/

. Invoke them with the

Bash

tool — do not inline their contents.

<skill-dir>

is the absolute path you were given in the "skill is now active" message (the directory containing this

SKILL.md

). Use it for every invocation; do not construct relative

../scripts/...

paths.

Script	Purpose	Output
`scripts/validate_prerequisites.sh`	Step 1 — validate toolchain (jq, BAT CLI at `$HOME/.bat/bat` , Java 17+). Validation-ONLY.	`tmp/bat-gen-env.json` ( `ok` , `errors[]` , `bat_cli` , `java_version` )
`scripts/extract_endpoints.sh <app-dir>`	Step 2 — grep the Mule source for `<http:listener>` paths and `<raise-error>` types; list API spec files. Anchors the inventory.	`tmp/bat-gen/source-digest.json` + stdout
`scripts/scaffold_suite.sh <suite-dir> [--url U] [--token T] [--force]`	Step 8 — create `config/{default,local}.dwl` , `run-bat.sh` (chmod +x, JDK-17 `JAVA_OPTS` ), and `tests/` . Idempotent.	suite skeleton on disk
`scripts/validate_bat_suite.sh <suite-dir> [--allowlist F]`	Step 9 — static DSL checks (imports, `describe(...)` , no `mustNotBe` , no hardcoded URL/token, Number status codes, `bat.yaml` shape, files↔disk parity, optional path allowlist). Exits 1 on violations.	stderr diagnostics

此技能在

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` （添加可执行权限，配置JDK-17的 `JAVA_OPTS` ）和 `tests/` 目录。支持幂等操作。	磁盘上的套件骨架
`scripts/validate_bat_suite.sh <suite-dir> [--allowlist F]`	步骤9——静态DSL检查（导入语句、 `describe(...)` 、禁止 `mustNotBe` 、禁止硬编码URL/令牌、数字状态码、 `bat.yaml` 格式、文件与磁盘一致性、可选路径白名单）。违反规则时退出码为1。	标准错误输出的诊断信息

Workflow shape (two phases)

工作流结构（两个阶段）

This workflow has two phases separated by a hard user-approval gate.

Phase 1: Test Design (Steps 1–6). Validate the toolchain, read the app's OpenAPI contract and Mule XML (and, if present, an existing BAT baseline), build a test inventory tagged by quality dimension, present an Inventory Summary, and wait for the user to approve. Phase 1 writes nothing into the suite directory — only the workspace-relative
```
tmp/bat-gen/
```
digest and the inventory JSON.
Phase 2: Generate & Run (Steps 7–11). Scaffold the suite, write the
```
.dwl
```
files +
```
bat.yaml
```
, run the static validator, run the suite against the live endpoint, and declare completion only after a clean run.

Phase 2 MUST NOT start until Step 6's approval gate has been passed explicitly. Generating

.dwl

files before the inventory is approved is the highest-impact failure mode this structure prevents — a wrong dimension split or a fabricated endpoint becomes N wrong test files.

此工作流分为两个阶段，中间有严格的用户审批环节。

第一阶段：测试设计（步骤1–6）。验证工具链，读取应用的OpenAPI契约和Mule XML（以及现有BAT基线，如果存在），构建按质量维度标记的测试清单，呈现清单摘要，等待用户审批。第一阶段不会向套件目录写入任何内容——仅会在工作区相对路径
```
tmp/bat-gen/
```
下生成摘要文件和清单JSON。
第二阶段：生成与运行（步骤7–11）。搭建套件骨架，编写
```
.dwl
```
文件 +
```
bat.yaml
```
，运行静态验证器，针对实时端点运行套件，仅在全部运行通过后才宣告完成。

必须在通过步骤6的审批环节后，才能启动第二阶段。在清单获得批准前生成

.dwl

文件是此结构要避免的最高影响故障模式——错误的维度划分或虚构的端点会导致大量错误的测试文件。

Workflow-wide discipline (read before Phase 1)

全工作流规范（进入第一阶段前请阅读）

Black-box only. Tests hit the deployed HTTP API. They never import Mule flows, read the Object Store directly, or assert on internal state. If the user wants in-process flow assertions, that is MUnit, not this skill.
Endpoints come ONLY from the source. Every path + verb in a generated test must exist in the app's Mule
```
<http:listener>
```
configuration and OpenAPI contract. Never invent an endpoint from the API's name or from training-time intuition. Step 2's
```
extract_endpoints.sh
```
digest is the anchor; the Phase-2 validator enforces it via
```
--allowlist
```
.
Config interpolation, never hardcoding. Every test uses
```
$(config.url)
```
and
```
config.token
```
. A literal
```
http://localhost...
```
or
```
"Bearer ..."
```
in a
```
.dwl
```
file is a defect — the validator rejects it.
The run is the gate. "Done" means
```
./run-bat.sh
```
ran against the live app and every test passed, OR every failure is documented in the report with reasoning. Never declare completion off an unrun suite.
Don't fix the app to make a test pass. If a test reveals what looks like a real bug in the app, do NOT edit the app. Flag it in the report as a discovered discrepancy and make the assertion match what the code actually does, noting the discrepancy for human review.

仅黑盒测试。测试仅访问已部署的HTTP API。绝不导入Mule流、直接读取对象存储或断言内部状态。如果用户需要进程内流断言，请使用MUnit，而非此技能。
端点仅来自源码。生成测试中的每个路径+方法必须存在于应用的Mule
```
<http:listener>
```
配置和OpenAPI契约中。绝不要根据API名称或训练时的直觉凭空创建端点。步骤2的
```
extract_endpoints.sh
```
摘要是基础；第二阶段的验证器会通过
```
--allowlist
```
参数强制执行此规则。
配置插值，禁止硬编码。每个测试都使用
```
$(config.url)
```
和
```
config.token
```
。
```
.dwl
```
文件中出现字面量
```
http://localhost...
```
或
```
"Bearer ..."
```
属于缺陷——验证器会拒绝此类文件。
运行即验证。“完成”意味着
```
./run-bat.sh
```
针对运行中的应用执行且所有测试通过，或每个失败都在报告中记录并说明原因。绝不能基于未运行的套件宣告完成。
不要为通过测试修改应用。如果测试发现应用中存在疑似真实bug，请勿编辑应用。在报告中标记为已发现的差异，并调整断言使其匹配代码的实际行为，同时注明该差异需人工审核。

Phase 1: Test Design

第一阶段：测试设计

Step 1: Validate Prerequisites

步骤1：验证先决条件

Run the prerequisite validator. It only validates; it writes findings to

tmp/bat-gen-env.json

bash

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

If it exits non-zero, STOP and surface the

errors

array to the user (most commonly: BAT CLI not installed, or Java < 17). Do not attempt to author a suite you cannot run — the run is the gate, and an unrunnable suite cannot pass it.

运行先决条件验证器。它仅做验证；将结果写入

tmp/bat-gen-env.json

。

bash

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

如果退出码非零，请停止操作并向用户展示

errors

数组内容（最常见的情况：未安装BAT CLI，或Java版本低于17）。请勿尝试编写无法运行的套件——运行是验证的核心，无法运行的套件无法通过验证。

Step 2: Read the Source and Build the Endpoint Anchor

步骤2：读取源码并构建端点基础

Identify the Mule app directory under test, then run the digest helper to anchor the inventory in the real source:

bash

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

This writes

tmp/bat-gen/source-digest.json

and echoes it: the

<http:listener>

paths (the endpoint allowlist), the

<raise-error>

types (the error-type coverage list), and the API spec file paths.

Then read the actual source — the digest anchors you but does not replace reading:

The OpenAPI/RAML contract (paths from
```
api_specs[]
```
) — request/response shapes, required fields, enums, status codes.
The Mule flow XML (
```
src/main/mule/*.xml
```
) — verbs per listener path,
```
<choice>/<when>
```
branches,
```
raise-error
```
mappings to status codes, the state machine if there is one, and how
```
Authorization
```
is enforced.
```
mule-artifact.json
```
for the runtime context.

[BLOCKER] Do not generate tests from the OpenAPI contract alone. The contract states intent; the flow XML states behavior. Where they disagree, the flow XML is what the deployed endpoint actually does, and BAT tests the deployed endpoint. Note any contract↔code disagreements for the report.

确定被测Mule应用的目录，然后运行摘要辅助工具，基于真实源码为测试清单提供基础：

bash

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
```
——运行时上下文信息。

[阻塞点] 请勿仅基于OpenAPI契约生成测试。 契约描述的是预期，而流XML描述的是实际行为。当两者不一致时，流XML才是已部署端点的实际行为，而BAT测试的是已部署端点。请在报告中记录任何契约与代码的不一致之处。

Step 3: Read the Existing BAT Baseline (if one exists)

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

If the app already has a hand-written BAT suite (commonly under

<app>/bat/

or a directory the user names), read it. It is ground truth for how this team writes BAT tests — absorb its idioms so the generated suite is consistent:

file/test naming style (kebab-case files; double-quoted
```
describe(...)
```
headers; single-quoted
```
it must '...'
```
scenarios)

the state-seeding pattern (

var context = HashMap()

execute [ context.set(...) ]

$(context.get(...))

in the next URL)

config layout and
```
bat.yaml
```
shape
which matchers the team uses

When a baseline exists, the generated suite MUST be a strict superset of the behaviors the baseline covers — no regressions. Re-emit baseline tests (so the suite stands alone), mark them

existing

in the inventory, and do not change their semantics (you may rename for consistency). If no baseline exists, skip this step.

如果应用已有手写的BAT测试套件（通常位于

<app>/bat/

或用户指定的目录），请读取它。它是团队编写BAT测试的基准——吸收其惯用写法，使生成的套件保持一致：

文件/测试命名风格（短横线分隔文件名；双引号包裹的
```
describe(...)
```
标题；单引号包裹的
```
it must '...'
```
场景）

状态初始化模式（

var context = HashMap()

、

execute [ context.set(...) ]

、下一个URL中使用

$(context.get(...))

）

配置布局和
```
bat.yaml
```
格式
团队使用的匹配器类型

当存在基线时，生成的套件必须是基线覆盖行为的严格超集——不能出现回归。重新生成基线测试（使套件独立存在），在清单中标记为

existing

，且不要更改其语义（可重命名以保持一致性）。如果没有基线，请跳过此步骤。

Step 4: Draft the Test Inventory

步骤4：草拟测试清单

Using the source (Step 2) and any baseline (Step 3), draft the inventory: one entry per proposed test, tagged with a primary quality dimension. Use the taxonomy in

references/quality-dimensions.md

Write the inventory to

tmp/bat-gen/test-inventory.json

— a JSON array of:

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
```
is
```
existing
```
|
```
new
```
|
```
refined
```
(when a baseline test is improved — add a one-line
```
refined_reason
```
). When there is no baseline, everything is
```
new
```
.
```
stateful: true
```
marks tests that need a seed call +
```
context
```
(multi-step).
Cover every endpoint × method and every
```
raise-error
```
type from the Step-2 digest. Aim for ~12–20 tests for a small API; don't bloat with redundant variants.

Names are kebab-case and match the

.dwl

basename.

基于源码（步骤2）和任何现有基线（步骤3），草拟测试清单：每个拟议测试对应一个条目，标记主要质量维度。使用

references/quality-dimensions.md

中的分类体系。

将清单写入

tmp/bat-gen/test-inventory.json

——一个JSON数组，每个条目格式如下：

json

{
  "name": "post-orders-happy-path",
  "file": "tests/post-orders-happy-path.dwl",
  "dimension": "Accuracy",
  "subdimension": "data-integrity",
  "endpoint": "POST /orders",
  "rationale": "一句话说明——为什么值得运行此测试",
  "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个测试；避免冗余变体导致套件臃肿。

名称使用短横线分隔格式，与

.dwl

文件的基础名一致。

Step 5: Derive the Endpoint Allowlist

步骤5：生成端点白名单

Write the normalized endpoint allowlist the Phase-2 validator will check generated paths against — one path per line, with id segments collapsed to

{}

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

Save it to

tmp/bat-gen/endpoint-allowlist.txt

. Derive it from the Step-2

listener_paths[]

(plus base path), NOT from the inventory — it is the independent check on the inventory.

生成第二阶段验证器将用于检查生成路径的标准化端点白名单——每行一个路径，将ID段替换为

{}

：

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

保存到

tmp/bat-gen/endpoint-allowlist.txt

。基于步骤2的

listener_paths[]

（加上基础路径）生成，而非基于测试清单——它是对清单的独立校验。

Step 6: Present the Inventory Summary and Get Approval

步骤6：呈现清单摘要并获取审批

[BLOCKER] Present ONLY after Steps 1–5 are complete. Every inventory entry must have a dimension, an endpoint that exists in the allowlist, and an expected status. If any is missing or an endpoint is not in the allowlist, fix it before presenting — do not paper over with "TBD".

Present a concise summary:

**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">

Then ask for explicit approval:

Review the inventory above. Proceed to generate and run the suite (Phase 2)?

Yes, generate and run the suite.

No, I want to change the inventory.

No, cancel.

[BLOCKER] WAIT for explicit "Yes" before Step 7. On "change the inventory", ask what to change (coverage, dimensions, specific tests) and loop back. On "cancel", stop politely.

[阻塞点] 仅在步骤1–5完成后呈现。 每个清单条目必须包含维度、存在于白名单中的端点，以及预期状态。如果有任何缺失或端点不在白名单中，请在呈现前修复——不要用“待确定”敷衍。

呈现简洁的摘要：

**BAT测试清单摘要**

**被测应用：** <应用目录> · 运行时URL <config.url>
**已读取源码：** <OpenAPI规范路径>、<流XML路径>
**基线：** <无 | N个现有测试位于<路径>>

**覆盖情况：**
- 端点：<M/N个监听路径×方法已覆盖>
- raise-error类型：<列出摘要中的每个类型及触发它的测试；标记未覆盖的类型>
- 状态转换：<列出（如果应用有状态机）>

**清单（共<count>个测试）：**
- 按维度划分：Accuracy <n> · Robustness <n> · Security <n>
- 按来源划分：existing <n> · new <n> · refined <n>   （无基线时省略）

**需人工审核的条目：**
- <契约与代码不一致、可疑的验证逻辑、死分支——或“无”>

然后请求明确审批：

请审核以上清单。是否继续生成并运行测试套件（第二阶段）？

是，生成并运行测试套件。

否，我要修改清单。

否，取消操作。

[阻塞点] 等待明确的“是”答复后再进入步骤7。 如果用户选择“修改清单”，询问具体修改内容（覆盖范围、维度、特定测试）并返回步骤4调整。如果选择“取消”，礼貌地停止操作。

Phase 2: Generate & Run

第二阶段：生成与运行

Step 7: (Re)confirm the Runtime URL and Token

步骤7：（重新）确认运行时URL和令牌

The suite runs against a live endpoint. Confirm the URL and bearer token before scaffolding:

If the user gave a URL/token, use them.
If the app is the local fixture, the defaults are
```
http://localhost:8082/api/v1
```
and
```
Bearer test-token
```
.
If neither is known, ask via
```
AskUserQuestion
```
— a suite pointed at the wrong URL fails every test for the wrong reason.

套件针对实时端点运行。搭建套件前请确认URL和Bearer令牌：

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

Step 8: Scaffold the Suite

步骤8：搭建套件骨架

Create the suite skeleton (config, runner, tests dir):

bash

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

This writes

config/default.dwl

config/local.dwl

(url/token/env),

run-bat.sh

(chmod +x, with the JDK-17

--add-opens

JAVA_OPTS

), and an empty

tests/

. It will not overwrite an existing

config/local.dwl

unless you pass

--force

— respect a url/token the user already edited.

Pick

<suite-dir>

per the user's project convention (e.g.

<app>/bat-generated/

or a path the user names). Do not write into the hand-written baseline directory.

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

bash

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/

或用户指定的路径）。请勿写入手写基线目录。

Step 9: Write the

.dwl

Files and

bat.yaml

, then Validate

步骤9：编写

.dwl

文件和

bat.yaml

，然后验证

For each entry in the inventory whose provenance is not

dropped

, write

tests/<name>.dwl

following every rule in

references/bat-authoring-rules.md

. The canonical shapes are in

references/examples/

— read them and match the style:

```
single-call-happy-path.dwl
```
— one request, multiple asserts.
```
auth-401.dwl
```
— negative/error-code test.
```
multi-step-stateful.dwl
```
— seed call +
```
context
```
+ dependent call (for
```
stateful: true
```
inventory entries).
```
json-body-and-headers.dwl
```
— asserting a parsed JSON body field and a
```
Content-Type
```
header that carries a charset (see rules 7b/7c).

Then write

bat.yaml

(schema in the authoring rules /

references/examples/bat.yaml

suite.name

, a

files:

entry per

.dwl

, and

reporters:

(HTML + JSON). No top-level
config:
key.

As the first tool call after writing, run the static validator against the endpoint allowlist from Step 5:

bash

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

If it exits non-zero, fix the reported files and re-run the validator. Only proceed to Step 10 after it exits 0. Keep the validator and the run in separate responses.

对于清单中来源不为

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

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

如果退出码非零，修复报告中指出的文件并重新运行验证器。只有当退出码为0时，才能进入步骤10。将验证器调用和运行操作分开在不同响应中执行。

Step 10: Run the Suite Against the Live Endpoint

步骤10：针对实时端点运行套件

This is the gate. As the only tool call in this response:

bash

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

Read the output:

All tests pass → proceed to Step 11.
A test fails → diagnose the cause:
- BAT-DSL/syntax error → fix the
```
.dwl
```
  , re-run the validator (Step 9), then re-run the suite.
- Assertion you guessed wrong (the app's real behavior differs from what the test asserted) → correct the assertion to match the deployed behavior, and note the correction in the report.
- What looks like a real app bug → do NOT fix the app. Flag it in the report as a discovered discrepancy, set the assertion to match the actual behavior, and mark it for human review.
- Connection refused / every test 401/404 → the runtime is down or the URL/token is wrong. Fix Step 7's config (re-run
```
scaffold_suite.sh --force
```
  or edit
```
config/local.dwl
```
  ) and re-run. This is not a test defect.

Iterate until all tests pass OR every remaining failure is documented. Do not ship a suite with silent failures. Run only

./run-bat.sh

in this response — no other tool calls alongside it.

这是核心验证环节。在此响应中仅执行此工具调用：

bash

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

读取输出结果：

所有测试通过 → 进入步骤11。
测试失败 → 诊断原因：
- BAT-DSL/语法错误 → 修复
```
.dwl
```
  文件，重新运行验证器（步骤9），然后重新运行套件。
- 断言猜测错误（应用的实际行为与测试断言不符）→ 修正断言使其匹配已部署行为，并在报告中记录此修正。
- 疑似真实应用bug → 请勿修复应用。在报告中标记为已发现的差异，将断言设置为匹配实际行为，并注明需人工审核。
- 连接被拒绝/所有测试返回401/404 → 运行时环境未启动或URL/令牌错误。修复步骤7的配置（重新运行
```
scaffold_suite.sh --force
```
  或编辑
```
config/local.dwl
```
  ）并重新运行。这不属于测试缺陷。

迭代直到所有测试通过或所有剩余失败都已记录。请勿交付存在未记录失败的套件。在此响应中仅运行

./run-bat.sh

——不要同时执行其他工具调用。

Step 11: Write the Report and Declare Completion

步骤11：编写报告并宣告完成

Pre-condition: the immediately preceding response ran

./run-bat.sh

and you have its pass/fail output. If not, go back to Step 10.

Write a short

REPORT.md

next to the suite:

Test count by dimension and by provenance.
Coverage table: each
```
raise-error
```
type and whether a test covers it; each endpoint × method.
Pass rate (X/Y) from the run.
Discrepancies discovered (contract↔code, suspected app bugs) — for human review.
Any tests still failing and why (only if you could not resolve them and chose to flag rather than silently drop).

Then declare completion in a tight message — the user can see the files and the run log. Include exactly:

The suite directory path and test count.
One sentence on what the suite covers.
The pass rate from the live run.
Anything flagged for human review (or "none").

Do not pad with feature lists or next-steps.

前置条件： 上一个响应已运行

./run-bat.sh

且你已获取其通过/失败输出。如果未满足，请返回步骤10。

在套件旁编写简短的

REPORT.md

：

按维度和来源划分的测试数量。
覆盖表：每个
```
raise-error
```
类型及是否有测试覆盖；每个端点×方法。
运行通过率（X/Y）。
已发现的差异（契约与代码不一致、疑似应用bug）——需人工审核。
仍失败的测试及原因（仅当无法解决且选择标记而非静默删除时记录）。

然后用简洁的消息宣告完成——用户可以查看文件和运行日志。消息需包含：

套件目录路径和测试数量。
一句话说明套件覆盖的内容。
实时运行的通过率。
需人工审核的内容（或“无”）。

请勿添加功能列表或后续步骤等冗余内容。

Quick Reference

快速参考

bash

undefined

bash

undefined

Step 1: validate toolchain (jq, BAT CLI, Java 17+) — validation-only

步骤1：验证工具链（jq、BAT CLI、Java 17+）——仅做验证

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

Step 2: anchor the inventory in the real source

步骤2：基于真实源码为清单提供基础

bash <skill-dir>/scripts/extract_endpoints.sh <app-dir> # → tmp/bat-gen/source-digest.json

Step 8: scaffold the runnable suite skeleton

步骤8：搭建可运行的套件骨架

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

Step 9: static DSL validation before spending a live run

步骤9：实时运行前的静态DSL验证

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

步骤10：核心验证环节——针对已部署端点运行

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

undefined

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

undefined

References

参考资料

```
references/bat-authoring-rules.md
```
— the BAT DSL rules (R1–R10),
```
bat.yaml
```
schema, config files, and
```
run-bat.sh
```
. Read before writing any
```
.dwl
```
.
```
references/quality-dimensions.md
```
— the Accuracy / Robustness / Security / Coverage taxonomy used to tag and size the inventory.
```
references/examples/
```
— canonical
```
.dwl
```
files (single-call, auth-error, multi-step stateful, JSON body/headers) and a reference
```
bat.yaml
```
.

```
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
```
。

generate-bat-tests

Original

Translation

Generate BAT Tests

生成BAT测试

When to Use This Skill

何时使用此技能

What BAT is (read once before Phase 1)

BAT是什么（进入第一阶段前请阅读）

Bundled scripts

捆绑脚本

Workflow shape (two phases)

工作流结构（两个阶段）

Workflow-wide discipline (read before Phase 1)

全工作流规范（进入第一阶段前请阅读）

Phase 1: Test Design

第一阶段：测试设计

Step 1: Validate Prerequisites

步骤1：验证先决条件

Step 2: Read the Source and Build the Endpoint Anchor

步骤2：读取源码并构建端点基础

Step 3: Read the Existing BAT Baseline (if one exists)

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

Step 4: Draft the Test Inventory

步骤4：草拟测试清单

Step 5: Derive the Endpoint Allowlist

步骤5：生成端点白名单

Step 6: Present the Inventory Summary and Get Approval

步骤6：呈现清单摘要并获取审批

Phase 2: Generate & Run

第二阶段：生成与运行

Step 7: (Re)confirm the Runtime URL and Token

步骤7：（重新）确认运行时URL和令牌

Step 8: Scaffold the Suite

步骤8：搭建套件骨架

Step 9: Write the .dwl Files and bat.yaml, then Validate

步骤9：编写.dwl文件和bat.yaml，然后验证

Step 10: Run the Suite Against the Live Endpoint

步骤10：针对实时端点运行套件

Step 11: Write the Report and Declare Completion

步骤11：编写报告并宣告完成

Quick Reference

快速参考

Step 1: validate toolchain (jq, BAT CLI, Java 17+) — validation-only

步骤1：验证工具链（jq、BAT CLI、Java 17+）——仅做验证

Step 2: anchor the inventory in the real source

步骤2：基于真实源码为清单提供基础

Step 8: scaffold the runnable suite skeleton

步骤8：搭建可运行的套件骨架

Step 9: static DSL validation before spending a live run

步骤9：实时运行前的静态DSL验证

Step 10: the gate — run against the deployed endpoint

步骤10：核心验证环节——针对已部署端点运行

References

参考资料

Step 9: Write the
`.dwl`
Files and
`bat.yaml`
, then Validate

步骤9：编写
`.dwl`
文件和
`bat.yaml`
，然后验证