testing-e2e

E2E 测试模式

使用 Playwright 1.59+ 进行端到端测试、视觉回归、无障碍测试和 AI Agent 工作流。

快速参考

类别	规则	影响	适用场景
模拟后端	rules/emulate-e2e.md	高	首选 — 为 E2E 提供确定性的 API 后端
Playwright 核心	rules/e2e-playwright.md	高	语义定位器、自动等待、检测不稳定测试
页面对象	rules/e2e-page-objects.md	高	封装页面交互、视觉回归
AI Agent	rules/e2e-ai-agents.md	高	Planner/Generator/Healer、init-agents
A11y Playwright	rules/a11y-playwright.md	中	使用 axe-core 扫描完整页面，符合 WCAG 2.2 AA
A11y CI/CD	rules/a11y-testing.md	中	CI 门禁、jest-axe 单元测试、阻止 PR
端到端类型	rules/validation-end-to-end.md	高	tRPC、Prisma、Pydantic 类型安全

总计：7 条规则、2 份参考资料、3 份检查清单、1 个示例、1 个脚本

上游文档覆盖范围（不要重复说明）

Playwright、axe-core 和 jest-axe 都有自己的文档。本技能仅包含 OrchestKit 的 差异内容（references/ork-delta.md）以及 rules/ 中的内部子集。对于下表所列内容， 请查阅供应商页面，而不要指望在此处找到相关说明。

主题	来源
截图对比工作流、基线文件、snapshotPathTemplate	https://playwright.dev/docs/test-snapshots
toHaveScreenshot 选项：mask、maxDiffPixelRatio、stylePath、animations	https://playwright.dev/docs/api/class-pageassertions
复用身份验证：storageState、设置项目、IndexedDB	https://playwright.dev/docs/auth
使用 page.route 拦截网络（内部默认仍是优先模拟，参见 rules/emulate-e2e.md）	https://playwright.dev/docs/mock
各版本中移除和变更的 API（SKILL.md 仅保留下面的简短禁用列表）	https://playwright.dev/docs/release-notes
完整定位器 API（内部优先级顺序见 rules/e2e-playwright.md）	https://playwright.dev/docs/locators
在 CI 上配置 Playwright runner（内部无障碍门禁工作流见 rules/a11y-testing.md）	https://playwright.dev/docs/ci
init-agents CLI 标志和生成的文件（Planner/Generator/Healer 工作流见 rules/e2e-ai-agents.md）	https://playwright.dev/docs/test-agents
jest-axe 匹配器和 configureAxe API（内部组件状态子集见 rules/a11y-testing.md）	https://github.com/NickColley/jest-axe
Lighthouse CI 配置和评分断言	https://github.com/GoogleChrome/lighthouse-ci

WCAG 2.2 成功标准以及手动键盘、屏幕阅读器、对比度和缩放测试不会转交给其他文档：checklists/a11y-testing-checklist.md 仍包含完整内容，规范性参考为 https://www.w3.org/WAI/WCAG22/quickref/。

模拟后端

对于与外部 API（GitHub、Vercel、Google）交互的 E2E 测试，请使用 emulate 作为后端，而不是调用真实 API。这样可以避免速率限制、网络问题和非确定性数据导致的不稳定。

方案	结果
模拟后端（首选）	确定性强、速度快、适用于 CI
真实 API	不稳定、受速率限制、速度慢
MSW/Nock 拦截	没有状态机，需要手动管理响应

主要功能：用于生成可复现数据的种子配置、用于 Playwright 并行运行的每个 worker 端口隔离，以及完整的状态机转换。

模式、CI 配置和每个 worker 的隔离 fixture 详见 rules/emulate-e2e.md。

---

Playwright 快速入门

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('[email protected]');
  await page.getByRole('button', { name: 'Submit' }).click();
  await expect(page.getByRole('heading', { name: 'Order confirmed' })).toBeVisible();
});

定位器优先级： getByRole() > getByLabel() > getByPlaceholder() > getByTestId()

Playwright Core

用于构建可靠测试的语义定位器模式和最佳实践。

规则	文件	关键模式
Playwright E2E	rules/e2e-playwright.md	语义定位器、自动等待、1.58+ 新特性

反模式（禁止）：

• 硬编码等待：await page.waitForTimeout(2000)
• 使用 CSS 选择器进行交互：await page.click('.submit-btn')
• XPath 定位器

在 1.58/1.59 中已移除 — 请勿使用：

• _react=ComponentName[prop=value] 和 _vue=... 组件选择器引擎 — 在 1.58 中已移除
• :light 选择器后缀 — 已移除
• launch({ devtools: true }) 选项 — 已移除；请使用 args: ['--auto-open-devtools-for-tabs']

页面对象

将页面交互封装到可复用的类中。

规则	文件	关键模式
页面对象模型	rules/e2e-page-objects.md	在构造函数中定义定位器、操作方法、断言方法

const checkout = new CheckoutPage(page);
await checkout.fillEmail('[email protected]');
await checkout.submit();
await checkout.expectConfirmation();

AI Agent

