端到端测试实战：Playwright 从零到生产线

┌─────────────────────────────────────────────────────────┐
│                    Playwright 架构                       │
├─────────────────────────────────────────────────────────┤
│  Test Runner (Node.js/Python/Java/C# )                  │
│     │                                                   │
│     ▼                                                   │
│  Playwright Library (统一 API)                          │
│     │                                                   │
│     ├──► Chromium (with DevTools Protocol)              │
│     ├──► Firefox (custom Playwright protocol patch)     │
│     └──► WebKit (custom Playwright protocol patch)      │
│                                                         │
│  关键优势：                                             │
│  • 浏览器协议直接通信（非 WebDriver HTTP 往返）          │
│  • 所有浏览器使用同一套 API                              │
│  • Browser Context 实现测试隔离（<100ms 创建）           │
│  • 自动等待（Auto-wait）消除 80% 的 flakiness           │
└─────────────────────────────────────────────────────────┘

// ❌ Selenium 时代的写法——需要自己处理等待和重试
await driver.sleep(1000);  // 盲目等待
const button = await driver.findElement(By.id('submit'));
await button.click();

// ✅ Playwright 的写法——自动等待元素 actionable
await page.click('#submit');  // 自动重试直到元素可见、启用、稳定

// 等价于 Playwright 内部的自动检查链：
// 1. 元素在 DOM 中存在
// 2. 元素可见（visibility: not hidden）
// 3. 元素启用（enabled: not disabled）
// 4. 元素停止移动（stable: not animation）
// 5. 元素可以接收事件（not obscured by other element）

import { test, expect } from '@playwright/test';

test('locator strategies', async ({ page }) => {
  await page.goto('/dashboard');

  // ✅ 推荐：语义化定位（可访问性优先）
  await page.getByRole('button', { name: '提交订单' }).click();
  await page.getByLabel('邮箱地址').fill('user@example.com');
  await page.getByPlaceholder('搜索商品').fill('iPhone');
  await page.getByText('订单已提交成功').waitFor();

  // ✅ 推荐：Test ID（最稳定，不受文案/UI变化影响）
  await page.getByTestId('checkout-button').click();

  // ⚠️ 次选：CSS selector（受样式变化影响）
  await page.locator('.btn-primary').click();

  // ❌ 不推荐：XPath（可读性差，易碎）
  await page.locator('//div[@class="btn"]').click();

  // 链式过滤
  const productCard = page.locator('.product-card')
    .filter({ hasText: 'iPhone 16' })
    .filter({ has: page.locator('.in-stock') });

  await expect(productCard).toHaveCount(1);
});

// 隐式等待到条件满足或超时（默认 5s），无需显式轮询
await expect(page.locator('.spinner')).not.toBeVisible();
await expect(page.locator('.result')).toHaveText('Success', { timeout: 10000 });
await expect(page.locator('.items')).toHaveCount(3);

// 对比：传统断言的问题
// expect(await page.locator('.result').textContent()).toBe('Success');
// ❌ 如果结果还没出现，直接失败，没有重试机制

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

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  workers: process.env.CI ? 4 : undefined,

  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
    actionTimeout: 10000,
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
    { name: 'Mobile Chrome', use: { ...devices['Pixel 5'] } },
    { name: 'Mobile Safari', use: { ...devices['iPhone 12'] } },
  ],
});

# e2e/pages/login_page.py
from playwright.sync_api import Page, expect

class LoginPage:
    def __init__(self, page: Page):
        self.page = page
        self.email_input = page.get_by_test_id("login-email")
        self.password_input = page.get_by_test_id("login-password")
        self.submit_button = page.get_by_test_id("login-submit")
        self.error_message = page.get_by_test_id("login-error")

    def goto(self):
        self.page.goto("/login")
        return self

    def login(self, email: str, password: str):
        self.email_input.fill(email)
        self.password_input.fill(password)
        self.submit_button.click()
        return self

    def expect_error(self, message: str):
        expect(self.error_message).to_contain_text(message)
        return self

    def expect_successful_redirect(self):
        expect(self.page).to_have_url("/dashboard")
        return self


# e2e/tests/test_login.py
from e2e.pages.login_page import LoginPage

def test_successful_login(page):
    login_page = LoginPage(page)
    login_page.goto().login("user@example.com", "password123")
    login_page.expect_successful_redirect()

def test_invalid_credentials(page):
    LoginPage(page).goto().login("wrong@example.com", "wrong")
        .expect_error("Invalid credentials")

// e2e/pages/CheckoutPage.ts
import { Page, Locator, expect } from '@playwright/test';

export class CheckoutPage {
  readonly continueButton: Locator;
  readonly placeOrderButton: Locator;
  readonly totalAmount: Locator;

