playwright-e2e-init

Playwright E2E 测试初始化

为 Next.js 和 React 应用设置端到端测试所需的 Playwright。

适用场景

• 为 Next.js 项目添加 E2E 测试
• 设置浏览器自动化测试
• 为关键流程创建用户流程测试
• 将 E2E 测试集成到 CI/CD 流水线

功能

1. 安装 Playwright 和浏览器
2. 创建配置（playwright.config.ts）
3. 设置测试目录（e2e/）
4. 为常见流程创建示例测试
5. 添加用于运行测试的 Bun 脚本
6. 更新 CI/CD 以运行 E2E 测试

快速开始

提示词示例：

Add Playwright E2E tests to this project

或者明确说明需求：

Set up E2E tests for the authentication flow

安装

bun add -D @playwright/test
bunx playwright install chromium

配置

playwright.config.ts

import { defineConfig, devices } from "@playwright/test";

export default defineConfig({
  testDir: "./e2e",
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [["html", { open: "never" }], ["list"]],
  use: {
    baseURL: "http://localhost:3000",
    trace: "on-first-retry",
    screenshot: "only-on-failure",
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
  ],
  webServer: {
    command: "bun run dev",
    url: "http://localhost:3000",
    reuseExistingServer: !process.env.CI,
    timeout: 120 * 1000,
  },
});

测试结构

e2e/
├── home.spec.ts          # Homepage tests
├── auth.spec.ts          # Authentication flow
├── navigation.spec.ts    # Navigation tests
└── fixtures/
    └── test-data.ts      # Shared test data

示例测试

针对代码库中的实际路由生成项目专属测试。Playwright 标准测试模式（导航、身份验证流程、表单提交、测试固件）已在 https://playwright.dev/docs/writing-tests 中详细说明。内联测试应聚焦于项目的具体页面和关键用户流程，而非通用示例。

Bun 脚本

添加到 package.json：

{
  "scripts": {
    "e2e": "playwright test",
    "e2e:ui": "playwright test --ui",
    "e2e:headed": "playwright test --headed",
    "e2e:debug": "playwright test --debug",
    "e2e:report": "playwright show-report"
  }
}

CI/CD 集成

GitHub Actions

添加到 CI 工作流：

- name: Install Playwright Browsers
  run: bunx playwright install --with-deps chromium

- name: Run E2E tests
  run: bun run e2e
  env:
    CI: true

- name: Upload Playwright Report
  uses: actions/upload-artifact@v4
  if: always()
  with:
    name: playwright-report
    path: playwright-report/
    retention-days: 7

最佳实践

• 将 E2E 测试聚焦于关键用户流程：身份验证、核心功能、付款/结账、错误处理。
• 使用 data-testid 属性作为选择器，不要依赖 CSS 类或文本内容。
• 使用页面对象模型封装可复用的页面交互（e2e/pages/）。
• 保持测试相互独立：每个测试自行设置和清理状态。
• 使用 test.extend 测试固件进行共享设置（已通过身份验证的会话、预置数据）。

故障排查

测试超时

在配置中增加超时时间：

timeout: 60000, // 60 seconds

找不到元素

使用 waitFor：

await page.waitForSelector('[data-testid="element"]');

不稳定的测试

添加重试并使用 toPass：

await expect(async () => {
  await expect(page.locator("text=Success")).toBeVisible();
}).toPass({ timeout: 10000 });

与其他技能集成

技能	集成方式
testing-cicd-init	首先设置单元测试
testing-expert	提供测试模式
debug	排查不稳定的测试和失败的浏览器流程