用途：编写和修复基于 @playwright/test 1.63 的端到端测试与视觉回归测试，包括 playwright.config.ts、spec 文件与 toHaveScreenshot 快照。
主要能力：配置中可定义多个 project（如 desktop 与 mobile，移动端使用设备描述符）并共用一个 dev server；webServer.url 需在测试前返回 2xx 至 4xx，port 已弃用，首次 next dev 编译较慢，timeout 建议 120 秒以上。spec 中优先使用 getByRole、getByLabel、getByText 而非 CSS 选择器，使用可重试的 web-first 断言（await expect(locator)...），避免 waitForTimeout，改为等待定位器状态或响应。可用 test.skip 按 project 或平台跳过。
快照：toHaveScreenshot 首次运行写入基线并失败，需审查后重跑；用 npx playwright test --update-snapshots 更新。文件名带浏览器、project 与平台后缀，如 home-desktop-linux.png。渲染受操作系统、字体与 GPU 影响，macOS 基线在 Linux 会失败，建议仅在 CI 镜像或对应 Playwright Docker 镜像中生成与更新基线，只提交 *-linux.png，并用 test.skip(process.platform !== 'linux', ...) 让其他平台跳过。可用 maxDiffPixels、animations: 'disabled'、mask、maskColor、stylePath、fullPage 等选项，共享默认值写在 expect.toHaveScreenshot 下。
时钟与动效：page.clock.setFixedTime 冻结 Date.now() 与 new Date()，install() 伪造定时器与 rAF，配合 runFor、fastForward、pauseAt、resume；page.clock 作用于整个浏览器上下文。可用 reducedMotion: 'reduce' 断言减弱动效路径或稳定截图。
遮罩与 WebGL：对 canvas、video、头像、计数器、嵌入内容等非确定性元素使用 mask 与 maskColor。WebGL 像素比对易受 GPU、驱动与帧时序影响，优先遮罩 canvas 并断言周边 DOM，或让应用渲染静态帧后等待就绪标记再截图；软件 GL 方案未经验证，需在 CI 确认。
CI：retries: 2、workers: 1 或较小值、forbidOnly: true、trace: 'on-first-retry'；用 npx playwright install --with-deps chromium 安装浏览器；失败时上传 playwright-report/ 与 test-results/。重试会掩盖不稳定的截图，应先修复非确定性。作者 Ender Puentes（与 Claude Code），来源 playwright.dev。