e2e-testing-patterns

Skill Directory

Resolve SKILL_DIR to the absolute directory containing this SKILL.md, as shown by the current host, before using any bundled path below. Before a shell command uses $SKILL_DIR, assign it in that command or replace it with the resolved path. It is not a host-exported environment variable.

E2E Testing Patterns

Playwright end-to-end testing patterns. For shared test quality principles (philosophy, smells, mocking decisions), see testing-patterns.

Reference Routing

| Need | Reference File | Sections to Read | |------|---------------|-----------------| | Playwright + E2E patterns | $SKILL_DIR/../testing-patterns/references/playwright-patterns.md | Full file (~461L, manageable) | | Behavior vs implementation | $SKILL_DIR/../testing-patterns/references/test-philosophy.md | ## The Fundamental Shift + ## Four Core Principles | | Flaky/brittle tests | $SKILL_DIR/../testing-patterns/references/test-smells.md | ## The Six Major Test Smells (relevant subsection) | | Mock usage decisions | $SKILL_DIR/../testing-patterns/references/mocking-strategies.md | ## The Mocking Decision Framework | | Test layer strategy | $SKILL_DIR/../testing-patterns/references/test-layers.md | ## The Three Layers + ## Choosing the Right Layer |

How to read sections: Grep for heading to find line number, Read with offset+limit.

Locator Priority (Best to Worst)

1. page.getByRole('button', { name: 'Submit' }) — accessible, resilient
2. page.getByLabel('Email') — form elements
3. page.getByText('Welcome') — visible content
4. page.getByTestId('checkout-form') — explicit test hooks
5. page.locator('.class') / #id — last resort, fragile

E2E Quick Reference

| Use | Instead Of | Why | |-----|-----------|-----| | await expect(locator).toBeVisible() | page.waitForTimeout(2000) | Auto-waits, deterministic | | page.getByRole() | page.locator('.btn') | Resilient to CSS changes | | Page Object Model | Inline selectors | Reusable, single source of truth | | page.route() for external APIs | Real HTTP calls | Fast, deterministic, no rate limits | | Config-based URLs | http://localhost:8080 | Works across environments | | toHaveScreenshot({ maxDiffPixelRatio: 0.01 }) | toMatchSnapshot() | Tolerates rendering differences | | test.describe() grouping | Flat test structure | Logical organization | | await before all assertions | Missing await | Playwright assertions are async |

E2E Red Flags

| Pattern | Why Harmful | Fix | |---------|------------|-----| | CSS selectors as primary locators | Break on styling changes | Use role/label/text locators | | page.waitForTimeout() | Arbitrary delay, flaky | Use expect(locator).toBeVisible() | | Missing test isolation | Tests depend on prior state | beforeEach setup, clean state | | Hardcoded URLs | Breaks across environments | Use config/env variables | | No Page Object Model | Duplicated selectors | Extract to page object classes | | Screenshot without tolerance | Pixel-perfect failures | Set maxDiffPixelRatio | | Missing await before assertions | Silent assertion skip | Always await Playwright expects | | page.evaluate() for assertions | Bypasses auto-waiting | Use Playwright locator assertions | | No network interception | Flaky external calls | page.route() for third-party APIs |

Page Object Model Pattern

• One class per page/component with locators as properties
• Methods return this or the next page object for chaining
• Locators defined once, referenced by all tests
• Actions (click, fill) encapsulated in methods
• Assertions stay in test files, not page objects