--- name: playwright-skill description: 经实战检验的 Playwright 模式，涵盖 E2E、API、组件、视觉、无障碍和安全性测试。包括定位器、夹具、POM、网络模拟、认证流程、调试、CI/CD（GitHub Actions、GitLab、CircleCI、Azure、Jenkins）、框架方案（React、Next.js、Vue、Angular）以及从 Cypress/Selenium 的迁移指南。TypeScript 与 JavaScript。 --- # Playwright 技能 > 有主见的、经过生产验证的 Playwright 指南——每个模式都包含何时使用（以及何时**不**该使用）。 **50 多份参考指南**覆盖 Playwright 的全部领域：选择器、断言、夹具、页面对象、网络模拟、认证、视觉回归、无障碍、API 测试、CI/CD、调试等——全程附带 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. **追踪：`'on-first-retry'`**——在不拖慢 CI 的前提下获取丰富的调试工件 8. **使用 Fixture 而非全局变量**——通过 `test.extend()` 共享状态，而非模块级变量 9. **每个测试只测一个行为**——多个相关的 `expect()` 调用是允许的 10. **仅模拟外部服务**——永远不要模拟你自己的应用；模拟第三方 API、支付网关、电子邮件 ## 指南索引 ### 编写测试 | 你要做的事情 | 指南 | 深入探讨 | | -------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------- | | 选择选择器 | [locators.md](core/locators.md) | [locator-strategy.md](core/locator-strategy.md) | | 断言与等待 | [assertions-and-waiting.md](core/assertions-and-waiting.md) | | | 组织测试套件 | [test-organization.md](core/test-organization.md) | [test-architecture.md](core/test-architecture.md) | | Playwright 配置 | [configuration.md](core/configuration.md) | | | 页面对象 | [page-object-model.md](pom/page-object-model.md) | [pom-vs-fixtures-vs-helpers.md](pom/pom-vs-fixtures-vs-helpers.md) | | Fixture 与钩子 | [fixtures-and-hooks.md](core/fixtures-and-hooks.md) | | | 测试数据 | [test-data-management.md](core/test-data-management.md) | | | 认证与登录 | [authentication.md](core/authentication.md) | [auth-flows.md](core/auth-flows.md) | | API 测试（REST/GraphQL） | [api-testing.md](core/api-testing.md) | | | 视觉回归 | [visual-regression.md](core/visual-regression.md) | | | 无障碍 | [accessibility.md](core/accessibility.md) | | | 移动端与响应式 | [mobile-and-responsive.md](core/mobile-and-responsive.md) | | | 组件测试 | [component-testing.md](core/component-testing.md) | | | 网络模拟 | [network-mocking.md](core/network-mocking.md) | [when-to-mock.md](core/when-to-mock.md) | | 表单与验证 | [forms-and-validation.md](core/forms-and-validation.md) | | | 文件上传/下载 | [file-operations.md](core/file-operations.md) | [file-upload-download.md](core/file-upload-download.md) | | 错误与边界情况 | [error-and-edge-cases.md](core/error-and-edge-cases.md) | | | CRUD 流程 | [crud-testing.md](core/crud-testing.md) | | | 拖放 | [drag-and-drop.md](core/drag-and-drop.md) | | | 搜索与筛选 UI | [search-and-filter.md](core/search-and-filter.md) | | ### 调试与修复 | 问题 | 指南 | | -------------------------- | ------------------------------------------------ | | 通用调试流程 | [debugging.md](core/debugging.md) | | 特定错误信息 | [error-index.md](core/error-index.md) | | 不稳定/间歇性测试 | [flaky-tests.md](core/flaky-tests.md) | | 常见新手错误 | [common-pitfalls.md](core/common-pitfalls.md) | ### 框架方案 | 框架 | 指南 | | ------------------------------------ | -------------------------------- | | Next.js（App Router + Pages Router） | [nextjs.md](core/nextjs.md) | | React（CRA、Vite） | [react.md](core/react.md) | | Vue 3 / Nuxt | [vue.md](core/vue.md) | | Angular | [angular.md](core/angular.md) | ### 迁移指南 | 从 | 指南 | | -------------------- | ------------------------------------------------- | | Cypress | [from-cypress.md](migration/from-cypress.md) | | Selenium / WebDriver | [from-selenium.md](migration/from-selenium.md) | ### 架构决策 | 问题 | 指南 | | ---------------------------- | -------------------------------------------------------------------- | | 选择哪种定位器策略？ | [locator-strategy.md](core/locator-strategy.md) | | E2E vs 组件 vs API？ | [test-architecture.md](core/test-architecture.md) | | 模拟还是真实服务？ | [when-to-mock.md](core/when-to-mock.md) | | POM vs Fixture vs 辅助函数？ | [pom-vs-fixtures-vs-helpers.md](pom/pom-vs-fixtures-vs-helpers.md) | ### CI/CD 与基础设施 | 主题 | 指南 | | -------------------------------- | ------------------------------------------------------------------ | | GitHub Actions | [ci-github-actions.md](ci/ci-github-actions.md) | | GitLab CI | [ci-gitlab.md](ci/ci-gitlab.md) | | CircleCI / Azure DevOps / Jenkins| [ci-other.md](ci/ci-other.md) | | 并行执行与分片 | [parallel-and-sharding.md](ci/parallel-and-sharding.md) | | Docker 与容器 | [docker-and-containers.md](ci/docker-and-containers.md) | | 报告与工件 | [reporting-and-artifacts.md](ci/reporting-and-artifacts.md) | | 代码覆盖率 | [test-coverage.md](ci/test-coverage.md) | | 全局设置/清理 | [global-setup-teardown.md](ci/global-setup-teardown.md) | | 多项目配置 | [projects-and-dependencies.md](ci/projects-and-dependencies.md) | ### 专题 | 主题 | 指南 | | ------------------------------------------- | -------------------------------------------------------------------------- | | 多用户与协作 | [multi-user-and-collaboration.md](core/multi-user-and-collaboration.md) | | WebSocket 与实时通信 | [websockets-and-realtime.md](core/websockets-and-realtime.md) | | 浏览器 API（地理、剪贴板、权限） | [browser-apis.md](core/browser-apis.md) | | iframe 与 Shadow DOM | [iframes-and-shadow-dom.md](core/iframes-and-shadow-dom.md) | | Canvas 与 WebGL | [canvas-and-webgl.md](core/canvas-and-webgl.md) | | Service Worker 与 PWA | [service-workers-and-pwa.md](core/service-workers-and-pwa.md) | | Electron 应用 | [electron-testing.md](core/electron-testing.md) | | 浏览器扩展 | [browser-extensions.md](core/browser-extensions.md) | | 安全性测试 | [security-testing.md](core/security-testing.md) | | 性能与基准测试 | [performance-testing.md](core/performance-testing.md) | | 国际化与本地化 | [i18n-and-localization.md](core/i18n-and-localization.md) | | 多标签页与弹窗 | [multi-context-and-popups.md](core/multi-context-and-popups.md) | | 时钟与时间模拟 | [clock-and-time-mocking.md](core/clock-and-time-mocking.md) | | 第三方集成 | [third-party-integrations.md](core/third-party-integrations.md) | ### CLI 浏览器自动化 | 你要做的事情 | 指南 | | -------------------------------------- | ---------------------------------------------------------------------- | | CLI 浏览器交互 | [playwright-cli/SKILL.md](playwright-cli/SKILL.md) | | 核心命令（open、click、fill、navigate）| [core-commands.md](playwright-cli/core-commands.md) | | 网络模拟与拦截 | [request-mocking.md](playwright-cli/request-mocking.md) | | 运行自定义 Playwright 代码 | [running-custom-code.md](playwright-cli/running-custom-code.md) | | 多会话浏览器管理 | [session-management.md](playwright-cli/session-management.md) | | Cookie、localStorage、认证状态 | [storage-and-auth.md](playwright-cli/storage-and-auth.md) | | 从 CLI 生成测试代码 | [test-generation.md](playwright-cli/test-generation.md) | | 追踪与调试 | [tracing-and-debugging.md](playwright-cli/tracing-and-debugging.md) | | 截图、视频、PDF | [screenshots-and-media.md](playwright-cli/screenshots-and-media.md) | | 设备与环境模拟 | [device-emulation.md](playwright-cli/device-emulation.md) | | 复杂多步骤流程 | [advanced-workflows.md](playwright-cli/advanced-workflows.md) | ## 语言说明 所有指南均包含 TypeScript 和 JavaScript 示例。当项目使用 `.js` 文件或没有 `tsconfig.json` 时，示例会调整为纯 JavaScript。