Claude Code E2E测试全实战：Playwright MCP到自愈测试流水线

flowchart LR
    A[开发者提交代码] --> B[Claude Code 启动 Playwright MCP]
    B --> C{Planner Agent<br/>规划测试路径}
    C --> D[Generator Agent<br/>生成测试代码]
    D --> E[Healer Agent<br/>修复失败用例]
    E --> F[测试报告]
    F -->|通过| G[合并代码]
    F -->|失败| E

# 在项目根目录
npm init -y
npm install -D @playwright/test
npx playwright install chromium

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest"
      ]
    }
  }
}

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--headed"
      ]
    }
  }
}

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": [
        "@playwright/mcp@latest",
        "--browser", "chromium",
        "--viewport-size", "1440,900"
      ]
    }
  }
}

> 请启动浏览器并访问 https://example.com，告诉我页面标题

浏览器已启动，页面标题为 "Example Domain"
页面包含一个标题 "Example Domain" 和一段说明文字

# 确认 Playwright MCP 包存在
npm view @playwright/mcp version
# 如果不存在，使用完整路径
npx -y @playwright/mcp@latest

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "PLAYWRIGHT_CHROMIUM_SANDBOX": "1"
      }
    }
  }
}

# 安装 WSL 依赖
sudo apt-get install -y libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1 libasound2

- navigation "Main"
  - link "Home"
  - link "Products"
  - link "About"
- main
  - heading "Welcome to Our Store" [level=1]
  - textbox "Search products..." [ref=s1e3]
  - button "Search" [ref=s1e4]
  - list
    - listitem
      - article
        - heading "Product A" [level=2]
        - text "$29.99"
        - button "Add to Cart" [ref=s1e8]
    - listitem
      - article
        - heading "Product B" [level=2]
        - text "$49.99"
        - button "Add to Cart" [ref=s1e12]

请启动浏览器，访问 http://localhost:3000，获取页面快照，
列出所有可交互元素，并尝试完成一次完整的用户注册流程

1. browser_navigate → http://localhost:3000
2. browser_snapshot → 获取页面结构
3. browser_click → 点击 "Sign Up" 按钮 [ref=s1e5]
4. browser_snapshot → 获取注册表单结构
5. browser_fill_form → 填写用户名、邮箱、密码
6. browser_click → 点击 "Submit" [ref=s2e12]
7. browser_snapshot → 验证注册成功提示

请使用 Playwright 的 Planner Agent 分析 http://localhost:3000，
为电商购物流程规划测试场景

## 测试计划：电商购物流程

### 场景 1：用户注册
- 访问注册页面
- 填写有效信息 → 验证注册成功
- 填写无效邮箱 → 验证错误提示

### 场景 2：商品浏览与搜索
- 访问商品列表页
- 输入关键词搜索 → 验证结果过滤
- 点击分类筛选 → 验证分类正确

### 场景 3：购物车操作
- 添加商品到购物车
- 修改数量 → 验证价格更新
- 删除商品 → 验证购物车更新

### 场景 4：结账流程
- 填写地址信息
- 选择支付方式
- 确认订单 → 验证订单创建

请根据上面的测试计划，使用 Generator Agent 生成 Playwright 测试代码，
使用 Page Object Model 模式，保存到 tests/e2e/ 目录

// tests/e2e/shopping-cart.spec.ts
import { test, expect } from '@playwright/test';
import { HomePage } from '../pages/home.page';
import { ProductPage } from '../pages/product.page';
import { CartPage } from '../pages/cart.page';

test.describe('购物车流程', () => {
  let homePage: HomePage;
  let productPage: ProductPage;
  let cartPage: CartPage;

  test.beforeEach(async ({ page }) => {
    homePage = new HomePage(page);
    productPage = new ProductPage(page);
    cartPage = new CartPage(page);
    await homePage.goto();
  });

  test('添加商品到购物车', async () => {
    await homePage.searchProduct('无线耳机');
    await productPage.selectFirstProduct();
    await productPage.addToCart();
    await productPage.expectCartCount(1);
  });

  test('修改购物车商品数量', async () => {
    await homePage.searchProduct('无线耳机');
    await productPage.selectFirstProduct();
    await productPage.addToCart();
    await cartPage.goto();
    await cartPage.updateQuantity(0, 3);
    await cartPage.expectTotalPrice();
  });

  test('删除购物车商品', async () => {
    await homePage.searchProduct('无线耳机');
    await productPage.selectFirstProduct();
    await productPage.addToCart();
    await cartPage.goto();
    await cartPage.removeItem(0);
    await cartPage.expectEmpty();
  });
});

flowchart TD
    A[测试执行失败] --> B[Healer 获取当前页面快照]
    B --> C[分析失败原因：<br/>选择器失效/元素移位/文本变更]
    C --> D[在无障碍树中搜索匹配元素]
    D --> E{找到匹配?}
    E -->|是| F[更新选择器/定位器]
    E -->|否| G[标记为需要人工介入]
    F --> H[重新执行测试]
    H --> I{通过?}
    I -->|是| J[保存修复后的测试]
    I -->|否| C

