# Playwright 视觉回归：忽略动态头像时间，仍能抓住按钮错位

Playwright Test真实截图比较验证局部mask稳定，按钮36px位移失败，并产生expected/actual/diff。

## 环境

- Node.js 24+；进入 reference 后 npm install。依赖为锁定的直接版本，首次安装需要网络。
- 执行 npx playwright install chromium；也可用 CHROME_BIN 指向你自己已安装的 Chromium。Mac生成的截图基线不能保证跨操作系统像素相同。

## 启动

~~~sh
cd reference
npm install
npx playwright install chromium
# 另一个终端在reference运行 python3 -m http.server 8787
EXERCISE_URL=http://127.0.0.1:8787 npx playwright test --config playwright.config.cjs --update-snapshots
EXERCISE_URL=http://127.0.0.1:8787 npx playwright test --config playwright.config.cjs
EXERCISE_URL=http://127.0.0.1:8787 EXERCISE_BROKEN=1 npx playwright test --config playwright.config.cjs
~~~

## 七步操作

1. 固定视口字体

页面有静态导出按钮和三张指标卡，右上角头像文字与时间每次变化。先固定浏览器、视口与系统字体，避免环境差异盖过真正的布局问题。

2. 建立截图基线

使用 Playwright Test 的 toHaveScreenshot 建立 expected 基线。首次生成后需人工确认页面正确；自动更新基线不能当作已经消除了回归。

3. 定位动态区域

只定位 .dynamic 这块时间与头像区域。基线和后续截图用同一 mask，按钮、标题与指标卡都保持可比较。

4. 屏蔽后再比较

换一份 seed 和时间重新访问，原生截图断言仍通过，证明动态区域不会造成误报。没有把整页或整个卡片遮住。

5. 注入按钮错位

给导出按钮增加36px水平偏移，再运行相同截图断言。原生测试必须失败；如果依旧通过，说明屏蔽范围或容差过宽。

6. 读取真实Diff

打开生成的 expected、actual、diff 三份图。差异图由 Playwright 真实像素比较产生，可定位按钮偏移，未用手绘色块伪造。

7. 保留窄屏基线

保存桌面与窄屏各自基线，修改后在相同视口复跑。下载包保留原创页、测试和实际 diff；动态 mask 验证的是局部比较，不证明所有浏览器视觉完全一致。

## 目录身份

- starter：待完成的任务接口与原创输入，TODO不是已完成实现。
- reference：作者原生完成参考和实际产物。records.json/browser-result.json为本地实测记录，不是AI助手回复。
- TASK.md：可交给相应AI助手的原始任务合同。该助手账号生成会话未运行。

## 依赖与许可

原创教学代码以MIT许可提供。第三方项目、模型及浏览器遵循其自身许可。第三方依赖由本地安装获取，不包含node_modules、模型权重、WASM运行时、数据库、缓存或凭据。

## 官方依据

- https://playwright.dev/docs/test-snapshots