Playwright 端到端测试实战指南
以官方 TodoMVC 演示页面为例，说明 Playwright 端到端测试流程：环境搭建、编写与运行测试、UI 模式时间旅行调试，以及视觉回归检测。
本文依据官方文档整理，未执行运行验证或性能基准。代码片段展示局部用法，业务函数、数据和环境需按项目补齐；版本与配置以所引文档为准。
直接回答：用 Playwright 做端到端测试的标准路径是：安装初始化 → 编写测试脚本 → 用 UI 模式调试 → 接入视觉回归检测。本文基于官方演示页面给出示例，不声称已在你的项目中完整运行。
准备演示项目
使用 Playwright 官方 TodoMVC 演示页面 https://demo.playwright.dev/todomvc/，无需虚构仓库地址或假定它在3000端口启动。该公开页面仅用于少量功能学习，不能进行高并发压测；CI 应使用自行部署且版本固定的测试应用。
安装与初始化 Playwright
npm init playwright@latest
向导会生成 playwright.config.ts、tests/ 目录并提示安装浏览器：
npx playwright install
演示配置：
import { defineConfig } from "@playwright/test";
export default defineConfig({
use: { baseURL: "https://demo.playwright.dev" },
});
第一个测试
tests/todo.spec.ts：
import { test, expect } from "@playwright/test";
test("可以新增并完成一条待办", async ({ page }) => {
await page.goto("/todomvc/");
await page.getByPlaceholder("What needs to be done?").fill("写测试");
await page.keyboard.press("Enter");
await expect(page.getByText("写测试")).toBeVisible();
await page.locator(".todo-list li").getByRole("checkbox").check();
await expect(page.locator(".todo-list li")).toHaveClass(/completed/);
});
npx playwright test 无头跑完；npx playwright test --headed 能看到真实浏览器操作过程。
UI 模式：时间旅行调试
npx playwright test --ui
UI 模式是 Playwright 的杀手级体验：左侧用例树，右侧逐步骤回放——每一步都有当时的 DOM 快照、网络请求和控制台输出。测试失败时不用再对着日志脑补现场，直接拖动时间轴看"哪一步开始不对"。
视觉回归检测
功能断言抓不到"样式悄悄变了"这类问题，交给视觉对比：
test("首页视觉基线", async ({ page }) => {
await page.goto("/todomvc/");
await expect(page).toHaveScreenshot("home.png");
});
首次缺少基线时测试会写出图像并报告失败，需要人工审阅后建立基线；之后才比较差异。操作系统、浏览器版本、字体与动态数据须一致。基线更新用 npx playwright test --update-snapshots——更新前务必人工核对 diff。
常见问题（FAQ）
Q：测试在 CI 上失败但本地通过？
A：可能是时序、依赖或资源差异。CI 机器慢，动画/接口耗时不同。消灭手写 sleep、改用自动等待断言；CI 上开启 trace 收集，失败时下载 Trace Viewer 回放。
Q：视觉回归的阈值怎么定？
A：按实际截图和允许变化区域评估，不能直接接受统一1%误差。先固定渲染环境，必要时mask动态区域，避免掩盖小而关键的视觉回归。
Q：webServer 每次起服务太慢？
A：只有测试自行部署的应用时才配置 webServer 的 command/url；用 reuseExistingServer: !process.env.CI 可以本地复用，CI 不复用旧实例。官方在线演示不需要 webServer。
官方参考
资料核对日期：2026-09-29。
