playwright

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Playwright + Next.js Testing Best Practices

Playwright + Next.js 测试最佳实践

Comprehensive testing optimization guide for Playwright with Next.js applications. Contains 43 rules across 8 categories, prioritized by impact to guide reliable, fast, and maintainable E2E tests.

针对Next.js应用的Playwright全面测试优化指南。包含8个类别下的43条规则，按影响程度排序，指导编写可靠、快速且可维护的E2E测试。

When to Apply

适用场景

Reference these guidelines when:

Writing new Playwright tests for Next.js apps
Debugging flaky or failing tests
Optimizing test execution speed
Setting up authentication state reuse
Configuring CI/CD pipelines for testing
Testing Server Components and App Router features
Reviewing test code for reliability issues

在以下场景中参考这些指南：

为Next.js应用编写新的Playwright测试
调试不稳定或失败的测试
优化测试执行速度
设置认证状态复用
配置用于测试的CI/CD流水线
测试Server Components和App Router功能
评审测试代码以排查可靠性问题

Rule Categories by Priority

按优先级划分的规则类别


arch-
loc-
wait-
auth-
mock-
next-
perf-
debug-

Priority	Category	Impact	Prefix
1	Test Architecture	CRITICAL	`arch-`
2	Selectors & Locators	CRITICAL	`loc-`
3	Waiting & Assertions	HIGH	`wait-`
4	Authentication & State	HIGH	`auth-`
5	Mocking & Network	MEDIUM-HIGH	`mock-`
6	Next.js Integration	MEDIUM	`next-`
7	Performance & Speed	MEDIUM	`perf-`
8	Debugging & CI	LOW-MEDIUM	`debug-`


arch-
loc-
wait-
auth-
mock-
next-
perf-
debug-

优先级	类别	影响程度	前缀
1	测试架构	关键	`arch-`
2	选择器与定位器	关键	`loc-`
3	等待与断言	高	`wait-`
4	认证与状态	高	`auth-`
5	模拟与网络	中高	`mock-`
6	Next.js集成	中	`next-`
7	性能与速度	中	`perf-`
8	调试与CI	中低	`debug-`

Quick Reference

快速参考

1. Test Architecture (CRITICAL)

1. 测试架构（关键）

```
arch-test-isolation
```
- Use fresh browser context for each test
```
arch-parallel-execution
```
- Enable parallel test execution
```
arch-page-object-model
```
- Use Page Object Model for complex pages
```
arch-fixtures
```
- Use fixtures for shared setup
```
arch-test-production
```
- Test against production builds
```
arch-cleanup-state
```
- Clean up test state after each test

```
arch-test-isolation
```
- 为每个测试使用全新的浏览器上下文
```
arch-parallel-execution
```
- 启用测试并行执行
```
arch-page-object-model
```
- 为复杂页面使用Page Object Model
```
arch-fixtures
```
- 使用fixtures进行共享设置
```
arch-test-production
```
- 针对生产构建进行测试
```
arch-cleanup-state
```
- 每个测试后清理测试状态

2. Selectors & Locators (CRITICAL)

2. 选择器与定位器（关键）

```
loc-role-selectors
```
- Use role-based selectors over CSS
```
loc-data-testid
```
- Use data-testid for dynamic elements
```
loc-label-selectors
```
- Use getByLabel for form inputs
```
loc-text-selectors
```
- Use getByText for static content
```
loc-avoid-xpath
```
- Avoid XPath selectors
```
loc-chained-locators
```
- Chain locators for specificity
```
loc-placeholder-selector
```
- Use getByPlaceholder sparingly

```
loc-role-selectors
```
- 优先使用基于角色的选择器而非CSS选择器
```
loc-data-testid
```
- 为动态元素使用data-testid
```
loc-label-selectors
```
- 为表单输入使用getByLabel
```
loc-text-selectors
```
- 为静态内容使用getByText
```
loc-avoid-xpath
```
- 避免使用XPath选择器
```
loc-chained-locators
```
- 链式使用定位器以提高特异性
```
loc-placeholder-selector
```
- 谨慎使用getByPlaceholder

3. Waiting & Assertions (HIGH)

3. 等待与断言（高）

```
wait-web-first-assertions
```
- Use web-first assertions
```
wait-avoid-hard-waits
```
- Avoid hard waits
```
wait-network-idle
```
- Use network idle for complex pages
```
wait-action-retries
```
- Let actions auto-wait before interacting
```
wait-soft-assertions
```
- Use soft assertions for non-critical checks
```
wait-custom-timeout
```
- Configure timeouts appropriately