  constructor(readonly page: Page) {
    this.continueButton = page.getByTestId('checkout-continue');
    this.placeOrderButton = page.getByTestId('checkout-place-order');
    this.totalAmount = page.getByTestId('order-total');
  }

  async goto() {
    await this.page.goto('/checkout');
  }

  async fillShippingAddress(address: {
    name: string; street: string; city: string; zip: string;
  }) {
    await this.page.getByTestId('shipping-name').fill(address.name);
    await this.page.getByTestId('shipping-street').fill(address.street);
    await this.page.getByTestId('shipping-city').fill(address.city);
    await this.page.getByTestId('shipping-zip').fill(address.zip);
    await this.continueButton.click();
  }

  async selectPaymentMethod(method: 'card' | 'paypal') {
    await this.page.getByTestId(`payment-${method}`).click();
  }

  async placeOrder() {
    await this.placeOrderButton.click();
    await expect(this.page.getByTestId('order-confirmation')).toBeVisible();
  }

  async getTotal(): Promise<string> {
    return await this.totalAmount.textContent() || '';
  }
}

// 1. 全局 setup：只登录一次，保存 storage state
// e2e/auth.setup.ts
import { test as setup, expect } from '@playwright/test';
import path from 'path';

const authFile = path.join(__dirname, '../playwright/.auth/user.json');

setup('authenticate', async ({ page }) => {
  await page.goto('/login');
  await page.getByTestId('login-email').fill(process.env.TEST_USER_EMAIL!);
  await page.getByTestId('login-password').fill(process.env.TEST_USER_PASSWORD!);
  await page.getByTestId('login-submit').click();

  await expect(page.getByTestId('dashboard-header')).toBeVisible();

  // 保存 cookies + localStorage + sessionStorage
  await page.context().storageState({ path: authFile });
});

// 2. 普通测试复用登录态
// playwright.config.ts
export default defineConfig({
  projects: [
    { name: 'setup', testMatch: /.*\.setup\.ts/ },
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        storageState: 'playwright/.auth/user.json',
      },
      dependencies: ['setup'],
    },
  ],
});

// 通过 API 直接获取认证 Cookie，避免走 UI 登录流程
test('quick login via API', async ({ page, context }) => {
  // 调用登录 API
  const response = await page.request.post('/api/auth/login', {
    data: { email: 'user@example.com', password: 'password123' }
  });

  // 提取 cookie 并注入
  const cookies = await context.cookies();
  await context.addCookies(cookies);

  // 现在已登录，直接测业务逻辑
  await page.goto('/dashboard');
  await expect(page.getByTestId('user-name')).toHaveText('User Name');
});

// playwright.config.ts
export default defineConfig({
  use: {
    trace: 'on-first-retry',   // 失败时自动录制 trace
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
});

# 本地查看失败的 trace
npx playwright show-trace test-results/login-fails/trace.zip

# .github/workflows/e2e.yml
- name: Run E2E tests
  run: npx playwright test

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

import { test, expect } from '@playwright/test';

test('visual regression: product page', async ({ page }) => {
  await page.goto('/products/iphone-16');

  // 等待关键元素稳定
  await page.getByTestId('product-image').waitFor();

  // 全页截图比较（阈值 2% 像素差异可接受）
  await expect(page).toHaveScreenshot('product-page.png', {
    maxDiffPixels: 100,
    threshold: 0.2,
    fullPage: true,
  });

  // 元素级截图比较
  const card = page.getByTestId('product-card');
  await expect(card).toHaveScreenshot('product-card.png');
});

test('visual regression with masked elements', async ({ page }) => {
  await page.goto('/dashboard');

  await expect(page).toHaveScreenshot('dashboard.png', {
    // 遮罩动态内容（时间戳、UUID）
    mask: [
      page.getByTestId('timestamp'),
      page.getByTestId('order-id'),
    ],
    // 忽略特定区域（CSS clip）
    clip: { x: 0, y: 0, width: 1280, height: 720 },
  });
});

// playwright.config.ts
export default defineConfig({
  fullyParallel: true,           // 测试文件内也并行
  workers: process.env.CI ? 4 : undefined,  // CI 用 4 workers

  use: {
    // 每个 worker 使用独立的 browser context
    // 同 worker 内的测试共享 context（快但非完全隔离）
  },
});

// 每个 test 使用新的 context（默认行为，最稳定）
test('isolated test 1', async ({ page, context }) => {
  // page 属于全新的 context，cookie/storage 都是干净的
});

// 如果需要跨 test 共享登录态（用 storageState）
test.describe.serial('order flow', () => {
  test('add to cart', async ({ page }) => { ... });
  test('checkout', async ({ page }) => { ... });  // 共享上一个测试的状态
});

// playwright.config.ts
export default defineConfig({
  retries: process.env.CI ? 2 : 0,  // CI 中失败重试 2 次

  expect: {
    timeout: 5000,  // 断言超时 5s
  },
});