playwright-best-practices

Playwright 最佳实践

CLI 上下文：防止上下文溢出

通过 Claude Code 或任何 CLI Agent 运行 Playwright 测试时，始终使用精简报告器，避免冗长的输出占用上下文窗口。

通过 CLI 运行测试时使用 --reporter=line 或 --reporter=dot。 在 playwright.config.ts 中配置：当设置了 CI 或 CLAUDE 环境变量时，默认使用精简报告器——配置代码片段请参见 playwright-patterns.md。

定位器优先级（从最可靠到最不可靠）

始终优先使用面向用户的属性：

1. page.getByRole('button', { name: 'Submit' }) — 无障碍角色
2. page.getByLabel('Email') — 表单控件标签
3. page.getByPlaceholder('Search...') — 输入框占位符
4. page.getByText('Welcome') — 可见文本（非交互元素）
5. page.getByAltText('Logo') — 图片替代文本
6. page.getByTitle('Settings') — 标题属性
7. page.getByTestId('submit-btn') — 显式测试约定
8. CSS/XPath — 最后选择，尽量避免

核心规则

• 优先使用 Web 断言：始终使用 await expect(locator).toBeVisible()，不要使用 expect(await locator.isVisible()).toBe(true) — Web 优先匹配器会自动等待并重试
• 测试隔离：每个测试都创建自己的数据；测试之间绝不共享状态
• 复用身份验证状态：通过 setup project + storageState 保存已验证身份的状态；不要在每个测试中都通过 UI 登录
• 优先使用 Fixtures 而非 beforeEach：Fixtures 封装设置和清理，按需运行，并且可以组合

反模式

• page.waitForTimeout(ms) — 改用自动等待的定位器
• page.locator('.class') — 改用 role/label/testid
• XPath 选择器 — 不可靠，应使用面向用户的属性
• 测试之间共享状态 — 每个测试都创建自己的数据
• 每个测试都通过 UI 登录 — 使用 setup project + storageState
• 不使用 await 的手动断言 — 改用 Web 优先断言
• 硬编码等待 — 依赖 Playwright 的自动等待
• CI/Agent 中使用默认报告器 — 使用 --reporter=line 或 --reporter=dot

检查清单

• 定位器使用 role/label/testid，而非 CSS 类或 XPath
• 所有断言都使用 await expect() Web 优先匹配器
• 页面对象在构造函数中定义定位器
• 不使用 page.waitForTimeout() — 改用自动等待
• 测试彼此隔离 — 不共享状态
• 通过 setup project 复用身份验证状态
• 在导航前设置网络模拟
• 每个测试单独创建测试数据，或通过 Fixtures 创建
• 为复杂流程添加调试日志
• 在 CI/Agent 环境中使用精简报告器（line/dot）

页面对象模型、Fixtures、网络模拟和配置示例请参见 playwright-patterns.md。