agentic-uitest

让 Claude Code / Codex 这类编码智能体"探索一次网页 → 固化成可重复跑的 Playwright 回归用例"的 MCP 服务：智能体负责理解业务和录制，工具负责防假通过验证、用例管理和日常回归——UI 测试从"每次都让 AI 点一遍（慢、贵、不稳定）"变成"AI 录一次，以后确定性回放（快、免 token、可持续维护）"。

• 🧭 对话式共测（cotest）：智能体驱动一个全程可见的浏览器，你可以随时接管操作，人机动作合并成同一条轨迹
• 🛡️ 防假通过三道闸：检查点证据必须是"动作后新出现的"、断言用计数增量而非裸可见、固化前做阴性对照（不做动作证据不该出现）
• ✍️ 手写用例一等公民：复杂异步流程（等 LLM 生成、条件分支）合成失败时返回轨迹素材（handoff）供智能体直接手写 spec，register_test 一键纳管
• 📊 本地控制台：用例库、运行历史、失败截图/录像/trace、一键重跑，浏览器打开即用

快速上手（3 步）

1. 安装（需 Node 18+）

npm install -g agentic-uitest
npx playwright install chromium

2. 在你的项目根目录创建 .mcp.json（Claude Code 会自动读取）

{
  "mcpServers": {
    "agentic-uitest": {
      "command": "agentic-uitest",
      "args": ["serve", "--port", "4318", "--no-token"],
      "env": {
        "TARGET_BASE_URL": "http://127.0.0.1:3000/",
        "UI_TEST_HEADLESS": "false",
        "TEST_SECRET_1": "<登录密码，不会写进用例>"
      }
    }
  }
}

3. 重启 Claude Code，对它说：

用 cotest 测 http://127.0.0.1:3000/ 的下单流程：进入商品页 → 加购 → 结算 → 出现订单成功提示。成功的话固化成测试用例。

智能体会打开一个可见浏览器逐步操作、打检查点、沙箱双重放验证后写入用例。之后回归只需一句：

运行所有测试用例，看看有没有挂的

控制台地址：http://127.0.0.1:4318/（用例库 / 运行历史 / 录像 / trace 都在这）。

与 Codex 配合

~/.codex/config.toml：

[mcp_servers.agentic-uitest]
command = "agentic-uitest"
args = ["serve", "--port", "4318", "--no-token"]
env = { TARGET_BASE_URL = "http://127.0.0.1:3000/", UI_TEST_HEADLESS = "false" }

实用提示词模板

| 场景 | 提示词 | |---|---| | 录制并固化 | 用 cotest 测 <URL> 的 <业务流程>：<步骤描述>。成功的话固化成测试用例 | | 有登录的项目 | 什么都不用加——工具自动探测项目登录态并复用；全新项目先说：用 cotest 录一遍登录（账号 xx，密码用 TEST_SECRET_1），固化为登录用例并保存登录态到 .auth/user.json | | 复用前置流程 | cotest_start 时用 replayFromTestId 先重放 <用例ID>，再继续测 <后续流程> | | 纳管手写用例 | 用 inspect_project 检查项目，把 unregisteredSpecs 里的用例用 register_test 登记并验证 | | 修改已有用例 | 直接修改 <spec 文件>，改完用 verify_test 验证 | | 日常回归 | 运行全部用例 / 我改了 src/checkout，跑受影响的用例（run_impacted_tests） |

CLI 命令

agentic-uitest serve      [选项]   MCP 服务器（供 Claude Code / Codex 连接）+ 控制台
agentic-uitest dashboard  [选项]   只启动控制台（--open 自动开浏览器）
agentic-uitest init       [选项]   给项目生成最小 Playwright 脚手架（默认只预览）
agentic-uitest inspect    [选项]   查看项目接入状态

选项：--project <dir>  --base-url <url>  --port <n>  --open  --no-token

配置项

