1. 先搞清楚 Playwright Test Agents 到底解决什么问题Playwright Test Agents 是 Playwright 官方在 1.5x 版本之后推出的一套「测试代理」能力它把自动化测试的建设过程拆成了三个角色planner 负责探索页面并产出测试计划generator 负责把计划翻译成可执行的 spec 文件healer 负责在用例失败后尝试修复选择器、等待和断言。它适合谁适合已经有 Playwright 基础、想给模块快速铺回归集的测试同学也适合想把 AI 引入测试链路但不想被「一键生成一堆垃圾用例」坑到的团队。我实测下来的感受是这套东西的价值不在「少写几行代码」而在于它把测试建设变成了一条可审核的链路——测试目标、测试计划、自动化用例、执行失败、修复回归每一步都有产物落盘你能 review、能回滚、能追责。这比让 AI 直接吐一个 spec 文件靠谱得多。但坑也很明确init-agents 目前只给 Claude Code、Copilot、OpenCode、VS Code 这几类宿主生成 Agent 定义和 MCP 配置Codex 不在原生支持列表里generator 生成的选择器经常出现 strict mode violationhealer 修的是「脚本问题」而不是「产品缺陷」如果页面真的坏了它会把断言改软把真实 bug 掩盖掉。下面我把 MCP 接入、settings.json 骨架、config.toml 骨架和验证动作完整走一遍。2. 前置准备TaoToken 接入与 Playwright 环境在讲配置之前先把模型调用这条链路打通。Test Agents 本身是 Playwright 的宿主能力但它需要一个大模型来驱动 planner/generator/healer 的推理我用的是 TaoToken 的 API 来做模型调用这样在 Claude Code、Codex 或自建脚本里都能统一走一个入口。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数直接拼 /v1 之类的路径即可。你需要先在控制台创建一个 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 的管理页面在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。环境方面我本地用的是 Node.js v22.17.1、Playwright 1.60.0、Chrome 稳定版。初始化项目mkdir pw-agents-demo cd pw-agents-demo npm init -y npm i -D playwright/test1.60.0 npx playwright install chromium然后初始化 Test Agents。注意这一步不是帮你跑测试而是给宿主生成 Agent 定义文件和 MCP 配置npx playwright init-agents --loopclaude --prompts--loop的可选值我实测--help里是 claude、copilot、opencode、vscode、vscode-legacy没有 codex。执行完之后你会看到.claude/agents/下多了三个 markdown 定义文件同时项目里多了一份 MCP 配置片段。如果你用的是 VS Code把--loop换成 vscode 即可。注意init-agents 生成的是「宿主侧」的 Agent 定义它不会自动帮你把 MCP server 注册到全局配置里这一步要手动确认。3. 可复制配置settings.json 与 config.toml 骨架3.1 Claude Code / VS Code 侧的 settings.json 骨架如果你走 Claude Code 或 VS Code 路线MCP server 的注册一般落在 settings 类文件里。下面是我实测能跑通的骨架重点是command、args和超时参数{ mcpServers: { playwright-test: { command: npx, args: [playwright, run-test-mcp-server], env: { PLAYWRIGHT_HTML_OPEN: never }, startupTimeout: 20000, toolTimeout: 120000 } } }这里几个参数值得说清楚。startupTimeout给 20 秒是因为 npx 首次拉包会慢给太短会直接报 MCP server 启动失败toolTimeout给 120 秒是因为 generator 生成一个完整 spec 可能要跑十几秒到几十秒默认值容易超时中断。PLAYWRIGHT_HTML_OPENnever是防止每次跑完自动弹报告窗口在 CI 或远程环境里很烦。3.2 Codex 侧的 config.toml 骨架Codex 目前没有--loopcodex但 Codex 支持自定义 subagent 和 MCP所以可以手动迁移。MCP 部分写进.codex/config.toml[mcp_servers.playwright-test] command npx args [playwright, run-test-mcp-server] startup_timeout_sec 20 tool_timeout_sec 120然后把 Playwright 生成的三个角色迁移成 Codex subagent分别放在.codex/agents/playwright-test-planner.toml .codex/agents/playwright-test-generator.toml .codex/agents/playwright-test-healer.toml每个 toml 的核心是 name、description 和 instructions 三段。以 planner 为例name playwright_test_planner description 基于 seed spec 探索页面并产出测试计划 instructions 你是 Playwright 测试计划代理。读取 tests/seed.spec.ts 作为入口 探索目标页面输出 markdown 测试计划到 specs/ 目录。 计划必须包含前置入口、每个场景的操作步骤、明确断言、正向与异常场景区分。 不要生成 spec.ts 代码只产出计划。 generator 和 healer 同理instructions 里分别强调「严格按计划生成 spec选择器优先用 getByRole/getByLabel 并加 exact」和「只修选择器、等待、断言不得放宽业务断言」。3.3 模型调用侧的环境变量不管走哪个宿主模型调用统一指向 TaoTokenexport OPENAI_BASE_URLhttps://taotoken.net/api/v1 export OPENAI_API_KEYsk-你的TaoTokenKey如果你用的是 Anthropic 兼容协议把 base 换成对应的 Anthropic 端点即可Key 还是同一个。这一步做完planner/generator/healer 的推理请求就会走 TaoToken而不是直连各家官方。4. 验证 Agent 是否生效从 planner 到 healer 的完整动作4.1 先让 planner 产出计划不要一上来就让 generator 生成代码先准备一个 seed spec 作为入口比如tests/seed.spec.ts里只写打开页面和登录逻辑。然后给 planner 下指令请使用 playwright_test_planner 这个 subagent 基于 tests/seed.spec.ts 为优惠券下单模块生成测试计划 覆盖金额计算、有效优惠券、无效优惠券、商品切换、订单提交反馈 输出到 specs/order-coupon.md。跑完之后打开specs/order-coupon.md检查三件事前置入口写没写清楚、每个场景有没有明确断言、正向和异常场景有没有分开。这一步是整条链路的地基计划跑偏后面全歪。4.2 generator 生成用例并首跑计划确认后让 generator 按计划生成npx playwright test tests/order-coupon.spec.ts --reporterline我第一轮跑就撞上了典型报错Error: strict mode violation: getByLabel(商品) resolved to 2 elements原因是页面上既有「商品信息」区域又有「商品」下拉框getByLabel(商品)命中了多个元素。修复方式是加 exactawait page.getByLabel(商品, { exact: true }).selectOption(course);这个例子说明 generator 能提速但选择器和断言必须人工 review尤其是 label 有包含关系的表单。4.3 healer 修选择器类失败我故意留了一条旧脚本await page.getByRole(button, { name: 使用优惠券 }).click();但页面真实按钮文案已经是「应用优惠券」执行后失败。Playwright 的失败上下文里会带当前页面快照healer 能读到按钮实际文案修复后变成await page.getByRole(button, { name: 应用优惠券 }).click();最后全量回归npx playwright test --reporterline结果7 passed。到这里 planner、generator、healer 三个角色都验证过了说明 Agent 链路是通的。5. 本篇常见错排查MCP server 启动超时报MCP server failed to start或startup timeout先确认npx playwright run-test-mcp-server能单独跑起来再检查startupTimeout是否给到 20 秒以上。首次 npx 拉包慢是常见原因。strict mode violationgetByLabel、getByRole、getByText命中多个元素。优先加{ exact: true }或者用filter({ hasText: ... })缩小范围不要直接改成nth(0)那样会把脆弱性藏起来。generator 生成的断言太软比如把expect(total).toBe(99.00)写成expect(total).toBeVisible()。这是 healer 或 generator 为了「让测试通过」的常见退化必须在 review 时改回业务断言否则回归集形同虚设。Codex 里读不到 .claude/agentsCodex 不认 Claude 的 agent 目录必须迁移成.codex/agents/*.toml同时把 MCP 配到.codex/config.toml两边都要有缺一个都调不起来。healer 把真实缺陷修没了如果页面真的坏了比如金额算错healer 可能改断言让它通过。判断标准是healer 只应该改选择器、等待、定位方式任何涉及业务数值和业务逻辑的断言改动都要人工确认。模型调用 401 或超时检查OPENAI_BASE_URL是否指向https://taotoken.net/api/v1Key 是否从控制台正确复制以及网络是否能访问该端点。如果宿主有自己的模型配置确认它没有覆盖环境变量。6. 怎么把这套东西接进现有工作流我的用法是这样分层的MCP 用来调试单条流程Test Agents 用来建设模块级回归集Playwright Test 负责执行和接入 CICodex 或 Claude Code 用来做测试计划评审、脚本修改和失败分析。这样分工的好处是AI 负责体力活人负责判断。如果你还在选模型入口可以先从模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatutm_campaignrewrite 试一下 planner 的提示词效果如果打算长期跑编码和 Agent 任务Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 里有额度方案接入细节和参数说明看文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite Claude Code 相关的接入说明在 https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecodeutm_campaignrewrite 。Key 还是去 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 创建。最后留一个我踩过的坑planner 产出的计划一定要先 review 再喂给 generator我试过跳过这步直接生成结果 spec 里把「无效优惠券」和「有效优惠券」的断言写反了跑出来全绿但业务是错的。计划这层审核省不得。