Playwright 1.59+ AI Agent 框架，用于测试规划、生成和自我修复。包含专为编码 Agent 设计的高效令牌 CLI 模式——输出简洁、响应结构化、上下文开销更低。

规则	文件	关键模式
AI Agent	rules/e2e-ai-agents.md	Planner、Generator、Healer 工作流

npx playwright init-agents --loop=claude    # For Claude Code

高效令牌 CLI 模式（1.58+）：Playwright 提供以 SKILL 为核心的 CLI 模式，可生成简洁且适合 Agent 的输出——通过 AI Agent 运行 Playwright 时使用此模式，以尽量减少令牌消耗。

工作流：Planner（探索应用、创建规格）-> Generator（读取规格、测试运行中的应用）-> Healer（修复失败、更新选择器）。

Playwright 1.59 新特性（2026 年 4 月）——与 AI Agent 相关：

• page.screencast({ start, stop, showActions }) — 统一的视频与实时 JPEG 帧流。Healer Agent 无需写入视频文件，即可在运行过程中读取帧并进行视觉断言。
• browser.bind() / npx playwright-cli attach — 测试过程中，可从 MCP 客户端连接到正在运行的浏览器；Healer 可用它检查卡住或失败的 CI 运行。
• locator.normalize() — 将脆弱的定位器改写为符合最佳实践的等效形式。与 Healer 搭配使用，可在适用时自动将 getByTestId 升级为 getByRole。

可访问性（Playwright）

在 E2E 测试中使用 axe-core 进行整页可访问性验证。

规则	文件	关键模式
Playwright + axe	rules/a11y-playwright.md	WCAG 2.2 AA、交互状态测试

import AxeBuilder from '@axe-core/playwright';

test('page meets WCAG 2.2 AA', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page })
    .withTags(['wcag2a', 'wcag2aa', 'wcag22aa'])
    .analyze();
  expect(results.violations).toEqual([]);
});

可访问性（CI/CD）

CI 流水线集成和基于 jest-axe 的单元级组件测试。

规则	文件	关键模式
CI 门禁 + jest-axe	rules/a11y-testing.md	阻止 PR、组件状态测试

端到端类型

确保各 API 层的类型安全，以消除运行时类型错误。

规则	文件	关键模式
类型安全	rules/validation-end-to-end.md	tRPC、Zod、Pydantic、模式拒绝测试

视觉回归

使用 Playwright 原生截图比较，无需外部服务。

await expect(page).toHaveScreenshot('checkout-page.png', {
  maxDiffPixels: 100,
  mask: [page.locator('.dynamic-content')],
});

供应商文档未提及的内部规则（仅用于 CI 的基线、单一快照项目、超出阈值时进行遮罩）：references/ork-delta.md。选项参考和基线工作流本身：请参阅上方的上游覆盖表。

关键决策

决策	建议
E2E 框架	使用 Playwright 1.59+ 和语义定位器
定位器策略	getByRole > getByLabel > getByTestId
浏览器	Chromium（1.59+ 中的 Chrome for Testing）
页面模式	复杂页面使用页面对象模型
视觉回归	Playwright 原生 toHaveScreenshot()
A11y 测试	axe-core（E2E）+ jest-axe（单元测试）
CI 重试	CI 中重试 2-3 次，本地重试 0 次
不稳定测试检测	在 CI 中设置 failOnFlakyTests: true
AI Agent	通过 init-agents 使用 Planner/Generator/Healer
类型安全	端到端使用 tRPC，运行时验证使用 Zod

参考资料

资源	描述
references/ork-delta.md	供应商文档未说明的项目规则：使用 jest-axe 而不是 vitest-axe、仅通过 CLI 初始化 Agent、仅在 CI 中建立基线、使用单个快照项目、使用遮罩而不是阈值
references/playwright-setup.md	安装、MCP 服务、种子测试、Agent 初始化

检查清单

检查清单	描述
checklists/e2e-checklist.md	定位器策略、页面对象、CI/CD、视觉回归
checklists/e2e-testing-checklist.md	全面涵盖：规划、实现、SSE、响应式设计、维护
checklists/a11y-testing-checklist.md	自动化 + 手动测试：键盘、屏幕阅读器、色彩对比度、WCAG

示例

示例	描述
examples/orchestkit-e2e-tests.md	OrchestKit 分析流程：页面对象、SSE 进度、错误处理

通用 Playwright 示例（用户流程、身份验证固件、API 模拟、多标签页、文件上传、axe 扫描）现在由 Upstream 覆盖范围表中的供应商页面提供。

脚本

脚本	描述
scripts/create-page-object.md	根据自动检测的模式生成 Playwright 页面对象

相关技能

• testing-unit - 使用模拟、固件和数据工厂的单元测试模式
• testing-integration - API 边界和契约测试
• cover - 当测试套件尚不存在时，生成 E2E 层
• verify - 评估现有测试套件并给出合并结论
• expect - 通过 agent-browser 进行差异感知的浏览器验证
• emulate-seed - 为 emulate 提供程序编写种子配置
• portless（上游）- 为本地 E2E 测试提供稳定的 HTTPS baseURL（使用 https://myapp.localhost，无需猜测端口；自 portless 0.10 起默认通过 HTTPS 使用 443 端口）