create-agent-tests

Agent 测试

Agent 测试的生产者技能：编码 Agent 针对目标环境执行 Markdown 用例文件，并返回可审计的报告。验证依据是执行 Agent 的判断及其收集的证据（浏览器、API、DB、日志、云、遥测数据），而不是固定的确定性断言。

此技能用于编写和运行 Agent 测试。每个用例都会生成一份可审计的报告，包含报告路径、最终的 PASS/FAIL/BLOCKED/ABORTED 状态，以及收集到的证据文件，供调用方使用。

何时使用 Agent 测试

当验证需要通过工具灵活判断 UI、API、数据库、日志、文件、网络或实时环境状态，而确定性测试还为时过早、容易脆弱、成本太高或范围过窄时，使用 Agent 测试。

尤其适用于：

• 需要通过视觉、交互、浏览器控制台、网络或追踪进行验证的 UI 变更。
• 需要通过实时请求和持久化状态检查来建立信心的 API 和 DB 工作流。
• 跨越前端、后端、存储、作业、外部模拟和清理环节的全栈流程。
• 在将稳定路径转为标准单元、契约、集成、YAML E2E 或其他确定性测试之前，进行探索性回归检查。

Agent 测试不能替代确定性测试。Agent 流程稳定后，优先将高价值的稳定流程转为标准确定性测试（单元、契约、集成、YAML E2E 或其他测试）。

项目布局

目标仓库中的 Agent 测试存放在 tests/agent/ 下：

tests/agent/agent-test-suites.json   suite manifest (project-owned)
tests/agent/<feature>/<case>.md       case files, one logical journey each
tests/agent/run-agent-verification.ts runner/orchestrator
agent-test-reports/                    generated reports; do not hand-edit

仓库负责管理实际使用的 agent-test-suites.json、用例文件、测试装置设置、认证/会话引导、CI 配置、引擎密钥和 MCP 配置、预发布/生产环境变更策略，以及清理工作的责任归属。

优先遵循本地约定

编写用例前，检查是否存在 tests/agent/agent-test-template.md。如果存在，将其视为权威的本地约定。除非用户明确要求更新该约定，否则不要通过广泛搜索重新发现或替换它。

如果不存在本地测试框架，且 Agent 测试是成本最低的充分验证方式，则按需复制此技能附带的初始文件来搭建：

• <skill-dir>/assets/agent-test-template.md → tests/agent/agent-test-template.md
• <skill-dir>/assets/agent-test-suites.example.json → tests/agent/agent-test-suites.example.json
• <skill-dir>/assets/run-agent-verification.ts → tests/agent/run-agent-verification.ts

只有项目实际采用 Agent 测试时才复制这些文件；不要预先放入尚未采用该测试方式的仓库。然后根据示例创建实际使用的清单：

cp tests/agent/agent-test-suites.example.json tests/agent/agent-test-suites.json

编写测试用例

根据 <skill-dir>/assets/agent-test-template.md（或本地模板）编写每个测试用例。优秀的测试用例应让执行 Agent 几乎无法靠猜测完成：

• 说明正在测试的要求、风险或行为，并链接相关来源。
• 补充真实的项目上下文：各环境的 URL、账号/组织、测试夹具和数据变更策略、数据库/日志/云服务访问权限、生产环境合成数据策略，以及清理责任归属。
• 将环境预检（证明目标环境可以执行测试用例）与产品验证（运行检查）分开。
• 列出具体检查项：浏览器页面/状态、API 路由和状态码、数据库表/行、审计事件、日志筛选条件、遥测查询、时序。
• 对测试本身创建的状态，所有断言都必须无条件执行。若某项检查以可选功能为前提（“如果界面提供 X，则验证 Y”），而 Agent 没有找到 X 时仍可跳过 Y 并通过测试，那么只要没有找到 X，测试就会静默地丢失其原本要覆盖的内容。对于你可以控制的测试夹具（例如刚创建的令牌、组织等），应要求该功能存在并直接对其断言；仅对确实依赖环境的界面才使用条件措辞。
• 明确说明每种行为所需的具体证据。
• 确保测试用例具有可移植性；将环境特定信息放在 testing-environments 部分，而不是步骤中。
• 切勿存储原始密钥。仅记录变量名、角色和访问方式。

运行

在目标仓库中添加一个 package 脚本，并根据其包管理器调整：

{ "scripts": { "agent:verify": "tsx tests/agent/run-agent-verification.ts" } }

运行整个测试套件或单个测试用例：

pnpm agent:verify --target local --suite smoke --project-name "<project name>"
pnpm agent:verify --target local --case tests/agent/<feature>/<case>.md

references/runner.md 完整说明了运行器默认设置、标志、对应的环境变量以及报告状态约定。

报告状态约定

每份测试用例报告都必须以且仅以一行结尾：

Status: PASS
Status: FAIL
Status: BLOCKED
Status: ABORTED

• PASS / FAIL：已完成环境预检并运行产品验证。
• BLOCKED：环境/设置问题导致无法执行测试用例（缺少数据库/日志访问权限、URL 无法访问、登录/会话初始化失败、缺少测试夹具或审批）。环境阻塞不得报告为 FAIL。
• ABORTED：仅用于编排中断。发布门禁会忽略 ABORTED 并重新运行该测试用例；中断时切勿以 PASS/FAIL/BLOCKED 结尾。

必需的测试用例若未返回 PASS，运行器就会判定失败。

如果测试用例需要驱动浏览器，请收集可审计的证据——HTML 报告、截图集、视频、跟踪记录或项目标准认可的等效证据。仅提供文字形式的浏览器操作声明并不足够。

输出

每次运行都会在其报告路径下生成一份可审计的报告，报告以且仅以一行 Status: 结尾，并附带所有收集到的证据材料（HTML 报告、截图、视频、跟踪记录、日志）。报告及其证据就是交付物——调用此技能的对象会使用这些内容。

何时不应使用

• 若确定性的单元测试、契约测试、集成测试或 YAML E2E 测试能以更低成本、更持久地提供证明，请改用标准的确定性格式。
• 若没有可用的实时环境、访问权限或测试夹具，请记录阻塞原因，而不是编写无法运行的测试用例。