e2e-testing

用途

本技能用于使用 Playwright 1.58+ 进行端到端（E2E）测试，重点验证关键用户旅程，并支持 AI 辅助的测试生成。它适用于测试关键用户旅程、浏览器自动化、跨浏览器测试以及 AI 辅助测试生成等场景。

主要能力

语义化定位器

技能推荐使用基于角色的定位器（最稳定），其次是基于标签的定位器，再次是测试 ID。定位器优先级为：getByRole() > getByLabel() > getByPlaceholder() > getByTestId()。应避免使用 CSS 选择器和 XPath，因为它们较为脆弱。

示例：

// 首选：基于角色的定位器（最稳定）
await page.getByRole('button', { name: 'Add to cart' }).click();
await page.getByRole('link', { name: 'Checkout' }).click();

// 良好：用于表单控件的基于标签的定位器
await page.getByLabel('Email').fill('test@example.com');

// 可接受：用于稳定锚点的测试 ID
await page.getByTestId('checkout-button').click();

// 避免：CSS 选择器和 XPath（脆弱）
// await page.click('[data-testid="add-to-cart"]');

基础测试

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

test('user can complete checkout', async ({ page }) => {
  await page.goto('/products');
  await page.getByRole('button', { name: 'Add to cart' }).click();
  await page.getByRole('link', { name: 'Checkout' }).click();
  await page.getByLabel('Email').fill('test@example.com');
  await page.getByRole('button', { name: 'Submit' }).click();
  await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
});

AI 代理（1.58+）

初始化 AI 代理：

# 为你的首选 AI 工具初始化代理
npx playwright init-agents --loop=claude    # 用于 Claude Code
npx playwright init-agents --loop=vscode    # 用于 VS Code（需要 v1.105+）
npx playwright init-agents --loop=opencode  # 用于 OpenCode

生成的目录结构：

.github/：代理定义和配置
specs/：Markdown 格式的测试计划
tests/seed.spec.ts：供 AI 代理参考的种子文件

初始化后，代理可以：

从 specs/ 读取测试计划并生成测试
使用 seed.spec.ts 作为模板以保持模式一致
通过分析失败自动修复失败的测试

破坏性变更（1.58）

以下功能在 Playwright 1.58 中已移除：

_react 选择器：改用 getByRole() 或 getByTestId()
_vue 选择器：改用 getByRole() 或 getByTestId()
:light 选择器后缀：使用不带 :light 的标准 CSS 选择器
devtools 启动选项：改用 args: ['--auto-open-devtools-for-tabs']
macOS 13 WebKit 支持：升级到 macOS 14+ 以进行 WebKit 测试

迁移示例：

// 之前（1.57 及更早）
await page.locator('_react=MyComponent').click();
await page.locator('.card:light').click();

// 之后（1.58+）
await page.getByTestId('my-component').click();
await page.locator('.card').click();

// DevTools 启动选项
// 之前
const browser = await chromium.launch({ devtools: true });

// 之后
const browser = await chromium.launch({
  args: ['--auto-open-devtools-for-tabs']
});

新特性（1.58+）

// 使用本地标志通过 CDP 连接
const browser = await chromium.connectOverCDP({
  endpointURL: 'http://localhost:9222',
  isLocal: true  // 新增：优化本地连接
});

// 断言单个类名
await expect(page.locator('.card')).toContainClass('highlighted');

// 不稳定测试检测
export default defineConfig({
  failOnFlakyTests: true,
});

// IndexedDB 存储状态
await page.context().storageState({
  path: 'auth.json',
  indexedDB: true  // 在存储状态中包含 IndexedDB
});

Speedboard HTML 报告中的时间线

HTML 报告现在包含时间线可视化，显示：

测试执行顺序
并行测试分布
每个测试阶段花费的时间
性能瓶颈

// 启用带时间线的 HTML 报告器
export default defineConfig({
  reporter: [['html', { open: 'never' }]],
});

反模式（禁止）

// 永远不要使用 CSS 选择器进行用户交互
await page.click('.submit-btn');

// 永远不要使用硬编码等待
await page.waitForTimeout(2000);

// 永远不要测试实现细节
await page.click('[data-testid="btn-123"]');

// 始终使用语义化定位器
await page.getByRole('button', { name: 'Submit' }).click();

// 始终使用 Playwright 的自动等待
await expect(page.getByRole('alert')).toBeVisible();

关键决策

定位器：getByRole > getByLabel > getByTestId
浏览器：Chromium（1.58+ 中为 Chrome for Testing）
执行：每个测试 5-30 秒
重试：CI 中 2-3 次，本地 0 次
截图：仅在失败时

需要测试的关键用户旅程

认证：注册、登录、密码重置
核心交易：购买、预订、提交
数据操作：创建、更新、删除
用户设置：个人资料更新、偏好设置

使用方式

通过 npx playwright init-agents 命令初始化 AI 代理，选择对应的 AI 工具循环参数（claude、vscode、opencode）。初始化后会生成代理定义、测试计划和种子文件。之后代理可以读取测试计划生成测试，使用种子文件保持模式一致，并自动修复失败的测试。

适用场景

测试关键用户旅程（认证、交易、数据操作、用户设置）
浏览器自动化
跨浏览器测试
AI 辅助测试生成
视觉回归测试
认证状态管理

限制

需要 Playwright 1.58+ 版本
使用 VS Code 循环需要 v1.105+
WebKit 测试需要 macOS 14+
部分旧选择器和选项在 1.58 中已移除，需要迁移

详细文档

references/playwright-1.57-api.md：完整的 Playwright API 参考
examples/test-patterns.md：用户流程、页面对象、视觉测试
checklists/e2e-checklist.md：测试选择和审查清单
scripts/page-object-template.ts：页面对象模型模板

能力细节

语义化定位器

关键词：getByRole、getByLabel、getByText、semantic、locator 解决的问题：使用基于可访问性的定位器；避免脆弱的 CSS/XPath 选择器；编写稳定的元素查询。

视觉回归

关键词：visual regression、screenshot、snapshot、visual diff 解决的问题：捕获并比较视觉快照；检测意外的 UI 变化；配置阈值容差。

跨浏览器测试

关键词：cross browser、chromium、firefox、webkit、browser matrix 解决的问题：在多个浏览器上运行测试；配置浏览器特定设置；处理浏览器差异。

AI 测试生成

关键词：AI test、generate test、autonomous、test agent、planner、init-agents 解决的问题：从用户旅程生成测试；使用 AI 代理进行测试规划；创建全面的测试覆盖。

AI 测试修复

关键词：test healing、self-heal、auto-fix、resilient test 解决的问题：自动修复损坏的选择器；使测试适应 UI 变化；减少测试维护。

认证状态

关键词：auth state、storage state、login once、reuse session、indexedDB 解决的问题：在测试之间持久化认证；避免重复登录流程；在测试之间共享认证状态。

技能介绍

用途

主要能力

语义化定位器

基础测试

AI 代理（1.58+）

破坏性变更（1.58）

新特性（1.58+）

Speedboard HTML 报告中的时间线

反模式（禁止）

关键决策

需要测试的关键用户旅程

使用方式

适用场景

限制

详细文档

相关技能

能力细节

语义化定位器

视觉回归

跨浏览器测试

AI 测试生成

AI 测试修复

认证状态