Back to Details

e2e-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

E2E Testing

E2E测试

Overview

概述

Covers E2E test architecture and patterns using Playwright — how to structure test suites, organize tests, and apply proven patterns for authentication, mocking, visual regression, accessibility auditing, and CI parallelism. Focuses on the WHY and WHEN of test patterns rather than Playwright API specifics.
When to use: Designing test suite architecture, structuring Page Object Models, planning CI sharding strategies, setting up authentication flows, organizing tests with tags and annotations, implementing visual regression workflows, mocking network requests, auditing accessibility.
When NOT to use: Unit testing (use Vitest/Jest), API-only testing (use integration tests), component testing in isolation (use component test runners). For Playwright API details, browser automation, scraping, or troubleshooting Playwright errors, use the 
playwright
skill.
本文介绍基于Playwright的E2E测试架构与模式——包括如何构建测试套件、组织测试，以及在认证、模拟、视觉回归、可访问性审计和CI并行执行等场景下应用经过验证的模式。重点讲解测试模式的应用原因与适用场景，而非Playwright API的具体细节。
适用场景： 设计测试套件架构、构建Page Object Model、规划CI分片策略、设置认证流程、使用标签和注解组织测试、实现视觉回归工作流、模拟网络请求、可访问性审计。
不适用场景： 单元测试（请使用Vitest/Jest）、仅API测试（请使用集成测试）、独立组件测试（请使用组件测试运行器）。若需了解Playwright API细节、浏览器自动化、网页爬取或排查Playwright错误，请使用
playwright
技能。

Quick Reference

快速参考

PatternAPI/ToolKey Points
Role-based locators
getByRole
, 
getByText
, 
getByLabel
Preferred over CSS/XPath selectors
Page Object ModelClasses in 
tests/pages/
Encapsulate all page-specific locators and actions
Authentication
storageState
+ setup projects		Authenticate once, reuse across tests
Visual regression
expect(page).toHaveScreenshot()
Mask dynamic content to prevent flakes
Accessibility audit
AxeBuilder
from 
@axe-core/playwright
.withTags()
+ 
.analyze()
on key flows
Trace debugging
trace: 'on-first-retry'
Full DOM snapshots, network logs, and timeline
Network mocking
page.route()
Stable tests without third-party dependencies
HAR replay
page.routeFromHAR()
High-fidelity mocks from recorded traffic
Image blocking
page.route('**/*.{png,jpg}', abort)
Speed up tests by skipping images
CI sharding
--shard=1/4
Split suite across parallel CI machines
Blob reports
--reporter=blob
+ 
merge-reports
Merge sharded results into a single report
Test tags
{ tag: ['@smoke'] }
Filter tests by category with 
--grep
Test steps
test.step('name', async () => {})
Group actions in trace viewer and reports
Changed tests only
--only-changed=$GITHUB_BASE_REF
Run only test files changed since base branch
Native a11y checks
toHaveAccessibleName
, 
toHaveRole
Lightweight alternative to full axe-core scans
Git info in reports
captureGitInfo
reporter option		Link test reports to commits for CI debugging
Web-first assertions
expect(element).toBeVisible()
Auto-wait instead of 
waitForTimeout
模式API/工具核心要点
基于角色的定位器
getByRole
, 
getByText
, 
getByLabel
优先于CSS/XPath选择器使用
Page Object Model
tests/pages/
中的类		封装所有页面专属的定位器与操作
认证机制
storageState
+ 初始化项目		仅认证一次，在所有测试中复用状态
视觉回归测试
expect(page).toHaveScreenshot()
屏蔽动态内容以避免不稳定测试
可访问性审计
@axe-core/playwright
中的
AxeBuilder
针对核心流程使用
.withTags()
+ 
.analyze()
追踪调试
trace: 'on-first-retry'
完整DOM快照、网络日志与时间线记录
网络模拟
page.route()
脱离第三方依赖，实现稳定测试
HAR重放
page.routeFromHAR()
基于录制流量生成高保真模拟数据
图片拦截
page.route('**/*.{png,jpg}', abort)
跳过图片加载以加速测试
CI分片
--shard=1/4
在多台并行CI机器上拆分测试套件
Blob报告
--reporter=blob
+ 
merge-reports
将分片测试结果合并为单个报告
测试标签
{ tag: ['@smoke'] }
使用
--grep
按类别筛选测试
测试步骤
test.step('name', async () => {})
在追踪查看器与报告中分组展示操作
仅运行变更测试
--only-changed=$GITHUB_BASE_REF
仅运行自基准分支以来修改过的测试文件
原生可访问性检查
toHaveAccessibleName
, 
toHaveRole
轻量级替代方案，无需完整axe-core扫描
报告中嵌入Git信息
captureGitInfo
报告选项		将测试报告与提交记录关联，便于CI调试
优先Web断言
expect(element).toBeVisible()
使用自动等待替代
waitForTimeout

