---
name: playwright-core
description: 经过实战检验的 Playwright 模式，涵盖 E2E、API、组件、视觉、无障碍和安全测试。包含定位器、断言、fixture、网络模拟、身份验证流程、调试，以及 React、Next.js、Vue 和 Angular 的框架方案。支持 TypeScript 和 JavaScript。
---

# Playwright 核心测试

> 经过实战检验的、具有明确意见的 Playwright 指南——每个模式都包含何时使用（以及何时**不**使用）的说明。

**46 份参考指南**，涵盖 Playwright 的完整测试领域：选择器、断言、fixture、网络模拟、身份验证、视觉回归、无障碍、API 测试、调试等——通篇附有 TypeScript 和 JavaScript 示例。

## 黄金法则

1. **优先使用 `getByRole()` 而非 CSS/XPath**——对标记更改具有弹性，反映用户浏览页面的方式
2. **永远不要使用 `page.waitForTimeout()`**——应使用 `expect(locator).toBeVisible()` 或 `page.waitForURL()`
3. **优先使用 Web 优先的断言**——`expect(locator)` 会自动重试；`expect(await locator.textContent())` 则不会
4. **每个测试相互隔离**——无共享状态，无执行顺序依赖
5. **在配置中设置 `baseURL`**——测试中不包含硬编码的 URL
6. **重试策略：CI 设为 `2`，本地设为 `0`**——在关键环境中暴露不稳定问题
7. **Trace 设置：`'on-first-retry'`**——在不拖慢 CI 的前提下提供丰富的调试信息
8. **优先使用 Fixture 而非全局变量**——通过 `test.extend()` 共享状态，而非使用模块级变量
9. **每个测试只测一个行为**——多个相关的 `expect()` 调用是可以的
10. **仅模拟外部服务**——永远不要模拟你自己的应用；模拟第三方 API、支付网关、电子邮件

## 指南索引

### 编写测试

| 你要做的事                 | 指南                                                | 深入探讨                                          |
| -------------------------- | --------------------------------------------------- | ------------------------------------------------- |
| 选择选择器策略             | [locators.md](locators.md)                          | [locator-strategy.md](locator-strategy.md)        |
| 断言与等待                 | [assertions-and-waiting.md](assertions-and-waiting.md) |                                                   |
| 组织测试套件               | [test-organization.md](test-organization.md)        | [test-architecture.md](test-architecture.md)      |
| Playwright 配置            | [configuration.md](configuration.md)                |                                                   |
| Fixture 与钩子             | [fixtures-and-hooks.md](fixtures-and-hooks.md)      |                                                   |
| 测试数据                   | [test-data-management.md](test-data-management.md)  |                                                   |
| 身份验证与登录             | [authentication.md](authentication.md)              | [auth-flows.md](auth-flows.md)                    |
| API 测试（REST/GraphQL）   | [api-testing.md](api-testing.md)                    |                                                   |
| 视觉回归测试               | [visual-regression.md](visual-regression.md)        |                                                   |
| 无障碍测试                 | [accessibility.md](accessibility.md)                |                                                   |
| 移动端与响应式测试         | [mobile-and-responsive.md](mobile-and-responsive.md) |                                                   |
| 组件测试                   | [component-testing.md](component-testing.md)        |                                                   |
| 网络模拟                   | [network-mocking.md](network-mocking.md)            | [when-to-mock.md](when-to-mock.md)                |
| 表单与验证                 | [forms-and-validation.md](forms-and-validation.md)  |                                                   |
| 文件上传与下载             | [file-operations.md](file-operations.md)            | [file-upload-download.md](file-upload-download.md) |
| 错误与边界情况             | [error-and-edge-cases.md](error-and-edge-cases.md)  |                                                   |
| CRUD 流程                  | [crud-testing.md](crud-testing.md)                  |                                                   |
| 拖放操作                   | [drag-and-drop.md](drag-and-drop.md)                |                                                   |
| 搜索与筛选 UI              | [search-and-filter.md](search-and-filter.md)        |                                                   |

### 调试与修复

| 问题                       | 指南                                          |
| -------------------------- | --------------------------------------------- |
| 通用调试流程               | [debugging.md](debugging.md)                  |
| 特定错误信息               | [error-index.md](error-index.md)              |
| 不稳定 / 间歇性测试        | [flaky-tests.md](flaky-tests.md)              |
| 新手常见错误               | [common-pitfalls.md](common-pitfalls.md)      |

### 框架方案

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

### 专题

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

### 架构决策

| 问题                         | 指南                                          |
| ---------------------------- | --------------------------------------------- |
| 选择哪种选择器策略？         | [locator-strategy.md](locator-strategy.md)    |
| E2E vs 组件 vs API？         | [test-architecture.md](test-architecture.md)  |
| 模拟 vs 真实服务？           | [when-to-mock.md](when-to-mock.md)            |