该技能是一套面向编码智能体的 Playwright 测试最佳实践集合，提供精简、有倾向性的指导，目标是让 Playwright 测试可读、相互隔离且稳定。它围绕 Playwright 的智能体 CLI（playwright-cli，包 @playwright/cli）及其无 GUI 调试流程构建，由 Checkly 维护；同样的实践既适用于在 CI 中运行测试，也适用于作为生产监控运行。
适用范围：全部指导均假设使用 @playwright/test 测试运行器与 TypeScript，涉及其 test、fixtures、projects、config 和 web-first expect。示例为 TypeScript（.spec.ts），相同 API 在 JavaScript 中同样可用。它不针对独立的 playwright 自动化库（该库没有测试运行器、fixtures 或自动重试断言）。导入方式为 import { test, expect } from '@playwright/test'。
智能体 CLI 是该技能的亮点。Playwright 的智能体 CLI——playwright-cli，包名 @playwright/cli——是一个独立的、令牌高效的、无 GUI 的浏览器，可逐条命令驱动，用于发现定位器和单步调试失败测试。它区别于标准的 npx playwright CLI，下述智能体工作流全程依赖它。
核心规则（始终适用）：
- 定位器优先级：优先使用面向用户的定位器——getByRole > getByLabel / getByPlaceholder / getByText > getByTestId > CSS/XPath。CSS/XPath 会把测试绑定到实现细节，容易失效。
- Web-first 断言：使用可自动重试的 expect(locator).toBeVisible() / toHaveText() 等。绝不要对手动取出的单次值做断言（如先 innerText() 再 toBe）。
- 不用硬等待：绝不使用 waitForTimeout()。信任自动等待的动作与 web-first 断言；需要显式等待时使用 waitForURL / waitForLoadState / waitForResponse。避免 networkidle。
- 隔离且独立：每个测试自行建立状态，可任意顺序、并行运行，测试之间不互相依赖。状态应通过 setup 中的 API 准备，而非经由 UI。
- 每个测试聚焦一个功能：若一个测试的断言跨越多个功能，应拆分。保持测试简短聚焦。
- 复用认证而非重复登录：只登录一次，持久化 storageState，通过 setup 项目在各测试间复用。
参考文件路由表：技能按任务类型加载 references/ 下的对应文件，包括定位器、断言、等待、测试结构、配置、认证、网络模拟、调试、不稳定测试、CI、测试数据、表单、交互、文件上传下载、iframe、多上下文、移动端、时钟、视觉回归、标签注解、控制台错误、全局 setup、错误状态等主题，每个参考文件末尾附有指向完整 /learn 文章的链接以便深入。仅在任务需要时才加载对应参考文件。
智能体工作流（无 GUI）：--ui、--debug（Inspector）、show-trace 等交互式工具是智能体无法驱动的 GUI，应改用非交互信号编写与调试。建议安装 playwright-cli（npm install -D @playwright/cli，通过 npx playwright-cli 运行，或全局安装 npm install -g @playwright/cli 后直接调用），并用 playwright-cli --version 确认；没有它一切仍可运行，但会失去检查/验证循环，只能靠猜测。
编写阶段——发现而非猜测：从实时页面读取定位器，而不是从源码猜。playwright-cli open <url> → playwright-cli snapshot 打印可访问性树，即驱动 getByRole/getByLabel 的角色与可访问名称，据此直接编写面向用户的定位器。
运行与调试：运行并阅读 stdout（npx playwright test path/to/file.spec.ts），报告器会打印失败的断言与调用日志；在 expect 失败时 Playwright 会把失败瞬间页面的 aria 快照写入 test-results/.../error-context.md（Playwright ≥ 1.60），可打开查看实际渲染内容；用 --trace on 把 trace.zip 写入 test-results/ 以供检查；用 playwright-cli 无 GUI 实时单步：后台运行 npx playwright test path/to/file.spec.ts --debug=cli，它会暂停并打印会话名，然后 playwright-cli attach <session-name> 并驱动：snapshot（页面状态与元素引用）、step-over、console error、network、eval 等，检查定位器未解析或实际渲染的原因后修复并重跑。修复根因（通常是定位器、缺失的 web-first 断言或硬等待）后重跑直至通过，不要用重试掩盖不稳定。
保持版本更新：这些原语较新且受版本限制，应检查 npx playwright --version 与 playwright-cli --version，落后时更新两个包。