用途：在编写、调试或评审 Web 应用（尤其 SPA）的 Playwright 测试时提供规范，解决测试不稳定、缓慢或脆弱的问题。核心原则是测试用户能看到和做到的事：用户无法通过角色或文本找到的元素，测试也不应依赖。
主要能力：给出定位器优先级（getByRole、getByLabel、getByPlaceholder、getByText、getByAltText，最后才是 getByTestId），说明多匹配时用 .first()、.last()、.nth()、.filter() 或链式作用域消歧；讲解自动等待与显式等待（expect 断言、waitForURL、waitForResponse、Promise.all 模式），并明确禁止 waitForTimeout；介绍软断言 expect.soft() 与 addLocatorHandler 处理弹窗遮罩。
使用方式：按“识别用户行为→定位→操作→断言可见结果→稳定化”流程编写。常用命令保持原样：npx playwright test、npx playwright test --debug、npx playwright show-trace trace.zip、npx playwright codegen localhost:3000、npx playwright show-report。质量分三层：可靠（无 flake）、快速（并行、复用认证）、可维护（页面对象、夹具）。
适用场景：SPA 端到端测试、表单与列表交互、加载状态与 API 响应等待、CI 失败排查。
限制：资料未提供具体安装步骤、版本要求、收费信息或平台支持范围；测试结构、性能、调试与 CI 的详细内容指向 reference 目录，正文未展开。