Codex × Playwright 端到端测试实战

Playwright 适合验证“用户能不能完成一条完整路径”，不适合替代所有单元测试。

教程目标

以“打开页面 → 操作表单 → 看到成功结果”为例，完成一条可重复运行的端到端测试。

开始前准备

• 应用在本地可以启动。
• 已确认测试账号、测试数据和外部服务不会影响生产环境。
• 项目已有 Playwright 时优先复用；没有时先审查引入成本。

第 1 步：让 Codex 只读盘点

请只读检查项目是否已经使用 Playwright。
列出配置文件、测试目录、启动命令、baseURL、浏览器项目、重试和 trace 设置。
同时确认测试会不会访问真实生产服务、真实支付或真实用户数据。
不要修改文件。

如果项目没有 Playwright，再让 Codex 给出最小接入方案，确认依赖、浏览器下载体积、CI 缓存和卸载方法后再安装。

第 2 步：定义用户路径

请把【目标功能】拆成一条最小 E2E 用户路径，先不要写代码。

输出：
1. 前置状态。
2. 用户操作。
3. 每一步可观察结果。
4. 需要准备和清理的数据。
5. 哪些外部依赖要 mock，哪些应使用测试环境真实服务。

第一条用例只验证一条主路径。登录、支付、邮件等高成本依赖应使用明确的测试环境或受控替身。

第 3 步：实现稳定定位器

请实现确认后的 Playwright 用例。

要求：
1. 优先使用 getByRole、getByLabel、getByText 或稳定的 data-testid。
2. 不使用依赖 DOM 层级的长 CSS 选择器。
3. 不用固定 sleep；等待用户可观察状态。
4. 测试数据可重复创建并在结束后清理。
5. 只修改本用例必要文件。

不要用 waitForTimeout 掩盖竞态问题。等待按钮可用、URL 变化、响应完成或结果区域出现。

第 4 步：本地验证与失败证据

先运行这一条 Playwright 用例，再运行相关测试集。
失败时保留错误、trace、截图或视频路径，先解释失败发生在哪一步，不要盲目提高超时时间。
最后展示 diff 和测试结果。

需要调试时，可以让 Codex根据项目脚本选择 headed 或 UI 模式，但不要把调试配置永久写进 CI。

第 5 步：接入 CI

CI 至少需要安装依赖与浏览器、启动应用、等待服务就绪、运行测试、失败时上传报告。密钥通过 CI Secret 注入，测试产物不能包含 Cookie、Token 或真实用户数据。

常见失败分支

• 本地通过、CI 失败：检查字体、时区、端口、浏览器版本和并发数据冲突。
• 定位器偶发找不到：检查无障碍名称和异步状态，不要先加 sleep。
• 测试互相污染：每条用例使用独立数据并清理。
• 截图泄露信息：改用脱敏测试账号并限制产物保存周期。

验收结果

1. 用例描述真实用户行为，不依赖实现细节。
2. 定位器稳定，没有固定等待。
3. 测试数据与生产隔离且可清理。
4. 本地最小用例和相关测试集都有结果。
5. CI 失败能留下 trace 或报告，产物不泄露秘密。

下一篇看：让 Codex 为现有代码补测试。