playwright-skill

Playwright 技能

主张明确、经过生产环境验证的 Playwright 指南——每种模式都说明何时（以及何时不）使用。

50+ 篇参考指南涵盖 Playwright 的完整功能范围：选择器、断言、fixture、页面对象、网络模拟、身份验证、视觉回归、无障碍、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、支付网关和邮件服务

指南索引

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
Page objects	page-object-model.md	pom-vs-fixtures-vs-helpers.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

调试与修复

问题	指南
通用调试工作流	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
端到端测试、组件测试还是 API 测试？	test-architecture.md
模拟服务还是真实服务？	when-to-mock.md
POM、fixtures 还是 helpers？	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
WebSockets 与实时功能	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 与本地化	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
Cookies、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。