npm install -D @playwright/test
npx playwright install chromium

import { defineConfig, devices } from '@playwright/test'
 
export default defineConfig({
  testDir: './tests',
  fullyParallel: true,
  retries: 0,
  reporter: [['html'], ['list']],
 
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
 
  // 自动启动 Next.js，无需手动 npm run dev
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: true,
    timeout: 120 * 1000,
  },
 
  projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
})

# CLAUDE.md
 
## 测试生成规范
 
### 项目信息
 
- 框架：Next.js 14 App Router
- 测试框架：Playwright + TypeScript
- baseURL：http://localhost:3000
 
### 文件输出位置
 
- E2E 测试：tests/e2e/[模块名]/[场景名].spec.ts
- Page Object：tests/fixtures/pages/[页面名]Page.ts
- Mock 数据：tests/mocks/[页面名].json
 
### 文件命名规则
 
- 根据测试场景自动命名，使用 kebab-case
- 例：「用户完整结账流程」→ checkout-complete-flow.spec.ts
- 例：「登录失败场景」→ login-failure.spec.ts
 
### 选择器规则（按优先级）
 
1. getByRole() 首选，语义化
2. getByLabel() 表单元素
3. getByText() 文本内容
4. getByTestId() 组件加 data-testid
5. 禁止 CSS selector 和 XPath
 
### 每个测试必须包含
 
- POM 类（封装所有页面操作）
- Mock 数据 JSON（所有接口必须 mock，数据结构与 TS 类型一致）
- 正常流程 + 异常场景 + 边界值
- waitForLoadState('networkidle') 等待 SSR hydration
- page.route() 拦截所有接口调用
 
### 禁止事项
 
- 禁止 page.waitForTimeout()（固定等待）
- 禁止 CSS class / XPath 定位
- 禁止测试之间共享状态
- 禁止依赖真实后端接口

---
name: generate-test
description: 理解指定文件及其依赖，基于场景生成 Playwright 测试脚本
---
 
请提供以下信息：
 
1. **目标文件路径**（如 app/checkout/page.tsx）
2. **测试场景描述**（如「用户完整结账流程，包含地址填写和支付」）
 
收到后我会：
 
- 读取目标文件及其所有 import 的依赖文件（components、hooks、types 等）
- 理解完整的业务逻辑、数据结构和接口定义
- 基于你描述的场景 Mock 所有接口（数据结构与 TS 类型严格匹配）
- 按照 CLAUDE.md 规范生成完整测试脚本：
  - Page Object Model → tests/fixtures/pages/
  - Mock 数据 → tests/mocks/
  - 测试用例 → tests/e2e/
- 根据场景描述自动命名文件（kebab-case）
- 生成完成后自动 review，输出评分和潜在问题
- 给出精确的运行命令，并询问是否直接执行
 
生成完成后会提示：
 
> 测试文件已生成：tests/e2e/checkout/checkout-complete-flow.spec.ts
> Review 评分：91分，无明显问题
>
> 运行命令：
>
> ```bash
> npx playwright test tests/e2e/checkout/checkout-complete-flow.spec.ts --headed
> ```
>
> 是否现在直接运行？
 
如果你回复「是」或「运行」，我会立即在终端执行这条命令。
执行完成后：
 
- 通过 → 告知结果，完成
- 失败 → 读取错误信息，分析原因，给出修复方案，修复后再次运行

import { Page, Locator } from '@playwright/test'
 
export class CheckoutPage {
  readonly addressInput: Locator
  readonly cityInput: Locator
  readonly couponInput: Locator
  readonly applyButton: Locator
  readonly submitButton: Locator
 
  constructor(private page: Page) {
    this.addressInput = page.getByLabel('收货地址')
    this.cityInput = page.getByLabel('城市')
    this.couponInput = page.getByLabel('优惠券码')
    this.applyButton = page.getByRole('button', { name: '使用优惠券' })
    this.submitButton = page.getByRole('button', { name: '提交订单' })
  }
 
  async goto() {
    await this.page.goto('/checkout')
    await this.page.waitForLoadState('networkidle')
  }
 
  async fillAddress(street: string, city: string) {
    await this.addressInput.fill(street)
    await this.cityInput.fill(city)
  }
 