```
wait-web-first-assertions
```
- 使用web-first断言
```
wait-avoid-hard-waits
```
- 避免硬等待
```
wait-network-idle
```
- 为复杂页面使用网络空闲状态
```
wait-action-retries
```
- 让操作在交互前自动等待
```
wait-soft-assertions
```
- 为非关键检查使用软断言
```
wait-custom-timeout
```
- 合理配置超时时间

4. Authentication & State (HIGH)

4. 认证与状态（高）

```
auth-storage-state
```
- Reuse authentication with storage state
```
auth-multiple-roles
```
- Use separate storage states for different roles
```
auth-session-storage
```
- Handle session storage for auth
```
auth-api-login
```
- Use API login for faster auth setup
```
auth-parallel-workers
```
- Use worker-scoped auth for parallel tests

```
auth-storage-state
```
- 使用存储状态复用认证信息
```
auth-multiple-roles
```
- 为不同角色使用独立的存储状态
```
auth-session-storage
```
- 处理认证相关的会话存储
```
auth-api-login
```
- 使用API登录以加快认证设置
```
auth-parallel-workers
```
- 为并行测试使用工作进程级别的认证

5. Mocking & Network (MEDIUM-HIGH)

5. 模拟与网络（中高）

```
mock-api-responses
```
- Mock API responses for deterministic tests
```
mock-intercept-modify
```
- Intercept and modify real responses
```
mock-har-files
```
- Use HAR files for complex mock scenarios
```
mock-abort-requests
```
- Abort unnecessary requests
```
mock-network-conditions
```
- Simulate network conditions

```
mock-api-responses
```
- 模拟API响应以实现确定性测试
```
mock-intercept-modify
```
- 拦截并修改真实响应
```
mock-har-files
```
- 为复杂模拟场景使用HAR文件
```
mock-abort-requests
```
- 中止不必要的请求
```
mock-network-conditions
```
- 模拟网络条件

6. Next.js Integration (MEDIUM)

6. Next.js集成（中）

```
next-wait-hydration
```
- Wait for hydration before interacting
```
next-server-components
```
- Test server components correctly
```
next-app-router-navigation
```
- Test App Router navigation patterns
```
next-server-actions
```
- Test server actions end-to-end
```
next-baseurl-config
```
- Configure baseURL for clean navigation

```
next-wait-hydration
```
- 交互前等待水合完成
```
next-server-components
```
- 正确测试Server Components
```
next-app-router-navigation
```
- 测试App Router导航模式
```
next-server-actions
```
- 端到端测试Server Actions
```
next-baseurl-config
```
- 配置baseURL以实现清晰导航

7. Performance & Speed (MEDIUM)

7. 性能与速度（中）

```
perf-sharding
```
- Use sharding for large test suites
```
perf-headless-ci
```
- Use headless mode in CI
```
perf-browser-selection
```
- Select browsers strategically
```
perf-reuse-server
```
- Reuse development server when possible
```
perf-retries
```
- Configure retries for flaky test recovery

```
perf-sharding
```
- 为大型测试套件使用分片
```
perf-headless-ci
```
- 在CI中使用无头模式
```
perf-browser-selection
```
- 策略性选择浏览器
```
perf-reuse-server
```
- 尽可能复用开发服务器
```
perf-retries
```
- 配置重试以恢复不稳定测试

8. Debugging & CI (LOW-MEDIUM)

8. 调试与CI（中低）

```
debug-trace-viewer
```
- Use trace viewer for failed tests
```
debug-screenshots-videos
```
- Capture screenshots and videos on failure
```
debug-inspector
```
- Use Playwright Inspector for interactive debugging
```
debug-ci-reporters
```
- Configure reporters for CI integration

```
debug-trace-viewer
```
- 为失败测试使用跟踪查看器
```
debug-screenshots-videos
```
- 测试失败时捕获截图和视频
```
debug-inspector
```
- 使用Playwright Inspector进行交互式调试
```
debug-ci-reporters
```
- 配置报告器以集成CI

How to Use

使用方法

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

阅读单个参考文件以获取详细说明和代码示例：

Section definitions - 类别结构和影响级别
Rule template - 添加新规则的模板

Reference Files

参考文件

File	Description
AGENTS.md	Complete compiled guide with all rules
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义和排序
assets/templates/_template.md	新规则模板
metadata.json	版本和参考信息