skillhub-147-playwright-skill/SKILL.md

name, description

name	description
playwright-skill	经实战检验的 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	locator-strategy.md
断言与等待	assertions-and-waiting.md
组织测试套件	test-organization.md	test-architecture.md
Playwright 配置	configuration.md
页面对象	page-object-model.md	pom-vs-fixtures-vs-helpers.md
Fixture 与钩子	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.md
特定错误信息	error-index.md
不稳定/间歇性测试	flaky-tests.md
常见新手错误	common-pitfalls.md

框架方案

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

迁移指南

从	指南
Cypress	from-cypress.md
Selenium / WebDriver	from-selenium.md

架构决策

问题	指南
选择哪种定位器策略？	locator-strategy.md
E2E vs 组件 vs API？	test-architecture.md
模拟还是真实服务？	when-to-mock.md
POM vs Fixture vs 辅助函数？	pom-vs-fixtures-vs-helpers.md

CI/CD 与基础设施

主题	指南
GitHub Actions	ci-github-actions.md
GitLab CI	ci-gitlab.md
CircleCI / Azure DevOps / Jenkins	ci-other.md
并行执行与分片	parallel-and-sharding.md
Docker 与容器	docker-and-containers.md
报告与工件	reporting-and-artifacts.md
代码覆盖率	test-coverage.md
全局设置/清理	global-setup-teardown.md
多项目配置	projects-and-dependencies.md

专题

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

CLI 浏览器自动化

你要做的事情	指南
CLI 浏览器交互	playwright-cli/SKILL.md
核心命令（open、click、fill、navigate）	core-commands.md
网络模拟与拦截	request-mocking.md
运行自定义 Playwright 代码	running-custom-code.md
多会话浏览器管理	session-management.md
Cookie、localStorage、认证状态	storage-and-auth.md
从 CLI 生成测试代码	test-generation.md
追踪与调试	tracing-and-debugging.md
截图、视频、PDF	screenshots-and-media.md
设备与环境模拟	device-emulation.md
复杂多步骤流程	advanced-workflows.md

语言说明

所有指南均包含 TypeScript 和 JavaScript 示例。当项目使用 .js 文件或没有 tsconfig.json 时，示例会调整为纯 JavaScript。