playwright

Playwright 自动化测试编写规范：构建高稳定性（Flaky-Free）的测试体系

1. 核心原则：为何测试会失败？

在制定规范前，需明确 Playwright 测试失败的三大核心根因。编写"高成功率"测试的本质，就是通过规范消除这三个变量：

竞态条件 (Race Conditions)

脚本执行速度快于页面渲染速度（如点击了尚未绑定事件的按钮）。

DOM 易变性 (DOM Volatility)

页面结构或样式变化导致选择器失效。

环境不确定性 (Environmental Flakiness)

网络延迟、API 500 错误或第三方服务宕机。

本规范将围绕**"确定性执行 (Deterministic Execution)"**这一目标展开。

2. 目录结构与命名规范 (TypeScript)

采用**领域驱动（Domain-Driven）**结构，将测试与业务逻辑解耦。推荐使用 TypeScript 以获得强类型支持，这直接关联到代码维护的稳定性。

2.1 推荐目录结构

tests/
├── e2e/
│   ├── auth.setup.ts            # 全局认证设置（生成 storageState）
│   ├── checkout/                # 业务模块目录
│   │   ├── guest-checkout.spec.ts
│   │   └── payment-flow.spec.ts
│   └── dashboard/
│       └── analytics.spec.ts
├── fixtures/                    # 自定义测试夹具 (Dependency Injection)
│   ├── db-fixture.ts            # 数据库操作封装
│   └── page-fixture.ts          # Page Object 自动注入
├── pages/                       # Page Object Models (POM)
│   ├── CheckoutPage.ts
│   └── components/              # 可复用组件 (如 DatePicker, Modal)
├── test-data/                   # 静态测试数据
├── playwright.config.ts         # 全局配置
└── .eslintrc.json               # 强制代码规范配置

2.2 命名规范

• 文件命名：使用 kebab-case，后缀为 .spec.ts。例如 user-login.spec.ts。
• 类命名 (POM)：使用 PascalCase。例如 LoginPage, ShoppingCartPage。
• 测试标题：必须表达业务价值而非操作细节。
  • ❌ test('click button and check div')
  • ✅ test('should display order confirmation after successful payment')

3. 高稳定性选择器策略 (Selector Strategy)

稳定性黄金法则：测试应当像用户一样通过"视觉"和"内容"来寻找元素，严禁依赖页面内部实现（CSS 类名、XPath）。

3.1 优先级金字塔

请严格按照以下顺序选用 Locator：

page.getByRole() (最高优先级)

理由：它是最稳定的选择器。它模拟用户和辅助技术（Screen Readers）的交互。如果页面样式变了但功能没变（例如"登录"按钮变成了一个图标但 ARIA 角色还是 button），测试依然通过。

示例：

await page.getByRole('button', { name: 'Submit' }).click();

page.getByText()

理由：适用于非交互性文本内容的验证。

示例：

await expect(page.getByText('Welcome, User')).toBeVisible();

page.getByTestId() (特定场景)

理由：当元素没有任何语义（如纯 div 容器）且必须定位时使用。需在前端代码中添加 data-testid 属性。