测试 e2e/shopping-cart.spec.ts 中的"添加商品到购物车"用例失败了，
错误信息是 "Waiting for selector '.add-to-cart-btn' timed out"。
请使用 Healer Agent 修复这个测试

tests/
├── e2e/                          # E2E 测试用例
│   ├── auth.spec.ts
│   ├── shopping-cart.spec.ts
│   └── checkout.spec.ts
├── pages/                        # Page Objects
│   ├── base.page.ts              # 基础页面类
│   ├── home.page.ts
│   ├── product.page.ts
│   ├── cart.page.ts
│   └── checkout.page.ts
├── fixtures/                     # 测试夹具
│   └── test.fixture.ts
└── helpers/                      # 辅助工具
    ├── assertions.ts
    └── test-data.ts

请查看 src/pages/ 目录下的所有页面组件，
为每个页面生成对应的 Page Object Model 类。
使用 data-testid 作为首选定位策略，无障碍角色作为备选。
生成到 tests/pages/ 目录。

// tests/pages/base.page.ts
import { Page, Locator, expect } from '@playwright/test';

export class BasePage {
  readonly page: Page;

  constructor(page: Page) {
    this.page = page;
  }

  // 通用定位策略：优先 data-testid，备选无障碍角色
  protected getByTestId(id: string): Locator {
    return this.page.getByTestId(id);
  }

  protected getByRole(role: string, options?: Record<string, unknown>): Locator {
    return this.page.getByRole(role as any, options as any);
  }

  protected getByText(text: string): Locator {
    return this.page.getByText(text);
  }

  async goto(path: string = '/') {
    await this.page.goto(path);
    await this.page.waitForLoadState('networkidle');
  }

  async expectVisible(locator: Locator) {
    await expect(locator).toBeVisible({ timeout: 10000 });
  }
}

// tests/pages/home.page.ts
import { BasePage } from './base.page';
import { Page, Locator, expect } from '@playwright/test';

export class HomePage extends BasePage {
  // 定位器 - 使用语义化属性
  readonly searchInput: Locator;
  readonly searchButton: Locator;
  readonly productCards: Locator;
  readonly cartBadge: Locator;

  constructor(page: Page) {
    super(page);
    this.searchInput = this.getByTestId('search-input');
    this.searchButton = this.getByTestId('search-button');
    this.productCards = this.page.locator('[data-testid="product-card"]');
    this.cartBadge = this.getByTestId('cart-badge');
  }

  async goto() {
    await super.goto('/');
  }

  async searchProduct(query: string) {
    await this.searchInput.fill(query);
    await this.searchButton.click();
    await this.page.waitForResponse('**/api/products**');
  }

  async getProductCount(): Promise<number> {
    return this.productCards.count();
  }

  async getCartCount(): Promise<string> {
    return this.cartBadge.textContent() ?? '0';
  }
}

## E2E 测试定位器策略

按优先级从高到低：
1. `data-testid` 属性 — 最稳定，不受 UI 文案变动影响
2. 无障碍角色 — `getByRole('button', { name: 'Submit' })`
3. 无障碍标签 — `getByLabel('Email address')`
4. 文本内容 — `getByText('Welcome back')`（仅当文案不常变）
5. CSS 选择器 — 最后手段，必须包含语义化的 class 名

// src/components/ProductCard.tsx
export function ProductCard({ product }: { product: Product }) {
  return (
    <article data-testid="product-card">
      <h2 data-testid="product-name">{product.name}</h2>
      <span data-testid="product-price">${product.price}</span>
      <button
        data-testid="add-to-cart"
        onClick={() => addToCart(product.id)}
      >
        Add to Cart
      </button>
    </article>
  );
}

# 创建 Next.js 电商项目（如果还没有）
npx create-next-app@latest my-store --typescript --tailwind --app
cd my-store

# 安装 Playwright
npm install -D @playwright/test
npx playwright install chromium

# 创建测试目录结构
mkdir -p tests/{e2e,pages,fixtures,helpers}

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ['html', { open: 'never' }],
    ['json', { outputFile: 'test-results/results.json' }],
  ],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

请分析 src/app/ 下的所有页面路由和组件，为我的电商应用生成完整的 E2E 测试套件。

要求：
1. 使用 Page Object Model 模式
2. 覆盖：注册、登录、商品浏览、搜索、购物车、结账
3. 每个场景包含正向和反向测试
4. 使用 data-testid 定位
5. 保存到 tests/ 目录

我刚完成了商品评论功能的开发。
请：
1. 启动应用
2. 通过浏览器验证评论功能（发布评论、查看评论、删除评论）
3. 为评论功能生成 E2E 测试
4. 运行测试并报告结果

