用途：在 Payload 仓库中编写和运行 Playwright 视觉回归测试。这类测试是带 @visual 标签的普通 e2e 测试，用截图与已提交的基线 PNG 对比，而非仅断言 DOM，与普通 e2e 测试放在同一目录，无需单独注册。
主要能力与关键文件：test/__helpers/e2e/visual.ts 提供 visual() 辅助函数，自动打上 @visual 标签；test/__helpers/e2e/expectScreenshot.ts 负责截图并与基线对比；test/playwright.config.ts 配置 toHaveScreenshot.maxDiffPixelRatio 与 snapshotPathTemplate；.github/scripts/visual/find-visual-suites.mjs 扫描 test/**/e2e.spec.ts 自动发现含 @visual 的套件；run-visual-suites.sh 循环执行 pnpm test:e2e:prod:server:run:noturbo <suite> --grep @visual。
使用方式：优先用 visual() 而非 test()，并调用 expectScreenshot，可传 name（基线文件名）、target（局部 Locator）、mask（需遮蔽的非确定性元素）。基线存放于 test/<suite>/snapshots/e2e.spec.ts/<name>。对于 test.skip、test.only、test.fixme、test.describe 或自定义标签等 visual() 未覆盖的情况，可手动写 { tag: '@visual' }。
生成与运行：基线必须在固定 Playwright Docker 镜像内生成，先 pnpm docker:start，再 pnpm test:visual:update；单套件用 pnpm test:visual <suite> -- --update-snapshots。本地运行用 pnpm test:visual 或 pnpm test:visual <suite>，可追加 -- --headed 等参数。@visual 测试不会被 pnpm test:e2e / pnpm test 拾取，expectScreenshot 要求 PAYLOAD_TEST_PROD === 'true'。
限制与陷阱：不得在裸主机或用手动截图、浏览器工具、复制图片等方式生成基线，否则会因字体渲染差异在 CI 确定性失败；截图前应先断言页面已加载；非确定性内容需用 mask；表格中被遮蔽单元格仍可能影响列宽，可先注入 table-layout: fixed；CI 无自动更新快照的机器人评论，失败需本地复现后用 pnpm test:visual:update 更新并推送。