| 环境变量 | 说明 | 默认 | |---|---|---| | TARGET_BASE_URL | 被测应用地址（必填） | — | | UI_TEST_PROJECT_ROOT | 用例落盘的项目根目录 | 当前目录 | | UI_TEST_HEADLESS | false 时全程显示浏览器窗口 | true | | TEST_SECRET_1（_2…） | 登录密码等密文，按录制中出现顺序对应；只进环境变量，不落盘、不进用例 | — | | UI_TEST_DASHBOARD_PORT | 控制台端口（同 --port；被占用时自动换） | 4317 | | UI_TEST_ARTIFACT_ROOT | 运行产物（录像/trace/历史）存放目录 | <项目>/artifacts | | UI_TEST_SLOW_MO_MS | 每个浏览器动作放慢毫秒数（演示用） | 0 | | AGENTIC_UITEST_EXPOSE_DISCOVERY | 1 时额外注册"审批式探索（discovery）"那一组 MCP 工具。默认关闭——编码智能体用 cotest 直接驱动浏览器即可，这组主要给控制台的可视化探索流程用 | 关 | | AGENTIC_UITEST_EXPOSE_SELECTOR_HEALING | 1 时额外注册"选择器自愈"MCP 工具（suggest_selector_recovery 等）。默认关闭——选择器失效时智能体直接读用例改选择器再 verify_test 更直接 | 关 |

默认只暴露约 26 个与编码智能体日常回归相关的工具（配置 / 运行 / cotest 共测）。上面两个开关控制的 20 个工具默认隐藏以精简工具面、提升智能体选工具的准确度；它们只影响 MCP 工具列表，本地控制台的探索与自愈功能不受影响（控制台走独立的 HTTP API）。改动 .mcp.json 后需重启 Claude Code / Codex 生效。

生成的资产都在你的项目里：用例 spec（普通 Playwright 文件，可直接编辑）+ config/tests.json（用例注册表）+ artifacts/（建议加入 .gitignore）。

工作流一图流

cotest 共测录制（智能体驱动 + 人可接管 + 检查点）
   │
   ├─ 简单流程 → cotest_finalize：合成 spec → 阴性对照 → 沙箱双重放 → 写入注册表
   │
   └─ 复杂流程（等 LLM 生成/条件分支）→ finalize 返回 handoff 素材
                → 智能体手写 spec → register_test 登记 + 验证
   │
   └→ 日常：run_tests / run_impacted_tests 回归，verify_test 改后复验，
       控制台看历史、录像、trace；选择器失效时智能体直接改用例再 verify_test
       （或开 AGENTIC_UITEST_EXPOSE_SELECTOR_HEALING 用 suggest_selector_recovery 自愈）

FAQ

Q：需要项目里已经有 Playwright 吗？ 不强制。全新项目对智能体说"用 init_project 接入"即可生成最小脚手架；已有 Playwright 的项目直接用，不会覆盖任何现有文件。

Q：登录怎么处理？密码会泄露吗？ 工具自动探测项目的 Playwright storageState 约定并复用登录态，不会把登录步骤录进业务用例。密码通过 TEST_SECRET_n 环境变量注入，录制中自动脱敏——不写盘、不进生成的用例、不发给模型。

Q：检查点被拒绝，提示"证据文本在动作前已存在"？ 这是防假通过机制在工作：页面历史数据里已有的文案（如聊天历史里的"N 个步骤"）证明不了本次动作产生了新结果。换一段动作后新出现的独特文本（如本次回复内容的片段）；确实要断言"数量增加"就传 allowPreexisting: true。

Q：cotest_finalize 一直失败怎么办？ 不要反复重试。复杂异步流程（等待 LLM 生成完成、页面有条件分支、后端要求数据唯一）机械合成到不了终点——finalize 失败时会返回 handoff（轨迹、选择器、iframe 链、检查点素材），让智能体基于它直接手写 spec，再用 register_test 登记验证，能力完全等同。

Q：页面里有 iframe（内嵌面板/助手）能测吗？ 能。快照会遍历所有 frame（iframe 内元素带 [iframe] 标记），动作、检查点和生成的用例自动使用 frameLocator 链。

Q：智能体自己写的用例控制台里看不到？ 用例必须登记进 config/tests.json 才被管理。说一句"用 inspect_project 找出 unregisteredSpecs 并 register_test 登记"即可。

Q：升级了版本但行为没变？ MCP 服务进程要重启（Claude Code 里 /mcp → Reconnect，或重开会话）；控制台页面也要重新打开——页面里的"刷新"按钮只刷数据不刷页面 JS。控制台标题旁有版本号，可确认是否为新版。

Q：VSCode 内置浏览器里录像播放不了？ 新版已通过 blob 方式兼容。若仍失败，失败信息会标明阶段（HTTP 状态/内容类型/媒体错误码），或点"单独打开"用系统浏览器看。

Q：运行失败提示可能是登录态过期？ 按提示先运行登记过的登录用例（tag auth-setup）刷新登录态，再重跑。

Q：控制台安全吗？ 只监听本机回环地址；默认带随机 token（--no-token 可关，仅限本机使用），写操作有 origin 校验，产物路径严格限制在 artifact 目录内。