playwright-best-practices_skill

Overview

This skill delivers concise, actionable Playwright best practices for writing reliable, maintainable end-to-end tests. It focuses on stable selectors, robust wait strategies, accessibility checks, responsive testing, and techniques to prevent flaky tests.

How this skill works

The guidance inspects common anti-patterns in test code and recommends concrete replacements: semantic locators (getByRole/getByTestId/getByLabel), explicit assertions and auto-waiting instead of fixed delays, and viewport-driven responsive checks. It also prescribes isolation, cleanup, and accessibility assertions to make tests deterministic and trustworthy.

When to use it

• When writing new Playwright E2E tests for web UI flows
• When refactoring flaky or brittle tests that fail intermittently
• When adding accessibility or keyboard navigation coverage
• When adding mobile/tablet/desktop viewports to test suites
• When implementing CI test pipelines to reduce false negatives

Best practices

• Prefer semantic locators: page.getByRole, getByLabel, getByTestId over CSS class or DOM-tree selectors
• Never use page.waitForTimeout; rely on auto-waiting and explicit assertions like waitForURL, waitForSelector, expect(...).toBeHidden()
• Add accessibility checks and keyboard navigation tests to catch semantic regressions early
• Keep tests independent: reset state and clean up data after each test using fixtures
• Run tests across multiple viewports and avoid hardcoded test data or randomness
• Use response-based waits (waitForResponse) for API-driven UI changes and retries for transient flakes

Example use cases

• Replace brittle CSS-based clicks with page.getByRole('button', { name: 'Submit' }).click()
• Fix a flaky login test by waiting for the network response and asserting redirect URL instead of using sleep
• Add an accessibility assertion and a keyboard tab sequence to ensure form fields are reachable
• Create a mobile test block that sets viewport to a phone size and verifies the hamburger menu appears
• Refactor a test suite to use fixtures that reset the database and remove inter-test dependencies