playwright-best-practices

此技能为在 Claude Code 等基于 CLI 的代理环境中开发和维护 Playwright 端对端测试提供了标准化框架。它专为需要编写稳健、易维护且具备上下文感知测试套件的软件工程师和自动化测试专家而设计。该技能强调以用户为中心的测试模式，确保测试对 UI 结构变化具有弹性，从而减少测试代码的脆弱性。

• 优先采用具弹性的定位策略，强调使用 getByRole、getByLabel 和 getByTestId 等面向用户的属性，而非脆弱的 CSS 选择器或 XPath 表达式。

• 强制执行基于 web-first 的断言模式，使用 await expect(locator)，确保测试具备自动等待和重试机制，这对动态 Web 应用程序至关重要。

• 推广架构最佳实践，包括测试隔离、通过 storageState 重用认证状态，以及使用 Fixtures 进行设置和清理任务，取代手动的 beforeEach 钩子。

• 集成 CLI 特有的优化规则，例如强制使用 line 或 dot 等最小化报告器，防止测试执行期间的输出淹没 LLM 上下文窗口。

• 通过鼓励每项测试独立创建数据以及稳健的网络模拟策略，确保测试的确定性。

• 始终优先使用语义化的定位器（如角色、标签和占位符），使测试意图与无障碍标准对齐。

• 避免使用硬编码的等待（如 page.waitForTimeout），应改用自动等待定位器和 web-first 断言。

• 配置 playwright.config.ts 以自动检测 CI 或 CLAUDE 环境变量，并切换至最小化报告模式。

• 使用页面对象模型 (POM) 组织代码，将定位器逻辑与测试场景分离，以便在 UI 发生变更时更轻松地进行维护。

• 通过避免共享状态并实现适当的清理过程，确保测试之间的真正隔离，使测试环境保持整洁状态。