Playwright Skill
Opinionated, production-tested Playwright guidance — every pattern includes when (and when not) to use it.
50+ reference guides covering the full Playwright surface: selectors, assertions, fixtures, page objects, network mocking, auth, visual regression, accessibility, API testing, CI/CD, debugging, and more — with TypeScript and JavaScript examples throughout.
Golden Rules
getByRole() over CSS/XPath — resilient to markup changes, mirrors how users see the page- Never
page.waitForTimeout() — use expect(locator).toBeVisible() or page.waitForURL()
- Web-first assertions —
expect(locator) auto-retries; expect(await locator.textContent()) does not
- Isolate every test — no shared state, no execution-order dependencies
baseURL in config — zero hardcoded URLs in tests- Retries:
2 in CI, 0 locally — surface flakiness where it matters
- Traces:
'on-first-retry' — rich debugging artifacts without CI slowdown
- Fixtures over globals — share state via
test.extend(), not module-level variables
- One behavior per test — multiple related
expect() calls are fine
- Mock external services only — never mock your own app; mock third-party APIs, payment gateways, email
Guide Index
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 & Fixing
| Problem |
Guide |
| General debugging workflow |
debugging.md |
| Specific error message |
error-index.md |
| Flaky / intermittent tests |
flaky-tests.md |
| Common beginner mistakes |
common-pitfalls.md |
Framework Recipes
| Framework |
Guide |
| Next.js (App Router + Pages Router) |
nextjs.md |
| React (CRA, Vite) |
react.md |
| Vue 3 / Nuxt |
vue.md |
| Angular |
angular.md |
Migration Guides
| From |
Guide |
| Cypress |
from-cypress.md |
| Selenium / WebDriver |
from-selenium.md |
Architecture Decisions
| Question |
Guide |
| Which locator strategy? |
locator-strategy.md |
| E2E vs component vs API? |
test-architecture.md |
| Mock vs real services? |
when-to-mock.md |
| POM vs fixtures vs helpers? |
pom-vs-fixtures-vs-helpers.md |
CI/CD & Infrastructure
| Topic |
Guide |
| GitHub Actions |
ci-github-actions.md |
| GitLab CI |
ci-gitlab.md |
| CircleCI / Azure DevOps / Jenkins |
ci-other.md |
| Parallel execution & sharding |
parallel-and-sharding.md |
| Docker & containers |
docker-and-containers.md |
| Reports & artifacts |
reporting-and-artifacts.md |
| Code coverage |
test-coverage.md |
| Global setup/teardown |
global-setup-teardown.md |
| Multi-project config |
projects-and-dependencies.md |
Specialized Topics
| Topic |
Guide |
| Multi-user & collaboration |
multi-user-and-collaboration.md |
| WebSockets & real-time |
websockets-and-realtime.md |
| Browser APIs (geo, clipboard, permissions) |
browser-apis.md |
| iframes & Shadow DOM |
iframes-and-shadow-dom.md |
| Canvas & WebGL |
canvas-and-webgl.md |
| Service workers & PWA |
service-workers-and-pwa.md |
| Electron apps |
electron-testing.md |
| Browser extensions |
browser-extensions.md |
| Security testing |
security-testing.md |
| Performance & benchmarks |
performance-testing.md |
| i18n & localization |
i18n-and-localization.md |
| Multi-tab & popups |
multi-context-and-popups.md |
| Clock & time mocking |
clock-and-time-mocking.md |
| Third-party integrations |
third-party-integrations.md |
CLI Browser Automation
| What you're doing |
Guide |
| CLI browser interaction |
playwright-cli/SKILL.md |
| Core commands (open, click, fill, navigate) |
core-commands.md |
| Network mocking & interception |
request-mocking.md |
| Running custom Playwright code |
running-custom-code.md |
| Multi-session browser management |
session-management.md |
| Cookies, localStorage, auth state |
storage-and-auth.md |
| Test code generation from CLI |
test-generation.md |
| Tracing and debugging |
tracing-and-debugging.md |
| Screenshots, video, PDF |
screenshots-and-media.md |
| Device & environment emulation |
device-emulation.md |
| Complex multi-step workflows |
advanced-workflows.md |
Language Note
All guides include TypeScript and JavaScript examples. When the project uses .js files or has no tsconfig.json, examples are adapted to plain JavaScript.
1---2name: playwright-skill3description: Battle-tested Playwright patterns for E2E, API, component, visual, accessibility, and security testing. Covers locators, fixtures, POM, network mocking, auth flows, debugging, CI/CD (GitHub Actions, GitLab, CircleCI, Azure, Jenkins), framework recipes (React, Next.js, Vue, Angular), and migration guides from Cypress/Selenium. TypeScript and JavaScript.4---5
6# Playwright Skill
7
8> Opinionated, production-tested Playwright guidance — every pattern includes when (and when _not_) to use it.
9
10**50+ reference guides** covering the full Playwright surface: selectors, assertions, fixtures, page objects, network mocking, auth, visual regression, accessibility, API testing, CI/CD, debugging, and more — with TypeScript and JavaScript examples throughout.
11
12## Golden Rules
13
141. **`getByRole()` over CSS/XPath** — resilient to markup changes, mirrors how users see the page
152. **Never `page.waitForTimeout()`** — use `expect(locator).toBeVisible()` or `page.waitForURL()`
163. **Web-first assertions** — `expect(locator)` auto-retries; `expect(await locator.textContent())` does not
174. **Isolate every test** — no shared state, no execution-order dependencies
185. **`baseURL` in config** — zero hardcoded URLs in tests
196. **Retries: `2` in CI, `0` locally** — surface flakiness where it matters
207. **Traces: `'on-first-retry'`** — rich debugging artifacts without CI slowdown
218. **Fixtures over globals** — share state via `test.extend()`, not module-level variables
229. **One behavior per test** — multiple related `expect()` calls are fine
2310. **Mock external services only** — never mock your own app; mock third-party APIs, payment gateways, email
24
25## Guide Index
26
27### Writing Tests
28
29| What you're doing | Guide | Deep dive |
30| -------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------ |
31| Choosing selectors | [locators.md](core/locators.md) | [locator-strategy.md](core/locator-strategy.md) |
32| Assertions & waiting | [assertions-and-waiting.md](core/assertions-and-waiting.md) | |
33| Organizing test suites | [test-organization.md](core/test-organization.md) | [test-architecture.md](core/test-architecture.md) |
34| Playwright config | [configuration.md](core/configuration.md) | |
35| Page objects | [page-object-model.md](pom/page-object-model.md) | [pom-vs-fixtures-vs-helpers.md](pom/pom-vs-fixtures-vs-helpers.md) |
36| Fixtures & hooks | [fixtures-and-hooks.md](core/fixtures-and-hooks.md) | |
37| Test data | [test-data-management.md](core/test-data-management.md) | |
38| Auth & login | [authentication.md](core/authentication.md) | [auth-flows.md](core/auth-flows.md) |
39| API testing (REST/GraphQL) | [api-testing.md](core/api-testing.md) | |
40| Visual regression | [visual-regression.md](core/visual-regression.md) | |
41| Accessibility | [accessibility.md](core/accessibility.md) | |
42| Mobile & responsive | [mobile-and-responsive.md](core/mobile-and-responsive.md) | |
43| Component testing | [component-testing.md](core/component-testing.md) | |
44| Network mocking | [network-mocking.md](core/network-mocking.md) | [when-to-mock.md](core/when-to-mock.md) |
45| Forms & validation | [forms-and-validation.md](core/forms-and-validation.md) | |
46| File uploads/downloads | [file-operations.md](core/file-operations.md) | [file-upload-download.md](core/file-upload-download.md) |
47| Error & edge cases | [error-and-edge-cases.md](core/error-and-edge-cases.md) | |
48| CRUD flows | [crud-testing.md](core/crud-testing.md) | |
49| Drag and drop | [drag-and-drop.md](core/drag-and-drop.md) | |
50| Search & filter UI | [search-and-filter.md](core/search-and-filter.md) | |
51
52### Debugging & Fixing
53
54| Problem | Guide |
55| -------------------------- | --------------------------------------------- |
56| General debugging workflow | [debugging.md](core/debugging.md) |
57| Specific error message | [error-index.md](core/error-index.md) |
58| Flaky / intermittent tests | [flaky-tests.md](core/flaky-tests.md) |
59| Common beginner mistakes | [common-pitfalls.md](core/common-pitfalls.md) |
60
61### Framework Recipes
62
63| Framework | Guide |
64| ----------------------------------- | ----------------------------- |
65| Next.js (App Router + Pages Router) | [nextjs.md](core/nextjs.md) |
66| React (CRA, Vite) | [react.md](core/react.md) |
67| Vue 3 / Nuxt | [vue.md](core/vue.md) |
68| Angular | [angular.md](core/angular.md) |
69
70### Migration Guides
71
72| From | Guide |
73| -------------------- | ---------------------------------------------- |
74| Cypress | [from-cypress.md](migration/from-cypress.md) |
75| Selenium / WebDriver | [from-selenium.md](migration/from-selenium.md) |
76
77### Architecture Decisions
78
79| Question | Guide |
80| --------------------------- | ------------------------------------------------------------------ |
81| Which locator strategy? | [locator-strategy.md](core/locator-strategy.md) |
82| E2E vs component vs API? | [test-architecture.md](core/test-architecture.md) |
83| Mock vs real services? | [when-to-mock.md](core/when-to-mock.md) |
84| POM vs fixtures vs helpers? | [pom-vs-fixtures-vs-helpers.md](pom/pom-vs-fixtures-vs-helpers.md) |
85
86### CI/CD & Infrastructure
87
88| Topic | Guide |
89| --------------------------------- | --------------------------------------------------------------- |
90| GitHub Actions | [ci-github-actions.md](ci/ci-github-actions.md) |
91| GitLab CI | [ci-gitlab.md](ci/ci-gitlab.md) |
92| CircleCI / Azure DevOps / Jenkins | [ci-other.md](ci/ci-other.md) |
93| Parallel execution & sharding | [parallel-and-sharding.md](ci/parallel-and-sharding.md) |
94| Docker & containers | [docker-and-containers.md](ci/docker-and-containers.md) |
95| Reports & artifacts | [reporting-and-artifacts.md](ci/reporting-and-artifacts.md) |
96| Code coverage | [test-coverage.md](ci/test-coverage.md) |
97| Global setup/teardown | [global-setup-teardown.md](ci/global-setup-teardown.md) |
98| Multi-project config | [projects-and-dependencies.md](ci/projects-and-dependencies.md) |
99
100### Specialized Topics
101
102| Topic | Guide |
103| ------------------------------------------ | ----------------------------------------------------------------------- |
104| Multi-user & collaboration | [multi-user-and-collaboration.md](core/multi-user-and-collaboration.md) |
105| WebSockets & real-time | [websockets-and-realtime.md](core/websockets-and-realtime.md) |
106| Browser APIs (geo, clipboard, permissions) | [browser-apis.md](core/browser-apis.md) |
107| iframes & Shadow DOM | [iframes-and-shadow-dom.md](core/iframes-and-shadow-dom.md) |
108| Canvas & WebGL | [canvas-and-webgl.md](core/canvas-and-webgl.md) |
109| Service workers & PWA | [service-workers-and-pwa.md](core/service-workers-and-pwa.md) |
110| Electron apps | [electron-testing.md](core/electron-testing.md) |
111| Browser extensions | [browser-extensions.md](core/browser-extensions.md) |
112| Security testing | [security-testing.md](core/security-testing.md) |
113| Performance & benchmarks | [performance-testing.md](core/performance-testing.md) |
114| i18n & localization | [i18n-and-localization.md](core/i18n-and-localization.md) |
115| Multi-tab & popups | [multi-context-and-popups.md](core/multi-context-and-popups.md) |
116| Clock & time mocking | [clock-and-time-mocking.md](core/clock-and-time-mocking.md) |
117| Third-party integrations | [third-party-integrations.md](core/third-party-integrations.md) |
118
119### CLI Browser Automation
120
121| What you're doing | Guide |
122| ------------------------------------------- | ------------------------------------------------------------------- |
123| CLI browser interaction | [playwright-cli/SKILL.md](playwright-cli/SKILL.md) |
124| Core commands (open, click, fill, navigate) | [core-commands.md](playwright-cli/core-commands.md) |
125| Network mocking & interception | [request-mocking.md](playwright-cli/request-mocking.md) |
126| Running custom Playwright code | [running-custom-code.md](playwright-cli/running-custom-code.md) |
127| Multi-session browser management | [session-management.md](playwright-cli/session-management.md) |
128| Cookies, localStorage, auth state | [storage-and-auth.md](playwright-cli/storage-and-auth.md) |
129| Test code generation from CLI | [test-generation.md](playwright-cli/test-generation.md) |
130| Tracing and debugging | [tracing-and-debugging.md](playwright-cli/tracing-and-debugging.md) |
131| Screenshots, video, PDF | [screenshots-and-media.md](playwright-cli/screenshots-and-media.md) |
132| Device & environment emulation | [device-emulation.md](playwright-cli/device-emulation.md) |
133| Complex multi-step workflows | [advanced-workflows.md](playwright-cli/advanced-workflows.md) |
134
135## Language Note
136
137All guides include TypeScript and JavaScript examples. When the project uses `.js` files or has no `tsconfig.json`, examples are adapted to plain JavaScript.
majiayu000