Common Mistakes

常见误区

MistakeCorrect Pattern
Using 
page.waitForTimeout()
for element visibility		Use web-first assertions like 
expect(element).toBeVisible()
which auto-wait
Writing raw locators directly in test filesEncapsulate all selectors in Page Object Model classes
Testing third-party APIs (Stripe, Auth0) directlyMock external services with 
page.route()
for stable, fast tests
Debugging CI failures with screenshots instead of tracesConfigure 
trace: 'on-first-retry'
and use Playwright Trace Viewer
Sharing state between tests via global variablesUse a fresh 
BrowserContext
per test for full isolation
Running all tests in a single CI jobUse Playwright sharding (
--shard=1/N
) across parallel machines
Using CSS/XPath selectors for element locationUse role-based locators that survive refactors and enforce accessibility
Logging in via UI in every testUse 
storageState
with setup projects to authenticate once
Using 
injectAxe
/
checkA11y
from 
axe-playwright
Use 
AxeBuilder
from 
@axe-core/playwright
with 
.analyze()
Committing 
storageState
JSON files to git		Add 
playwright/.auth/
to 
.gitignore
错误做法正确解决方案
使用
page.waitForTimeout()
等待元素可见		使用
expect(element).toBeVisible()
这类优先Web断言，支持自动等待
在测试文件中直接编写原生定位器将所有选择器封装到Page Object Model类中
直接测试第三方API（如Stripe、Auth0）使用
page.route()
模拟外部服务，实现稳定、快速的测试
仅通过截图调试CI失败问题配置
trace: 'on-first-retry'
并使用Playwright Trace Viewer进行调试
通过全局变量在测试间共享状态为每个测试使用全新的
BrowserContext
实现完全隔离
在单个CI任务中运行所有测试使用Playwright分片功能（
--shard=1/N
）在多台并行机器上执行测试
使用CSS/XPath选择器定位元素使用基于角色的定位器，可在重构后仍保持有效且符合可访问性要求
在每个测试中通过UI重新登录结合
storageState
与初始化项目，仅执行一次认证
使用
axe-playwright
中的
injectAxe
/
checkA11y
使用
@axe-core/playwright
中的
AxeBuilder
并调用
.analyze()
将
storageState
JSON文件提交到Git仓库		将
playwright/.auth/
添加到
.gitignore
文件中

Delegation

任务委托

  • Discover which user flows lack E2E coverage: Use 
    Explore
    agent
  • Build a full Page Object Model test suite for an application: Use 
    Task
    agent
  • Plan a CI sharding strategy for a large test suite: Use 
    Plan
    agent
For Playwright API details, browser automation, scraping, stealth mode, screenshots/PDFs, Docker deployment, or troubleshooting Playwright errors, use the 
playwright
skill.
  • 发现缺少E2E覆盖的用户流程：使用
    Explore
    agent
  • 为应用构建完整的Page Object Model测试套件：使用
    Task
    agent
  • 为大型测试套件规划CI分片策略：使用
    Plan
    agent
若需了解Playwright API细节、浏览器自动化、网页爬取、隐身模式、截图/PDF生成、Docker部署或排查Playwright错误，请使用
playwright
技能。

References

参考资料

  • Role-based locators, auto-waiting, chaining, filtering, and locator strategy
  • Page Object Model architecture, fixtures integration, and base page patterns
  • Authentication with storageState, setup projects, and multi-role testing
  • Network mocking, route interception, HAR replay, and WebSocket mocking
  • Accessibility auditing with AxeBuilder, WCAG tags, and reusable fixtures
  • Visual regression, snapshot testing, masking, tolerance thresholds, and baseline management
  • CI sharding, parallelism, blob reports, and browser caching
  • Test organization with tags, annotations, test.step, and project configuration
  • 基于角色的定位器、自动等待、链式调用、筛选与定位策略
  • Page Object Model架构、fixtures集成与基础页面模式
  • 基于storageState的认证、初始化项目与多角色测试
  • 网络模拟、路由拦截、HAR重放与WebSocket模拟
  • 基于AxeBuilder的可访问性审计、WCAG标签与可复用fixtures
  • 视觉回归、快照测试、内容屏蔽、容差阈值与基线管理
  • CI分片、并行执行、Blob报告与浏览器缓存
  • 基于标签、注解、test.step与项目配置的测试组织