Web Test Automation

Web Test Automation

Best-practice guidance for building durable, low-flakiness automated tests for web applications. Playwright (TypeScript) is the default stack; Cypress and Selenium are covered for existing investments and migration.

This skill teaches an agent how to do web test automation well — it does not replace the official docs. When writing real test code, also consult the current Playwright / Cypress docs for exact API shapes, since these tools move fast.

When to Load Reference Files

Load only the reference files relevant to the current task:

Core Principles (the substance)

These are the highest-value rules. Encode them into every suite you design.

1. Locators: user-facing first

• Prefer role/label/text locators (getByRole, getByLabel, getByText); fall back to test IDs (getByTestId → data-testid / data-cy).
• Avoid CSS/XPath tied to DOM structure or styling — they break on every refactor.
• Centralize selectors in one place (a page object) so a UI change is a one-line fix.

2. Waiting & flakiness (the #1 source of pain)

• Use web-first, auto-retrying assertions: await expect(locator).toBeVisible() — never expect(await locator.isVisible()).toBe(true).
• Never use fixed sleeps (page.waitForTimeout, cy.wait(<number>)). Wait on conditions, events, or network responses instead.
• Lint for missing awaits (@typescript-eslint/no-floating-promises) and run tsc --noEmit in CI.
• Diagnose flakiness with the trace viewer; harden critical tests with --repeat-each=N.

3. Test isolation & data

• Every test runs independently with its own state. Verify by running a test alone.
• Set up / reset state in beforeEach, not after* (cleanup may not run on failure).
• Control state programmatically — seed via API or DB, not UI clicks.
• Log in once via API / storageState (Playwright setup project; Cypress cy.session()) and reuse the signed-in state.

4. Scope discipline

• Only test what you control. Mock third-party/external services via network interception (page.route, cy.intercept). Don't hit real external servers.

5. Architecture

• Page Object Model centralizes selectors + exposes domain-level methods.
• In Playwright, prefer fixtures for setup/teardown and POM for UI abstraction — know when to use which.
• Keep the test body thin; push reuse into fixtures/factories.

6. Cross-cutting test types inside web E2E

• API testing: validate endpoints and use the API to set up preconditions / assert postconditions.
• Accessibility: integrate @axe-core/playwright; scope scans; gate on WCAG tags.
• Visual regression: toHaveScreenshot with platform-suffixed baselines; mask dynamic content; tune maxDiffPixels; generate baselines in a consistent (ideally Dockerized) env.

7. CI integration

• Run on every PR/commit; use Linux runners; install only needed browsers (--with-deps).
• Shard across machines for speed; use trace-on-first-retry (not always-on); publish the HTML report + trace artifacts.

Tool Selection Quick Reference

See references/tool-selection.md for the full decision tree.

Configuration

• Default project layout: tests/ for specs, tests/pages/ for page objects, tests/fixtures/ for fixtures, playwright.config.ts at root.
• Recommended Playwright config: trace: 'on-first-retry', retries: process.env.CI ? 2 : 0, fullyParallel: true, projects per browser, a setup project for auth.
• Install: npm init playwright@latest (adds config, GitHub Actions workflow, example tests).
• Lint gate: enable @typescript-eslint/no-floating-promises; run tsc --noEmit in CI to catch missing awaits.

Language / Framework Selection

• Default: Playwright + TypeScript.
• Override only when the user explicitly asks for Cypress, Selenium, or another language binding, or when an existing suite dictates it. Surface the tradeoff in the decision file before overriding.

Resources

• Playwright Best Practices — https://playwright.dev/docs/best-practices
• Playwright Page Object Model — https://playwright.dev/docs/pom
• Playwright Accessibility Testing — https://playwright.dev/docs/accessibility-testing
• Playwright Visual Comparisons — https://playwright.dev/docs/test-snapshots
• Playwright API Testing — https://playwright.dev/docs/api-testing
• Cypress Best Practices — https://docs.cypress.io/app/core-concepts/best-practices

Attribution: principles distilled from the official Playwright and Cypress best-practice docs, and informed by the MIT-licensed community skills currents-dev/playwright-best-practices-skill and testdino-hq/playwright-skill.