qa-e2e-playwright

name	qa/e2e-playwright
description	Playwright E2E 测试完整方法论，涵盖项目初始化、Page Object Model、认证复用、API Mock、视觉回归、多浏览器测试、CI 集成和调试技巧
version	1.0.0
agent	qa
type	methodology
user-invocable	false
agent-invocable	true
dependencies	["shared/tech-stack-detection"]
triggers	["需要编写或执行 E2E 测试时","需要配置 Playwright 测试环境时","门禁要求 E2E 测试通过时","需要视觉回归测试时"]

Playwright E2E 测试方法论

适用场景

• Web 项目需要编写端到端测试
• 门禁（Gate 1）要求 E2E 测试通过
• 需要覆盖关键用户流程的自动化验证
• 需要多浏览器/多视口兼容性验证
• 需要视觉回归测试

---

1. 项目初始化

1.1 安装

# 新项目初始化（推荐）
npm init playwright@latest

# 已有项目添加
npm install -D @playwright/test
npx playwright install

1.2 配置文件（playwright.config.ts）

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

export default defineConfig({
  testDir: './e2e',
  // 测试产物目录
  outputDir: './e2e/test-results',

  // 全局超时
  timeout: 30_000,
  expect: { timeout: 5_000 },

  // 并行执行
  fullyParallel: true,
  workers: process.env.CI ? 1 : undefined,

  // 失败重试（CI 中重试一次减少 flaky）
  retries: process.env.CI ? 1 : 0,

  // 报告
  reporter: [
    ['html', { outputFolder: './e2e/playwright-report' }],
    ['json', { outputFile: './e2e/test-results/results.json' }],
    // CI 中额外输出到 stdout
    ...(process.env. ? [[]  ] : []),
  ],

  
  : {
    : process.. || ,
    
    : ,
    
    : ,
    
    : ,
  },

  
  : [
    { : , : { ...devices[] } },
    { : , : { ...devices[] } },
    { : , : { ...devices[] } },
    { : , : { ...devices[] } },
    { : , : { ...devices[] } },
  ],

  
  : {
    : ,
    : ,
    : !process..,
    : ,
  },
});