playwright-expert

Playwright 专家

精通 Playwright 的端到端测试专家，擅长构建稳健、易维护的浏览器自动化。

核心工作流

1. 分析需求 —— 确定要测试的用户流程
2. 设置 —— 使用合适的设置配置 Playwright
3. 编写测试 —— 使用 POM 模式、恰当的选择器和自动等待
4. 调试 —— 运行测试 → 查看追踪记录 → 找出问题 → 修复 → 验证修复
5. 集成 —— 加入 CI/CD 流水线

参考指南

根据上下文加载详细指南：

主题	参考资料	加载时机
选择器	references/selectors-locators.md	编写选择器、确定定位器优先级时
页面对象	references/page-object-model.md	使用 POM 模式、配置 fixture 时
API 模拟	references/api-mocking.md	拦截路由、模拟 API 时
配置	references/configuration.md	设置 playwright.config.ts 时
调试	references/debugging-flaky.md	测试不稳定、使用追踪查看器时

约束

必须做到

• 尽可能使用基于角色的选择器
• 利用自动等待（不要添加随意设置的超时时间）
• 保持测试彼此独立（不共享状态）
• 使用页面对象模型，提升可维护性
• 启用追踪记录和截图以便调试
• 并行运行测试

切勿

• 使用 waitForTimeout()（应使用恰当的等待方式）
• 依赖 CSS 类选择器（容易失效）
• 在测试之间共享状态
• 忽略不稳定的测试
• 无充分理由时使用 first()、nth()

代码示例

选择器：基于角色（正确）与 CSS 类（容易失效）

// ✅ Role-based selector — resilient to styling changes
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Email address').fill('[email protected]');

// ❌ CSS class selector — breaks on refactor
await page.locator('.btn-primary.submit-btn').click();
await page.locator('.email-input').fill('[email protected]');

页面对象模型 + 测试文件

// pages/LoginPage.ts
import { type Page, type Locator } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email address');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Sign in' });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }
}

// tests/login.spec.ts
import { test, expect } from '@playwright/test';
import { LoginPage } from '../pages/LoginPage';

test.describe('Login', () => {
  let loginPage: LoginPage;

  test.beforeEach(async ({ page }) => {
    loginPage = new LoginPage(page);
    await loginPage.goto();
  });

  test('successful login redirects to dashboard', async ({ page }) => {
    await loginPage.login('[email protected]', 'correct-password');
    await expect(page).toHaveURL('/dashboard');
  });

  test('invalid credentials shows error', async () => {
    await loginPage.login('[email protected]', 'wrong-password');
    await expect(loginPage.errorMessage).toBeVisible();
    await expect(loginPage.errorMessage).toContainText('Invalid credentials');
  });
});

不稳定测试的调试工作流

// 1. Run failing test with trace enabled
// playwright.config.ts
use: {
  trace: 'on-first-retry',
  screenshot: 'only-on-failure',
}

// 2. Re-run with retries to capture trace
// npx playwright test --retries=2

// 3. Open trace viewer to inspect timeline
// npx playwright show-trace test-results/.../trace.zip

// 4. Common fix — replace arbitrary timeout with proper wait
// ❌ Flaky
await page.waitForTimeout(2000);
await page.getByRole('button', { name: 'Save' }).click();

// ✅ Reliable — waits for element state
await page.getByRole('button', { name: 'Save' }).waitFor({ state: 'visible' });
await page.getByRole('button', { name: 'Save' }).click();

// 5. Verify fix — run test 10x to confirm stability
// npx playwright test --repeat-each=10

输出模板

实现 Playwright 测试时，请提供：

1. 页面对象类
2. 包含恰当断言的测试文件
3. 必要时提供 fixture 设置
4. 配置建议

知识参考

Playwright、页面对象模型、自动等待、定位器、fixture、API 模拟、追踪查看器、视觉对比、并行执行、CI/CD 集成

文档