sequenceDiagram
    participant Dev as 开发者
    participant CC as Claude Code
    participant MCP as Playwright MCP
    participant App as 本地应用

    Dev->>CC: 验证评论功能 + 生成测试
    CC->>MCP: browser_navigate /localhost:3000
    MCP->>App: HTTP Request
    App-->>MCP: HTML Response
    MCP-->>CC: 页面加载完成
    CC->>MCP: browser_snapshot
    MCP-->>CC: 无障碍树 (含评论区域)
    CC->>MCP: browser_click "Write Review"
    CC->>MCP: browser_fill_form
    CC->>MCP: browser_click "Submit"
    CC->>MCP: browser_snapshot
    MCP-->>CC: 验证评论已发布
    CC->>CC: 生成 E2E 测试代码
    CC->>App: npx playwright test
    App-->>CC: 测试结果
    CC-->>Dev: 报告：3个场景全部通过

# .github/workflows/e2e.yml
name: E2E Tests
on:
  pull_request:
    branches: [main]

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright
        run: npx playwright install --with-deps chromium

      - name: Build application
        run: npm run build

      - name: Run E2E tests
        run: npx playwright test

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/

运行 npx playwright test，发现 tests/e2e/auth.spec.ts 失败。
请分析失败原因，使用 Healer 修复所有失败用例，
修复后重新运行测试确认通过

$ npx playwright test --reporter=json 2>&1 | tail -20

Error: locator.waitFor: Waiting for selector '[data-testid="login-btn"]' failed
  at LoginPage.clickLogin (tests/pages/login.page.ts:15)

// 修复前
readonly loginButton = this.getByTestId('login-btn');

// 修复后 - 开发者改了 data-testid
readonly loginButton = this.getByTestId('sign-in-btn');

npx playwright test tests/e2e/auth.spec.ts --retries=0

我们的 Button 组件从 <button class="btn"> 迁移到了 <Button variant="primary">，
导致 50+ 测试失败。请：
1. 运行全部测试，收集失败列表
2. 对每个失败用例使用 Healer 修复
3. 生成修复报告：哪些自动修复了，哪些需要人工介入

// tests/fixtures/auth.fixture.ts
import { test as base, Page } from '@playwright/test';

type AuthFixture = {
  authenticatedPage: Page;
};

export const test = base.extend<AuthFixture>({
  authenticatedPage: async ({ browser }, use) => {
    const context = await browser.newContext({
      storageState: 'tests/fixtures/auth-state.json',
    });
    const page = await context.newPage();
    await use(page);
    await context.close();
  },
});

请使用浏览器完成登录流程，将登录状态保存到 tests/fixtures/auth-state.json

// tests/helpers/mock-server.ts
import { Page } from '@playwright/test';

export async function mockProductAPI(page: Page) {
  await page.route('**/api/products', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({
        products: [
          { id: 1, name: 'Wireless Headphones', price: 79.99 },
          { id: 2, name: 'USB-C Cable', price: 12.99 },
        ],
      }),
    });
  });
}

请分析 src/app/api/ 下的所有 API 路由，
为每个路由生成 mock 函数，包含正常响应和错误响应两种场景

// tests/e2e/visual-regression.spec.ts
import { test, expect } from '@playwright/test';

test('首页视觉回归', async ({ page }) => {
  await page.goto('/');
  await expect(page).toHaveScreenshot('home-page.png', {
    maxDiffPixelRatio: 0.01,
    threshold: 0.2,
  });
});

// playwright.config.ts 中的并行配置
export default defineConfig({
  // 按文件级并行
  fullyParallel: true,
  workers: process.env.CI ? 4 : '50%',
  // 分片执行（CI 多机器）
  // shard: '1/4',
});

# 第1个分片（共4个）
npx playwright test --shard=1/4

// playwright.config.ts 速度优化
export default defineConfig({
  use: {
    // 关闭不必要的资源加载
    bypassCSP: true,
    // 超时设置
    navigationTimeout: 15000,
    actionTimeout: 10000,
  },
  // 禁用不必要的跟踪
  trace: 'off',  // CI 中改为 'on-first-retry'
  screenshot: 'off', // CI 中改为 'only-on-failure'
  video: 'off',  // CI 中改为 'retain-on-failure'
});

flowchart TB
    subgraph 开发阶段
        A[编写新功能] --> B[Claude Code 自测]
        B --> C{通过?}
        C -->|否| D[修复代码]
        D --> B
        C -->|是| E[提交 PR]
    end

    subgraph 测试生成
        E --> F[Planner Agent<br/>规划测试场景]
        F --> G[Generator Agent<br/>生成测试代码]
        G --> H[运行测试验证]
    end

    subgraph 持续维护
        I[CI 运行测试] --> J{全部通过?}
        J -->|是| K[合并代码]
        J -->|否| L[Healer Agent<br/>自动修复]
        L --> M{修复成功?}
        M -->|是| N[更新测试代码]
        M -->|否| O[人工介入]
        N --> I
        O --> P[开发者修复]
        P --> I
    end

    H --> I