【10. web 自动化测试及项目部署】：用 skill 打通 playwright-cli 自动化测试与数据库重置全流程

1. 从零散脚本到可复用流程web 自动化测试与数据库重置的真实痛点做 web 项目的人大多经历过这个阶段本地写几个 Playwright 脚本跑一跑手动改改数据库再手动部署一下看起来也能跑通。但一旦换个人接手或者过两周自己回头看就发现脚本散落在各处、数据库状态说不清楚、部署文档早就过期。这套流程最大的问题不是技术难而是没有收敛成一条可复用的链路。我这次要聊的场景很具体一个 OJ 在线判题系统前端有登录、注册、题目列表、题目详情、代码提交、管理后台、落地页等模块后端有判题服务数据库里存着题目、用户、提交记录。项目已经做过单元测试和接口自动化测试数据库里堆了一堆测试数据。现在要做的是用 playwright-cli 执行 web UI 自动化测试测试前把数据库重置成干净状态测试后生成项目阅读文档和部署文档。为什么强调数据库重置因为 UI 测试和接口测试不一样。接口测试可以直接构造请求、断言响应数据库脏一点也能跑。但 UI 测试是模拟真实用户操作比如注册一个新用户如果数据库里已经有同名用户用例就会失败比如题目列表如果数据库里有几十道测试题目断言列表显示 3 道题就会挂。所以测试前必须保证数据库处于已知的、干净的状态。为什么用 playwright-cli 而不是 playwright-mcp核心原因是 token 消耗。MCP 的交互流程是用户描述任务 → AI 工具把任务和 MCP Server 信息一起给 LLM → LLM 决定发什么请求 → MCP Client 转发 → MCP Server 执行 → 返回结果 → LLM 分析。这个链路里MCP Server 的工具描述、每次请求的上下文都要塞进 token。而 CLI 的方式是LLM 直接生成一条命令行AI 工具执行把 stdout 返回给 LLM 分析。实测下来playwright-cli 的 token 消耗大约只有 playwright-mcp 的四分之一。在当前阶段token 就是成本能省则省。那 skill 又是什么你可以把 playwright-cli 理解成一个工具箱里面有螺丝刀、扳手、电钻。skill 则是这套工具的说明书而且是专门写给 AI 看的说明书。安装 skill 之后AI 在生成 playwright-cli 命令时能参考官方提供的最佳实践而不是瞎猜参数。这样生成的命令更准确减少反复试错。这套流程适合谁适合正在做 web 项目、想把手动测试和部署收敛成自动化流程的开发者适合已经在用 AI 辅助编码、但还没把测试环节接进来的团队也适合想了解 playwright-cli skill 这套组合怎么落地的人。下面我会从环境搭建、skill 配置、测试用例生成、数据库重置、实际执行、报错排查一路讲下来每个环节都给可复制的命令和配置。2. TaoToken 前置准备给 playwright-cli 测试链路接上模型能力playwright-cli 本身只是浏览器自动化工具它不负责理解测试文档生成测试步骤分析失败原因。这些需要 LLM 来做。所以整条链路里模型接入是前置条件。我这边用的是 TaoToken 提供的 API 服务它兼容 OpenAI 风格的接口配置起来比较直接。先说你需要在 TaoToken 控制台拿到什么。登录之后进控制台创建一个 API Key。这个 Key 就是后面所有模型调用的凭证。注意 Key 只在创建时显示一次复制下来存好。如果你用的是 Claude Code 或者类似的编码工具TaoToken 也提供了对应的接入方式Base URL 用https://taotoken.net/api不要加 UTM 参数。模型选择上做 playwright-cli 测试编排建议用能力较强的模型。因为测试文档理解、用例生成、失败分析这些任务对模型的推理能力有要求。弱模型容易生成错误的 playwright-cli 命令或者在分析报错时给出无关建议。我实测下来用中等以上能力的模型一次生成可用命令的概率明显更高。配置方式分两种。如果你用的是支持自定义 Base URL 的 AI 工具直接在设置里填{ base_url: https://taotoken.net/api, api_key: 你的_API_Key, model: 你选择的模型ID }如果你用的是 Claude Code配置会稍微不同。Claude Code 读取的是环境变量或者配置文件。你可以在项目根目录或者用户目录下配置# 示例配置路径按你的实际工具调整 [model] base_url https://taotoken.net/api api_key 你的_API_Key model_id 你选择的模型ID这里要提醒一点Base URL、API Key、Model ID 这三件套必须配套。只填 Base URL 不填 Key请求会返回 401Key 填错同样 401Model ID 填了不存在的会返回模型不存在的错误。后面排障章节我会详细讲这几个报错怎么定位。为什么要在测试链路里接模型因为 playwright-cli 的命令虽然可以手写但测试用例有几十条每条都要打开页面、输入、点击、断言手写命令效率太低。让模型读测试文档自动生成 playwright-cli 命令序列才是这套流程的价值所在。模型负责翻译测试文档成命令playwright-cli 负责执行skill 负责让模型翻译得更准。还有一点数据库重置程序也可以让模型来写。你给模型看测试文档告诉它需要哪些预置数据、哪些冗余数据要删它就能生成一个重置脚本。当然这个脚本执行前一定要人工确认确认它操作的是测试库而不是生产库。这一点我在后面会再强调。TaoToken 的 API 文档和模型列表可以在官网查到接入文档里有详细的参数说明。如果你还没拿 Key先去控制台创建一个后面所有步骤都依赖这个 Key。3. 可复制配置playwright-cli skill 数据库重置的完整片段这一章是整篇的核心我给的都是可以直接复制粘贴的配置和命令。你按顺序操作就能把环境搭起来。3.1 环境安装先确认 Node.js 和 npm 可用。Windows 上装 Node.js 就是下载安装包一路 next装完在 PowerShell 里验证node -v npm -v能输出版本号就行。我这边是 Node v24 和 npm 11你的版本不用完全一样但建议 Node 18 以上。然后装 opencode如果你用其他 AI 工具这步可以跳过换成你用的工具npm i -g opencode-ai接着装 playwright-clinpm install -g playwright/clilatest装完之后验证一下用有头模式打开一个页面playwright-cli open baidu.com --headed--headed这个参数很关键。不加的话默认是无头模式浏览器窗口不可见。无头模式适合生产环境但学习和调试阶段有头模式能让你直观看到浏览器在做什么。如果这条命令能弹出一个浏览器窗口并打开百度说明 playwright-cli 装好了。3.2 安装 playwright-cli skillskill 是给 AI 看的说明书。安装命令playwright-cli install --skill agents这条命令会在当前目录下创建.agent目录把 skill 文件放进去。关键点在于你在哪个目录执行在用户目录比如C:\Users\你的用户名执行skill 全局生效所有项目都能用。在项目目录执行skill 只在当前项目生效。我建议装在用户目录这样不用每个项目都装一遍。装完之后.agent目录里会有一个SKILL.md这就是 skill 的入口文档。启动 opencode 后用/skill命令能看到已安装的 skill 列表确认 playwright-cli skill 在里面。3.3 测试配置文件在项目里创建playwright.config.js// playwright.config.js module.exports { testDir: ./tests/e2e, timeout: 30000, retries: 1, use: { baseURL: http://192.168.26.132:8080, headless: true, screenshot: only-on-failure, video: retain-on-failure, }, projects: [ { name: chromium, use: { browserName: chromium } }, { name: firefox, use: { browserName: firefox } }, ], };这个配置里baseURL换成你自己的服务地址headless在调试时改成false方便观察。screenshot和video设为失败时保留方便排查。3.4 数据库重置脚本配置数据库重置程序我让模型根据测试文档生成。核心逻辑是连接测试库删除冗余数据插入预置数据。下面是一个 C 重置程序的配置片段示例实际代码让模型根据你的数据库结构生成// db_reset_config.h // 数据库重置配置执行前务必确认连接的是测试库 struct DbConfig { std::string host 127.0.0.1; int port 3306; std::string user test_user; std::string password test_password; std::string database oj_test; // 必须是测试库 }; // 重置策略先删后插 // 1. 清空 submissions、problems、users 表 // 2. 插入预置管理员 admin / vr.666666 // 3. 插入预置普通用户 testuser / test123456 // 4. 插入 3 道预置题目两数之和、反转字符串、质数判定这里我必须强调数据库重置程序是危险程序。执行前一定要确认database字段指向的是测试库不是生产库。我建议在程序里加一道确认比如要求输入YES才继续执行。另外重置程序不要放在生产环境的 CI 里自动跑只在你确认过的测试环境手动触发。3.5 skill 编排命令环境搭好之后在 opencode 里用 skill 编排测试。命令格式/playwright-cli web自动化测试文档.md 根据文档描述使用有头模式--headed完成 web 自动化测试每个操作之间停顿 1 秒先执行 TC-001 到 TC-010这条命令的意思是调用 playwright-cli skill读取测试文档按文档里的用例执行用有头模式操作间停顿 1 秒先跑前 10 条用例。分批执行是因为用例多了一次跑完时间长、不稳定出问题也不好定位。3.6 生成项目文档测试跑通之后让模型生成 README 和 DEPLOY 文档SPEC.md 根据文档描述和代码仓库内容编写 DEPLOY.md项目部署文档和 README.md项目介绍文档模型会读 SPEC 和代码生成两份文档。生成后建议找一台新机器从头部署一遍验证文档是否可行。这一步经常能发现依赖缺失、路径写错、环境变量没配等问题。4. 验证请求一次测试→重置→部署的完整动作配置写好了接下来要验证整条链路能不能跑通。我按测试→重置→部署的顺序演示一次完整动作。4.1 先重置数据库测试前先重置保证数据库干净。执行重置程序./db_reset --config db_reset_config.json --confirm YES执行完检查一下管理员账户在不在普通用户账户在不在预置题目是不是 3 道。可以用数据库客户端查SELECT COUNT(*) FROM users; -- 应该是 2 SELECT COUNT(*) FROM problems; -- 应该是 3 SELECT COUNT(*) FROM submissions; -- 应该是 0如果数量对不上说明重置程序有问题先修重置程序别急着跑测试。4.2 执行第一批测试用例在 opencode 里执行/playwright-cli web自动化测试文档.md 使用有头模式执行 TC-001 到 TC-010操作间停顿 1 秒你会看到浏览器窗口自动打开依次执行登录、注册、退出等操作。每条用例执行完opencode 会输出结果。如果某条用例失败它会给出失败原因。这里有个实际会遇到的问题opencode 执行 web 自动化测试时有时打开网页后就卡住了。我试过这时候按两次esc暂停任务然后输入继续执行它通常能接着跑。这个卡顿不是 playwright-cli 的问题是 AI 工具在等待页面加载状态时的判断延迟。4.3 验证测试结果第一批跑完后检查结果。通过的用例不用管失败的用例单独拎出来分析。比如 TC-005 注册成功用例失败可能是注册页面元素选择器变了或者用户名唯一性检查接口返回慢。让模型单独执行这条用例/playwright-cli web自动化测试文档.md 单独执行 TC-005使用有头模式输出详细日志单独执行时模型会输出更详细的步骤方便定位问题。4.4 测试通过后总结文档当一批用例都通过后让模型把执行步骤总结成文档将上述执行过程总结到 web自动化测试文档-playwright-cli.md这份总结文档和原始测试文档的区别是原始文档是设计用例总结文档是实际执行步骤。后续再跑测试直接按总结文档操作成功率更高。4.5 部署验证测试全通过后生成部署文档然后在新机器上验证SPEC.md 根据文档描述和代码仓库内容编写 DEPLOY.md 和 README.md拿到 DEPLOY.md 后找一台干净的云服务器按文档一步步部署。部署过程中遇到的问题比如依赖下载失败、端口占用、环境变量没配都记下来回头更新 DEPLOY.md。这一步是检验文档质量的最好方式。4.6 完整链路回顾一次完整动作是重置数据库 → 执行测试用例 → 分析失败用例 → 修复问题 → 重新执行 → 总结执行文档 → 生成部署文档 → 新机器验证部署。这条链路跑通一次之后后续每次迭代只需要重复重置→测试→修复这几步部署文档和测试总结文档可以复用。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一章列几个实际会遇到的报错以及怎么定位。5.1 401 错误报错长这样Error: 401 Unauthorized原因通常是 API Key 不对。检查三件事Key 是不是复制完整了有没有漏字符Key 是不是过期了Base URL 是不是写对了。TaoToken 的 Base URL 是https://taotoken.net/api注意结尾没有斜杠也不要加多余路径。如果 Key 和 URL 都对还是 401去控制台确认这个 Key 有没有被禁用或者额度是不是用完了。5.2 local proxy failed报错长这样Error: local proxy failed to connect这个通常出现在 AI 工具配置了本地代理但代理服务没启动或者端口不对。检查你的工具配置里有没有proxy相关设置。如果你没主动配代理可能是工具默认读取了系统代理。把代理设置清掉或者确认代理服务在运行。注意这里说的是工具自身的网络配置问题不是让你去搞什么网络工具就是检查配置项。5.3 reading choices 报错报错长这样TypeError: Cannot read properties of undefined (reading choices)这是模型返回格式不符合预期。常见原因是 Base URL 指向的接口不兼容 OpenAI 格式或者模型 ID 填错了。检查你的配置里base_url和model是否匹配。有些工具要求 Base URL 带/v1有些不带按你用的工具文档来。TaoToken 的接口是兼容 OpenAI 风格的如果工具要求/v1可以试https://taotoken.net/api/v1。5.4 OAuth 相关报错报错长这样Error: OAuth token expired or invalid如果你用的是 Claude Code 这类需要 OAuth 的工具可能是登录态过期了。重新走一遍登录流程或者检查配置文件里的 token 是不是还有效。有些工具支持 API Key 和 OAuth 两种方式如果你用的是 API Key确认配置里没有残留的 OAuth 设置干扰。5.5 playwright-cli 命令找不到报错长这样playwright-cli: command not found说明 playwright-cli 没装好或者没加到 PATH。重新执行npm install -g playwright/clilatest然后确认 npm 全局 bin 目录在 PATH 里。Windows 上可以用npm config get prefix看全局目录在哪把这个目录加到系统 PATH。5.6 skill 没生效现象是 AI 生成的 playwright-cli 命令参数不对或者不知道某些子命令。检查.agent目录在不在SKILL.md在不在。如果装在项目目录确认当前工作目录是项目根目录。如果装在用户目录确认 AI 工具能读取用户目录下的.agent。有些工具需要在配置里显式指定 skill 路径。5.7 数据库重置后测试还是失败如果重置后测试还是因为数据问题失败检查重置程序是不是真的连到了测试库。有时候配置里写的是测试库但环境变量覆盖了实际连到了别的库。在重置程序里加日志打印实际连接的 host、port、database确认无误再执行。6. 语义一致 CTA把这条链路用起来整条链路的核心是用 skill 让 AI 理解 playwright-cli 的用法用 playwright-cli 执行 web 自动化测试用数据库重置保证测试环境干净最后生成项目文档和部署文档。这套流程的价值在于把零散脚本收敛成可复用流程换个人接手也能跑起来。如果你要接入模型能力来驱动这条链路TaoToken 的 API Key 在控制台创建接入文档里有详细的参数说明。测试编排和失败分析这类任务建议用能力较强的模型生成命令的准确率更高。如果你要长期跑编码和 Agent 任务可以看看 Coding Plan适合持续性的开发场景。验证模型效果的话模型对话页面可以直接试。实际用下来这套流程最花时间的不是配置而是第一次跑测试用例时的趟坑阶段。每条用例都可能因为选择器、等待时间、数据状态出问题需要反复调整。但一旦趟完一遍把执行步骤总结成文档后续再跑就快很多。数据库重置程序一定要在测试环境验证充分确认它只动测试库。部署文档生成后找台新机器从头走一遍能发现不少隐藏问题。这套东西跑通之后你会发现 web 项目的测试和部署不再是负担而是一个可以重复执行的标准化流程。