playwright-best-practices

This skill provides a standardized framework for developing and maintaining Playwright end-to-end tests within CLI-based agent environments like Claude Code. It is designed for software engineers and QA automation specialists who need to write robust, maintainable, and context-aware test suites. The skill emphasizes user-centric testing patterns that ensure tests remain resilient to structural UI changes, helping to minimize brittle test code.

• Prioritizes resilient locator strategies, emphasizing user-facing attributes such as getByRole, getByLabel, and getByTestId over fragile CSS selectors or XPath expressions.

• Enforces web-first assertion patterns using await expect(locator), ensuring automatic waiting and retrying behavior which is critical for dynamic web applications.

• Promotes architectural best practices including test isolation, authentication state reuse via storageState, and the use of fixtures for setup and teardown tasks instead of manual beforeEach hooks.

• Integrates CLI-specific optimization rules, such as forcing minimal reporters like line or dot to prevent console output from flooding the LLM context window during test execution.

• Facilitates clean test data management by encouraging per-test data creation and robust network mocking strategies to ensure test determinism.

• Always prefer semantic locators like roles, labels, and placeholders to align test intent with accessibility standards.

• Avoid hardcoded waits like page.waitForTimeout in favor of auto-waiting locators and web-first assertions.

• Configure playwright.config.ts to automatically detect CI or CLAUDE environment variables to switch to minimal reporting modes.

• Organize code using the Page Object Model (POM) pattern to keep locator logic separate from test scenarios, facilitating easier updates when the UI changes.

• Ensure tests are truly isolated by avoiding shared state and implementing proper teardown procedures to leave the test environment in a clean state.