2026年8月13日

playwright-qa 技能 — 前端任务的真实浏览器验证

Datarim 的 playwright-qa 技能如何在 /dr-qa 期间触发真实浏览器检查、自动解析正确的工具,并将截图和 trace 存储为可审计的证据。

前端代码变更很容易在无声无息中被破坏。一次 CSS 调整会改变布局,一个 PHP 模板会渲染出损坏的 HTML,而唯一能捕获这些问题的测试是视觉测试。playwright-qa 技能定义了在 Datarim /dr-qa 阶段中,真实浏览器检查何时以及如何运行。

检测:按变更文件选择启用

该技能并非始终处于活动状态。只有当任务的变更文件集包含至少一个前端文件时才会触发——.html、.css、.tsx、.vue、.svelte,以及正文匹配 HTML 标记模式的 PHP 文件。检测基于 origin/main 的 git diff --name-only 运行,可通过 DATARIM_FRONTEND_BASE 配置。仅涉及后端的任务永远不会触发浏览器检查。

工具解析链

该技能不假定使用固定工具。dev-tools/detect-playwright-tooling.sh 处的检测脚本会依次执行五步链。首先检查 DATARIM_PLAYWRIGHT 覆盖环境变量。如果不存在,则探测 PATH 上是否有 playwright 二进制文件。如果缺失,则检查是否存在 Playwright MCP 服务器。作为第四步,它会在 BROWSER、PLAYWRIGHT_BROWSER_PATH 或 CHROME_PATH 中查找浏览器可执行文件。当整条链耗尽且无匹配时,结果为 none——这是第五个也是最终状态,记录为一项发现,而非硬性失败。

有头与无头模式

默认情况下,检查以无头模式运行。向 /dr-qa 传入 --headed 会请求可见的浏览器窗口,当没有可用显示时优雅回退到无头模式。更严格的 --headed-strict 标志会在 $DISPLAY 缺失时完全中止检查——适用于需要可见浏览器的本地运行。相同的模式可通过 qa_browser_mode frontmatter 键按任务配置。

产物与并发

每次检查都会将输出写入 datarim/qa/playwright-{ID}/run-{ISO-timestamp}/ 下:一张截图、一个 Playwright trace 包、一份合并日志,以及一个 summary.md,其中记录所用工具、有头模式、退出码、发现项和目标 URL。latest/ 符号链接始终指向最近一次运行。当多个代理在同一任务上并行运行 /dr-qa 时,它们会通过 flock 在按任务的锁文件上串行化,因此产物永远不会相互覆盖。

请参阅 playwright-qa 参考中的完整技能契约,或阅读Datarim 是什么以了解更全面的图景。