Coding Agent 写代码的速度已超过人类 review 的速度但验证没跟上Agent 改完一行代码CI 里跑的还是人写的旧用例。TestSprite CLIGitHub 2800 star 的 Apache-2.0 开源项目TypeScript 实现把测试平台封装成Agent 可直接驱动的 CLI 契约JSON Schema 描述意图式测试计划、退出码矩阵表达机器可读结论、自洽失败 Bundle 让 Agent 一次拿全修复上下文。Claude Code、Codex、Cursor 都能直接调用这套设计思路可以迁移到任何给 Agent 做工具的项目。为什么是 CLI 契约而不是测试框架传统 E2E 的产物是代码 selectorAgent 生成这类代码失败率很高selector 随 DOM 变化就挂断言太具体脆弱、太泛无效。plan 文件反其道而行——只描述用户意图不写选择器{ $schema: https://raw.githubusercontent.com/TestSprite/testsprite-cli/v0.4.0/schemas/plan.schema.json, projectId: prj_abc123, type: frontend, name: Login rejects an empty password, priority: p0, planSteps: [ { type: action, description: Navigate to /login and submit the form with an empty password }, { type: assertion, description: Verify an inline error says the password is required } ] }维度传统 E2EPlaywright意图式 Plan用例描述selector 断言代码自然语言 action/assertion1-200 步稳定性selector 随 DOM 漂移平台端 LLM 解析意图DOM 变化可自愈凭据处理写在代码/env存 project 配置plan 里禁止变量替换schemadraft-07里几个值得抄的决策name必须是可断言的动词行为句subject verb outcome拒绝名词片段方便 LLM 和 failure 分析提取断言目标{{placeholder}}不做变量替换结构上合法、能过校验但 CLI 只打非致命[advisory]——Agent 会把花括号原样敲进输入框凭据的正确位置是 project 配置project update --username/--password$schema按版本钉住v0.4.0而非mainCLI 升级后 plan 依然解析到同一份 schema不会因main新增必填字段导致历史 plan 全挂256KB 单文件、批量 5MB/50 条上限都在客户端、任何网络调用之前强制。还有个决策值得抄schema 与校验器assertPlanShape可能不一致项目约定校验器实际行为优先并用 spec 测试钉住——契约与实现谁说了算这里有标准答案。退出码矩阵把测试结论变成机器可读信号CLI 给 Agent 用最大的坑是人类友好的输出对 Agent 不友好。解法是双通道--output json输出稳定结构可 pipe 给 jq 或直接喂 LLM退出码表达语义退出码含义0 / 1通过 / 通用失败或非通过 run 状态3-7认证 / 未找到 / 校验失败 / 冲突 / 超时10-13服务不可用 / 限流可重试/ 额度不足 / 功能未开通14CLIENT_TOO_OLD后端要求升级 CLIHTTP 426不可重试129/130/143SIGHUP / SIGINT / SIGTERM128 信号号细节见功力test run --wait超时退出 7前先把含runId的 partial 对象打到 stdout并附nextAction指向test wait run-id——脚本不会拿到空 stdout也永远有 id 续跑test diff run-a run-b把回归编码进退出码verdict 一致退出 0、不一致退出 1一行脚本就能断言这次 rerun 与上次已知良好 run 行为一致信号处理--wait期间 Ctrl-C 优雅分离退出128信号Ctrl-C 永不取消服务端 run要停只能test cancel run-id。EPIPEtest list | head静默退出 0。原则退出码与 stdout 结构永远自洽——Agent 拿到非零退出码时stdout 里一定有能继续行动的 id 和 nextAction。失败 Bundle一次拿全修复所需上下文测试失败后 Agent 最痛苦的是上下文散落各处。test failure get把最新失败打包成自洽目录testsprite test failure get test_3a9f21c7 --out ./.testsprite/failure # 产物示意 # .testsprite/failure/ # ├── result.json # verdict / failureKind / snapshotId / runId / codeVersion # ├── failure.json # root-cause 假设 推荐修复目标 # ├── test.py # 生成的 Playwright 测试源码 # ├── step_03/ # 失败步 ±1 邻居screenshot.png dom.html # └── video.mp4全 bundle 共享同一snapshotIdCLI 拒绝拼接不同 run、不同 codeVersion 的数据——多实体读取的一致性用快照 id 而非再查一次保证Agent-safe 原则--out原子写崩溃留.partial标记--failed-only只保留失败步 ±1 邻居压住 Agent 读上下文的 token 成本rerun 是 replay 不是重跑test rerun按保存脚本 verbatim 回放前端默认开 AI heal-on-drift可--no-auto-heal关test run才是触发全新 agent run、可能重新生成代码。修回归用 rerun验新行为用 runtest flaky检测时强制 auto-heal off多次 verbatim replay 统计通过率避免AI 悄悄修了漂移掩盖非确定性——测的是脚本稳定性不是被测应用。Agent 注入把 CLI 用法写进 Agent 的出厂设置光有 CLI 不够Agent 得知道怎么用。testsprite agent install把 skill/instruction 写进项目支持 8 个目标claude 为 GAcodex/cursor/cline/windsurf/antigravity/kiro/copilot 为 experimental。testsprite agent install claude # 装 Claude Code skill testsprite agent install codex # 写进 AGENTS.md 的 managed-section testsprite agent status # 检查各 target有问题退出 1可作 CI gate两个值得抄的设计codex 目标用 managed-section 模式只在现有AGENTS.md里写哨兵包裹段!-- sentinel --...!-- /sentinel --重跑原位替换绝不碰哨兵外的用户内容——给 Agent 装配置的礼貌agent status输出ok/stale/modified/unmarked/absent/corrupt六态能检测 skill 被用户改过modified或与 CLI 版本不匹配stale有任何问题退出 1agent status ...可直接当 CI 前置步骤。skill 文件的版本管理比复制粘贴 prompt 进 AGENTS.md前进了一大步。CI/CD 集成与工程细节# JUnit XML sidecar--output json 不受影响 testsprite test run --all --project proj_xxx --wait \ --report junit --report-file ./results.xml # GitHub Actions 原生输出::error:: 注解 job summary 表格 testsprite test run test_xxx --wait --summary-file ./summary.json --output jsonGitHub Actions 检测自动输出::error::注解到 PR checks job summary 表格内容转义run 错误文本无法注入 workflow command——把 CI 输出当攻击面处理--target-url预检拒绝 localhost、127.x、::1、RFC1918 等内网地址测本地走 MCP 隧道插件客户端先拦无效目标不让云端 run 白跑幂等与重试语义显式每次 run 自动 mint idempotency key批量deferred[]非空以 7 退出并给 nextAction换新 key 重试凭据不进 shell history--password-file/--client-secret-file是标配auto-auth支持 password / OAuth refresh_token / AWS Cognito 三种登录流每次 run 自动换新 token--dry-run全局可用完整校验但零网络、零凭据、零文件写入Agent 迭代 plan 可先校验再真建telemetry 是固定白名单只上报命令名、结果、退出码、错误 code、时长不含 API key、URL、参数值、错误消息DO_NOT_TRACK1可关。踩坑与使用建议先--dry-run再真跑省无效调用和额度凭据走 project 配置或--*-fileplan 里{{placeholder}}就是字面量进输入框锁 CLI 版本号后端通告最低版本太旧直接 HTTP 426 退出 14装最新会让流水线某天莫名全红CI 里关交互噪音TESTSPRITE_NO_UPDATE_NOTIFIER1、NO_COLOR1。小结TestSprite CLI 值得借鉴的不是AI 测试本身而是把Agent 当一等公民设计 CLI 契约意图式 plan 把用例从代码降维成结构化 JSON退出码矩阵让结论变成脚本可分支的信号失败 Bundle 用 snapshotId 保证上下文自洽skill 注入让 Agent 开箱即用。这套模式——机器可读契约 显式错误语义 自洽上下文打包——可直接迁移到任何给 Agent 做工具的项目。进阶方向AGENTS.md managed-section 正成为跨 Agent 配置标准skill 文件的版本化与六态检测会是下一波 Agent 工程化基础设施。
