Playwright 环境安装和配置指南

1. 安装 Playwright

使用 npm 安装

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

# 安装浏览器
npx playwright install

使用 yarn 安装

# 安装 Playwright
yarn add -D @playwright/test

# 安装浏览器
yarn playwright install

2. 项目配置

基础配置文件 (playwright.config.js)

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

export default defineConfig({
  // 测试目录
  testDir: './tests',
  
  // 并行运行测试
  workers: process.env.CI ? 1 : undefined,
  
  // 重试失败的测试
  retries: process.env.CI ? 2 : 0,
  
  // 超时设置
  timeout: 30000,
  
  // 报告配置
  reporter: [
    ['html'],
    ['list']
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:5173',
    reuseExistingServer: !process.env.CI,
  },
  // 项目配置
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
  ],
  
  // 全局设置
  use: {
    // 基础 URL
    baseURL: 'http://localhost:5174',
    
    // 截图设置
    screenshot: 'only-on-failure',
    
    // 视频设置
    video: 'retain-on-failure',
    
    // 追踪设置
    trace: 'retain-on-failure',
    env: {
      NODE_ENV: process.env.NODE_ENV || 'development'
    }
  },
  globalSetup: async ({ playwright }) => {
    // 可以在这里添加全局的设置
  },
  globalTeardown: async ({ playwright }) => {
    // 可以在这里添加全局的清理
  },
});

package.json 配置

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

3. 目录结构

demo/
├── tests/                    # 测试文件目录
│   ├── home.spec.js         # 首页测试
│   ├── form.spec.js         # 表单页测试
│   ├── list.spec.js         # 列表页测试
│   └── playwright-guide.md  # 测试指南
├── playwright.config.js     # Playwright 配置
└── package.json            # 项目配置

4. 环境变量配置

.env 文件

# 开发环境
VITE_API_BASE_URL=http://localhost:3000
VITE_APP_TITLE=Demo App

# 测试环境
PLAYWRIGHT_BASE_URL=http://localhost:5173
PLAYWRIGHT_HEADLESS=true

在配置文件中使用环境变量

// playwright.config.js
export default defineConfig({
  use: {
    baseURL: process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:5173',
  },
});

5. 测试运行

运行所有测试

npm test

运行 UI 模式

npm run test:ui

运行调试模式

npm run test:debug

查看测试报告

npm run test:report

6. 常见问题解决

浏览器安装问题

# 重新安装浏览器
npx playwright install

# 安装特定浏览器
npx playwright install chromium

权限问题

# Linux/Mac 系统
chmod +x node_modules/.bin/playwright

代理设置

// playwright.config.js
export default defineConfig({
  use: {
    proxy: {
      server: 'http://myproxy.com:3128',
      username: 'user',
      password: 'pass'
    }
  }
});

7. CI/CD 集成

GitHub Actions 配置

name: Playwright Tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: actions/setup-node@v2
      with:
        node-version: 16
    - name: Install dependencies
      run: npm ci
    - name: Install Playwright Browsers
      run: npx playwright install --with-deps
    - name: Run Playwright tests
      run: npx playwright test
    - uses: actions/upload-artifact@v2
      if: always()
      with:
        name: playwright-report
        path: playwright-report/

8. 性能优化

配置优化

// playwright.config.js
export default defineConfig({
  // 并行运行测试
  workers: process.env.CI ? 1 : undefined,
  
  // 设置超时时间
  timeout: 30000,
  
  // 设置重试次数
  retries: process.env.CI ? 2 : 0,
  
  // 设置全局等待时间
  expect: {
    timeout: 5000
  }
});

测试优化建议

1. 使用 test.beforeEach() 进行测试准备
2. 避免不必要的等待
3. 使用适当的超时时间
4. 合理使用并行测试
5. 优化选择器性能

9. 调试技巧

使用 UI 模式

npm run test:ui

使用调试模式

npm run test:debug

使用断点

// 在代码中添加断点
await page.pause();

查看追踪

# 运行测试并生成追踪
npx playwright test --trace on

# 查看追踪
npx playwright show-trace trace.zip