playwright-best-practices

Guides writing, debugging, and maintaining Playwright tests across E2E, API, and component scenarios.

Updated Jan 31, 2023
One-click install
npx skills add https://github.com/Briian3306/Transporte --skill playwright-best-practices-briian3306
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: playwright-best-practices
Source: https://github.com/Briian3306/Transporte/tree/main/ibarra-app/.agents/skills/playwright-best-practices
Command: npx skills add https://github.com/Briian3306/Transporte --skill playwright-best-practices-briian3306

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Writing and maintaining Playwright test suites involves many decisions—locator strategies, waiting patterns, mocking, CI configuration, and framework-specific quirks—and getting them wrong leads to flaky, slow, or brittle tests. This Skill provides structured, activity-based guidance so you apply proven patterns instead of reinventing them. ## Core Features & Use Cases - Activity-Based Reference Routing: A decision tree and lookup tables map your current task (writing E2E tests, fixing flaky tests, configuring CI/CD, mocking APIs) to the exact reference file you need. - Comprehensive Coverage: References span core patterns (locators, assertions, fixtures, Page Object Model), testing patterns (API, visual, accessibility, security), browser APIs (WebSockets, geolocation, service workers), frameworks (React, Angular, Vue, Next.js), and infrastructure (GitHub Actions, Docker, sharding, reporting). - Use Case: You are debugging a test that fails only in parallel CI runs. The decision tree routes you to flaky-tests.md and performance.md, where you find guidance on test isolation, worker-scoped fixtures, and race condition diagnosis. ## Quick Start Ask the agent to help you write or fix a Playwright test, describing your scenario such as mocking an API response or fixing a flaky login test.

Frequently Asked Questions about playwright-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix flaky Playwright tests?▼

Replace explicit waits like waitForTimeout with auto-retrying web-first assertions such as expect(locator).toBeVisible(). Ensure test isolation with fixtures, avoid shared mutable state between tests, and use trace viewer to diagnose race conditions in parallel runs.

How do I mock API responses in Playwright tests?▼

Use page.route() to intercept network requests and fulfill them with custom JSON responses. For advanced scenarios like HAR recording, GraphQL mocking, or simulating network failures, the network interception references cover those patterns.

Should I use Page Object Model or fixtures in Playwright?▼

Both are valid; the skill includes a dedicated POM vs fixtures decision reference. Page Object Model encapsulates page interactions in classes, while fixtures handle setup and teardown—many suites combine both approaches.

Does Playwright support accessibility testing with axe-core?▼

Yes, integrate @axe-core/playwright by creating an AxeBuilder instance and calling analyze() on the page. You can scope analysis to specific elements, disable rules, filter by WCAG tags, and build a reusable a11y fixture for your suite.

How do I run only specific Playwright tests by tag?▼

Add tags like @smoke or @fast to test titles, then filter with npx playwright test --grep @smoke. This supports workflows like running fast tests on PRs and full suites nightly.

Why do my Playwright tests pass locally but fail in CI?▼

Common causes include missing environment variables, different base URLs, timing differences under CI parallelism, and unseeded databases. Use process.env for configuration, webServer in config to start services, and unique identifiers for test data.