用途：为编码智能体提供一套精简、有明确取舍的 Playwright 测试编写指南，目标是让测试可读、相互隔离且稳定。适用于 CI 运行，也适用于作为生产环境监控。
主要能力：给出定位器优先级（getByRole > getByLabel/getByPlaceholder/getByText > getByTestId > CSS/XPath）、web-first 自动重试断言、禁止硬等待（不用 waitForTimeout，改用 waitForURL/waitForLoadState/waitForResponse，避免 networkidle）、测试隔离与独立、一个测试只覆盖一个功能、复用登录态（storageState + setup project）等核心规则。
使用方式：按任务类型查阅 references/ 下的参考文件，如 locators、assertions、waiting、test-structure、config、auth、network、debugging、flakiness、ci、test-data、forms、interactions、files、iframes、multi-context、mobile、clock、visual、tags-annotations、console-errors、global-setup、error-states。无 GUI 的智能体工作流：用 playwright-cli open <url> 与 playwright-cli snapshot 从实时页面读取可访问性树来发现定位器；运行 npx playwright test path/to/file.spec.ts 并阅读 stdout；失败时查看 test-results/.../error-context.md（Playwright ≥ 1.60）；用 --trace on 生成 trace.zip；用 npx playwright test path/to/file.spec.ts --debug=cli 后台暂停并打印会话名，再 playwright-cli attach <session-name> 配合 snapshot、step-over、console error、network、eval 逐步排查。安装 agent CLI：npm install -D @playwright/cli，通过 npx playwright-cli 调用，或 npm install -g @playwright/cli 全局安装。
适用场景：使用 @playwright/test 测试运行器与 TypeScript 的项目（示例为 .spec.ts，API 同样适用于 JavaScript），导入方式为 import { test, expect } from '@playwright/test'。
限制：不针对独立的 playwright 自动化库（无测试运行器、fixtures 或自动重试断言）；--ui、--debug（Inspector）、show-trace 等交互式 GUI 无法被智能体驱动；相关原语较新且有版本门槛，需检查 npx playwright --version 与 playwright-cli --version 并更新。