playwright-testing

Playwright 测试

Playwright 是一款现代化的 Web 应用端到端测试框架。它提供可靠、快速的跨浏览器测试体验，并带来出色的开发者体验。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用其他技能……
编写 E2E 浏览器测试	编写单元测试（使用 vitest-testing）
在 Chromium、Firefox、WebKit 上测试	测试 Python 代码（使用 python-testing）
设置视觉回归测试	分析测试质量（使用 test-quality-analysis）
在 E2E 测试中模拟网络请求	生成基于属性的测试（使用 property-based-testing）
测试移动设备视口	仅测试 API 契约（使用 api-testing）

核心专长

• 跨浏览器：在 Chromium、Firefox、WebKit（Safari）上测试
• 可靠：自动等待、自动重试，不会出现不稳定的测试
• 快速：并行执行、浏览器上下文隔离
• 现代化：以 TypeScript 为先、使用 async/await、支持自动补全
• 多平台：Windows、macOS、Linux

安装

bun create playwright                  # Initialize (recommended)
bun add --dev @playwright/test         # Or install manually
bunx playwright install                # Install browsers
bunx playwright install --with-deps    # With system deps (Linux)
bunx playwright --version              # Verify

配置（playwright.config.ts）

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

export default defineConfig({
  testDir: './tests',
  timeout: 30000,
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
  ],
});

基本命令

bunx playwright test                           # Run all tests
bunx playwright test tests/login.spec.ts       # Specific file
bunx playwright test --headed                  # See browser
bunx playwright test --debug                   # Debug mode
bunx playwright test --project=chromium        # Specific browser
bunx playwright test --ui                      # UI mode
bunx playwright codegen http://localhost:3000  # Record tests
bunx playwright show-report                    # Last report
bunx playwright show-trace trace.zip           # Trace viewer
bunx playwright test --update-snapshots        # Update snapshots

编写测试

基本测试结构

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

test('basic test', async ({ page }) => {
  await page.goto('https://example.com');
  await expect(page).toHaveTitle(/Example/);
});

test.describe('login flow', () => {
  test('should login successfully', async ({ page }) => {
    await page.goto('/login');
    await page.fill('input[name="email"]', '[email protected]');
    await page.fill('input[name="password"]', 'password123');
    await page.click('button[type="submit"]');
    await expect(page).toHaveURL('/dashboard');
  });
});

选择器和定位器

// Text/Role selectors (recommended)
await page.getByText('Sign in').click();
await page.getByRole('button', { name: 'Submit' }).click();
await page.getByLabel('Email').fill('[email protected]');
await page.getByPlaceholder('Enter your name').fill('John');
await page.getByTestId('login-button').click();

// CSS/XPath selectors
await page.locator('.button-primary').click();
await page.locator('xpath=//button[text()="Submit"]').click();

// Chaining
await page.locator('.card').filter({ hasText: 'Product' }).getByRole('button').click();

关键断言

断言	说明
toHaveTitle(title)	页面标题
toHaveURL(url)	页面 URL
toBeVisible()	元素可见
toBeEnabled()	元素已启用
toHaveText(text)	元素文本
toContainText(text)	部分文本
toHaveAttribute(name, value)	属性值
toHaveClass(class)	CSS 类
toHaveValue(value)	输入值
toBeEmpty()	输入为空
toHaveCount(n)	元素数量
not.toBeDisabled()	否定断言

Agent 优化

场景	命令
快速测试	bunx playwright test --reporter=line --bail
CI 测试	bunx playwright test --reporter=github
单个浏览器	bunx playwright test --project=chromium --reporter=line
调试失败的测试	bunx playwright test --trace on --reporter=line
有头模式调试	bunx playwright test --headed --debug

如需详细示例、高级模式和最佳实践，请参阅 REFERENCE.md。

在不带 GPU 的 CI 运行器上测试 WebGL 应用（CesiumJS、three.js、MapLibre）：SwiftShader 标志、lhci 的 chromeFlags 字符串陷阱和帧率限制详见 无 GPU CI 环境中的 WebGL 应用。

参考资料

• 官方文档：https://playwright.dev
• 配置：https://playwright.dev/docs/test-configuration
• API 参考：https://playwright.dev/docs/api/class-test
• 最佳实践：https://playwright.dev/docs/best-practices
• CI/CD：https://playwright.dev/docs/ci
• Trace 查看器：https://playwright.dev/docs/trace-viewer