  async applyCoupon(code: string) {
    await this.couponInput.fill(code)
    await this.applyButton.click()
  }
 
  async placeOrder() {
    await this.submitButton.click()
  }
}

{
  "cart": {
    "items": [{ "id": "1", "name": "商品A", "qty": 2, "price": 99 }],
    "total": 198
  },
  "couponValid": { "code": "SAVE20", "discount": 20, "valid": true },
  "couponInvalid": { "code": "INVALID", "valid": false, "message": "优惠券不存在" },
  "paymentSuccess": { "orderId": "ORD-001", "status": "paid" },
  "paymentFailed": { "status": "failed", "message": "余额不足" }
}

import { test, expect } from '@playwright/test'
import { CheckoutPage } from '../../fixtures/pages/CheckoutPage'
import mockData from '../../mocks/checkout.json'
 
test.describe('用户完整结账流程', () => {
  test.beforeEach(async ({ page }) => {
    await page.route('**/api/cart', (route) => route.fulfill({ json: mockData.cart }))
  })
 
  test('正常下单：填写地址 + 使用优惠券 + 支付成功', async ({ page }) => {
    await page.route('**/api/coupon', (route) => route.fulfill({ json: mockData.couponValid }))
    await page.route('**/api/payment', (route) => route.fulfill({ json: mockData.paymentSuccess }))
 
    const checkout = new CheckoutPage(page)
    await checkout.goto()
    await checkout.fillAddress('南京路1号', '上海')
    await checkout.applyCoupon('SAVE20')
 
    await expect(page.getByText('已优惠 ¥20')).toBeVisible()
 
    await checkout.placeOrder()
    await expect(page).toHaveURL('/order/success')
    await expect(page.getByText('订单提交成功')).toBeVisible()
  })
 
  test('优惠券无效，显示错误提示', async ({ page }) => {
    await page.route('**/api/coupon', (route) => route.fulfill({ json: mockData.couponInvalid }))
 
    const checkout = new CheckoutPage(page)
    await checkout.goto()
    await checkout.applyCoupon('INVALID')
 
    await expect(page.getByRole('alert')).toContainText('优惠券不存在')
  })
 
  test('支付失败，显示失败提示', async ({ page }) => {
    await page.route('**/api/coupon', (route) => route.fulfill({ json: mockData.couponValid }))
    await page.route('**/api/payment', (route) => route.fulfill({ json: mockData.paymentFailed }))
 
    const checkout = new CheckoutPage(page)
    await checkout.goto()
    await checkout.fillAddress('南京路1号', '上海')
    await checkout.placeOrder()
 
    await expect(page.getByRole('alert')).toContainText('余额不足')
    await expect(page).toHaveURL('/checkout')
  })
})

npx @playwright/mcp@latest

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

# 运行所有测试
npx playwright test
 
# 带界面运行（本地调试首选）
npx playwright test --headed
 
# 只跑某个场景文件
npx playwright test tests/e2e/checkout/checkout-complete-flow.spec.ts
 
# 只跑某个模块目录
npx playwright test tests/e2e/checkout/
 
# 查看 HTML 报告
npx playwright show-report
 
# 更新视觉回归基准截图
npx playwright test tests/visual/ --update-snapshots

链路名称：
前置条件：
操作步骤：
 
主断言：
- 最能证明业务成功的结果
 
辅助断言：
- 页面 / 路由状态
- 网络请求正确性
- 数据副作用
- 本地存储 / 登录态 / 权限态
 
异常断言：
- 接口失败后的表现
- loading / 按钮恢复
- 防重复提交
- 脏数据保护
 
非功能断言（按需）：
- 性能
- 幂等
- 兼容
- 可用性
- 安全性
 
 
## 参考文档
 
[AI 测试全体系详解（自动化测试框架 + 智能缺陷检测 + A/B 测试优化）](https://mp.weixin.qq.com/s/JF0cLs2C6eDhCVWp11hVEw)
 
[从代码巡检看软件测试：AI已经开始替代功能测试了](https://mp.weixin.qq.com/s/GRPF9vjj2y-em4NvhSyNgg)
 
[从人工到AI驱动：天猫测试全流程自动化变革实践](https://developer.aliyun.com/article/1685362)
 
[如何让AI帮你做前端自动化测试？我们这样落地了](https://developer.aliyun.com/article/1672102)