playwright-architect
Architect-level Playwright guidance — what belongs in E2E versus unit/component tests, fixture and page-object boundaries, deterministic waits and network control, auth and seeded state, CI parallelism and flake policy. Use when designing or repairing a browser test suite.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- playwright-architect
- license
- MIT
- metadata
- { "crusor-path": "website-architect/frontend-development-architect/playwright-architect", "crusor-domain": "website-architect", "crusor-origin": "original", "crusor-sources": "playwright.dev/docs/best-practices; playwright.dev/docs/test-fixtures", "crusor-triggers": "playwright, e2e test, end-to-end, browser test, flaky test, e2e suite, browser automation, trace viewer", "crusor-verified-on": "2026-10-30" }
- description
- Architect-level Playwright guidance — what belongs in E2E versus unit/component tests, fixture and page-object boundaries, deterministic waits and network control, auth and seeded state, CI parallelism and flake policy. Use when designing or repairing a browser test suite.
- compatibility
- Playwright 1.40+; any frontend stack
03 SKILL.md 正文
Playwright Architect
E2E is the most expensive layer per assertion. Architecture is the discipline of spending it only on journeys that must not break — and making those deterministic.
When to use
- Designing the browser-test layer for a web app.
- A suite is slow, flaky, or failing without a product bug.
- Deciding where a test belongs: unit, component, or E2E.
When NOT to use
- Testing pure functions or component rendering (unit/component layer).
- Load testing and visual-regression-at-scale (different tools and budgets).
Decision 1 — The test pyramid, stated plainly
| Layer | Owns | Budget |
|---|---|---|
| unit | rules, formatting, reducers | thousands, ms |
| component | one component's states | hundreds, ms |
| E2E | critical journeys (login, checkout, publish) | tens, minutes |
| visual | layout regressions on key pages | few, stable pages |
- If a bug can be caught at a lower layer, it does not get an E2E test.
- Every E2E test names the business journey it protects.
Decision 2 — Fixtures and page objects
- One fixture per actor (anonymous user, signed-in user, admin), each producing an authenticated context — auth setup runs once, reused via storage state.
- Page objects hold locators and user-level actions, never assertions about business rules (those live in the test).
- Locators: role + accessible name (
getByRole), then test ids. Never CSS chains into component internals. - Data setup through API/seed, not by clicking through the UI.
Decision 3 — Determinism
- No
waitForTimeout. Wait on state:expect(locator).toBeVisible(), URL, or a network response. - Control the network: mock third parties, stub failures and slow responses to test the sad path deliberately.
- Freeze time and randomise seeds where output depends on them.
- Each test creates its own data and cleans up; no ordering dependencies.
Decision 4 — CI reality
- Shards in parallel; retries limited (1) and reported, never used to hide flake.
- Trace + video on first retry; artefacts uploaded.
- Quarantine policy: a test failing intermittently twice is fixed or deleted
within a sprint — a permanent
@flakytag is a broken gate. - Runs on every PR for the smoke subset; full suite on main/nightly.
Failure modes at scale
- A 40-minute suite nobody runs locally.
- Sleeps everywhere → 5% flake rate → team ignores red.
- Page objects with 300 methods, mirroring the DOM.
- Tests that depend on shared seed data and pass only in order.
- E2E used to verify styling that a screenshot test covers in 200 ms.
Verification receipts
- Flake audit: pass rate over the last 50 runs per test; zero unexplained.
- Suite duration and shard balance recorded.
- Trace artefacts present on retry.
- Every critical journey covered exactly once (no duplicates).
waitForTimeoutcount in the suite: zero.
04 同仓库更多 Skills
interaction-patterns-architect
Architect-level interaction design in code — choosing established patterns over invented ones, feedback and latency behaviour, destructive-action safeguards, navigation and overlay conventions, and the state model behind every interactive surface. Use when a screen has to behave, not just look.
design-system-ops-architect
Architect-level operation of a design system in code — token pipelines and versioning, component API and variant policy, the catalogue as the contract, adoption metrics, and the governance that stops a system from forking into three. Use when a component library must survive several teams.
design-handoff-architect
Architect-level design handoff — what must be specified before implementation starts, tokens over raw values, responsive and content-limit contracts, state matrices, and the review loop that catches drift between design and code. Use when a design is about to become code.
content-microcopy-architect
Architect-level UI content — where strings live, voice and terminology consistency, error and empty-state copy as part of the interface, translation-ready authoring, and the content model a product needs before it multiplies screens. Use when the words in the interface matter as much as the pixels.
ui-ux-implementation-architect
Architect-level direction for turning a design into working UI — the handoff contract, component ownership versus screen-level layout, interaction and state conventions, design QA gates, and the review habits that keep an implementation faithful without frozen pixels. Use before any specific UI implementation skill.
test-strategy-architect
Architect-level test strategy — allocating assertions across unit, integration, contract and end-to-end layers, designing for testability through dependency boundaries, fixture and data strategy, and the flake and coverage policies that keep a suite trustworthy. Use when defining how a codebase is tested.