playwright-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright Core Testing

Playwright核心测试

Opinionated, production-tested Playwright guidance — every pattern includes when (and when not) to use it.

46 reference guides covering the full Playwright testing surface: selectors, assertions, fixtures, network mocking, auth, visual regression, accessibility, API testing, debugging, and more — with TypeScript and JavaScript examples throughout.

具有明确实践导向、经生产环境验证的Playwright指南——每种模式都说明了适用场景（以及不适用的场景）。

46份参考指南覆盖Playwright测试的全场景：选择器、断言、测试夹具、网络模拟、认证、可视化回归测试、无障碍测试、API测试、调试等——全程包含TypeScript和JavaScript示例。

Golden Rules

黄金准则

getByRole()
over CSS/XPath — resilient to markup changes, mirrors how users see the page

Never
page.waitForTimeout()
— use

expect(locator).toBeVisible()

page.waitForURL()

Web-first assertions —

expect(locator)

auto-retries;

expect(await locator.textContent())

does not

Isolate every test — no shared state, no execution-order dependencies
baseURL
in config — zero hardcoded URLs in tests
Retries:
2
in CI,
0
locally — surface flakiness where it matters
Traces:
'on-first-retry'
— rich debugging artifacts without CI slowdown
Fixtures over globals — share state via
```
test.extend()
```
, not module-level variables
One behavior per test — multiple related
```
expect()
```
calls are fine
Mock external services only — never mock your own app; mock third-party APIs, payment gateways, email

优先使用
getByRole()
而非CSS/XPath —— 不受标记变更影响，与用户查看页面的方式一致

绝对不要使用
page.waitForTimeout()
—— 改用

expect(locator).toBeVisible()

或

page.waitForURL()

优先使用Web原生断言 ——
```
expect(locator)
```
会自动重试；
```
expect(await locator.textContent())
```
则不会
每个测试保持独立 —— 不共享状态，无执行顺序依赖
在配置中设置
baseURL
—— 测试中绝对不要硬编码URL
重试次数：CI环境设为2，本地设为0 —— 在关键环境暴露不稳定测试问题
追踪记录：设为
'on-first-retry'
—— 生成丰富的调试产物，同时避免拖慢CI速度
优先使用测试夹具而非全局变量 —— 通过
```
test.extend()
```
共享状态，而非模块级变量
每个测试对应一个行为 —— 允许包含多个相关的
```
expect()
```
调用
仅模拟外部服务 —— 绝不模拟自身应用；仅模拟第三方API、支付网关、邮件服务等

Guide Index

指南索引

Writing Tests

编写测试

What you're doing	Guide	Deep dive
Choosing selectors	locators.md	locator-strategy.md
Assertions & waiting	assertions-and-waiting.md
Organizing test suites	test-organization.md	test-architecture.md
Playwright config	configuration.md
Fixtures & hooks	fixtures-and-hooks.md
Test data	test-data-management.md
Auth & login	authentication.md	auth-flows.md
API testing (REST/GraphQL)	api-testing.md
Visual regression	visual-regression.md
Accessibility	accessibility.md
Mobile & responsive	mobile-and-responsive.md
Component testing	component-testing.md
Network mocking	network-mocking.md	when-to-mock.md
Forms & validation	forms-and-validation.md
File uploads/downloads	file-operations.md	file-upload-download.md
Error & edge cases	error-and-edge-cases.md
CRUD flows	crud-testing.md
Drag and drop	drag-and-drop.md
Search & filter UI	search-and-filter.md

操作场景	指南	深度解析
选择选择器	locators.md	locator-strategy.md
断言与等待	assertions-and-waiting.md
组织测试套件	test-organization.md	test-architecture.md
Playwright配置	configuration.md
测试夹具与钩子	fixtures-and-hooks.md
测试数据	test-data-management.md
认证与登录	authentication.md	auth-flows.md
API测试（REST/GraphQL）	api-testing.md
可视化回归测试	visual-regression.md
无障碍测试	accessibility.md
移动端与响应式测试	mobile-and-responsive.md
组件测试	component-testing.md
网络模拟	network-mocking.md	when-to-mock.md
表单与验证	forms-and-validation.md
文件上传/下载	file-operations.md	file-upload-download.md
错误与边界用例	error-and-edge-cases.md
CRUD流程测试	crud-testing.md
拖拽测试	drag-and-drop.md
搜索与筛选UI测试	search-and-filter.md

Debugging & Fixing

调试与修复

Problem	Guide
General debugging workflow	debugging.md
Specific error message	error-index.md
Flaky / intermittent tests	flaky-tests.md
Common beginner mistakes	common-pitfalls.md

问题场景	指南
通用调试流程	debugging.md
特定错误信息	error-index.md
不稳定/间歇性失败测试	flaky-tests.md
常见新手误区	common-pitfalls.md

Framework Recipes

框架实践方案

Framework	Guide
Next.js (App Router + Pages Router)	nextjs.md
React (CRA, Vite)	react.md
Vue 3 / Nuxt	vue.md
Angular	angular.md

框架	指南
Next.js（App Router + Pages Router）	nextjs.md
React（CRA、Vite）	react.md
Vue 3 / Nuxt	vue.md
Angular	angular.md

Specialized Topics

专项主题

Topic	Guide
Multi-user & collaboration	multi-user-and-collaboration.md
WebSockets & real-time	websockets-and-realtime.md
Browser APIs (geo, clipboard, permissions)	browser-apis.md
iframes & Shadow DOM	iframes-and-shadow-dom.md
Canvas & WebGL	canvas-and-webgl.md
Service workers & PWA	service-workers-and-pwa.md
Electron apps	electron-testing.md
Browser extensions	browser-extensions.md
Security testing	security-testing.md
Performance & benchmarks	performance-testing.md
i18n & localization	i18n-and-localization.md
Multi-tab & popups	multi-context-and-popups.md
Clock & time mocking	clock-and-time-mocking.md
Third-party integrations	third-party-integrations.md

主题	指南
多用户与协作测试	multi-user-and-collaboration.md
WebSockets与实时功能测试	websockets-and-realtime.md
浏览器API（地理定位、剪贴板、权限）	browser-apis.md
内嵌框架（iframes）与Shadow DOM	iframes-and-shadow-dom.md
Canvas与WebGL测试	canvas-and-webgl.md
服务工作线程与PWA测试	service-workers-and-pwa.md
Electron应用测试	electron-testing.md
浏览器扩展测试	browser-extensions.md
安全测试	security-testing.md
性能与基准测试	performance-testing.md
国际化（i18n）与本地化	i18n-and-localization.md
多标签页与弹窗测试	multi-context-and-popups.md
时钟与时间模拟	clock-and-time-mocking.md
第三方集成测试	third-party-integrations.md

Architecture Decisions

架构决策

Question	Guide
Which locator strategy?	locator-strategy.md
E2E vs component vs API?	test-architecture.md
Mock vs real services?	when-to-mock.md

问题	指南
选择哪种定位器策略？	locator-strategy.md
端到端测试 vs 组件测试 vs API测试？	test-architecture.md
模拟服务还是使用真实服务？	when-to-mock.md