playwright-core

Playwright Core: Test Architecture and Quality Gates

Overview

Writing end-to-end tests is easy. Writing end-to-end tests that survive UI refactors and network latency without flaking requires discipline.

Use this skill when you are authoring, reviewing, or refactoring Playwright tests that should behave like a real user journey. It pairs well with playwright-auth-state for logged-in flows, playwright-network-mocking for external API control, and playwright-debugging when a test is already failing.

The approval standard: A test is only valid if it tests the application exactly how a human user interacts with it. We do not test implementation details, we do not rely on fixed sleep timers, and we do not share state between tests. If a test fails, it should indicate a true user-facing bug, not a brittle CSS selector or a race condition.

When to Use

• Before writing new Playwright E2E tests or component tests.
• When reviewing a PR that adds or modifies test coverage.
• When fixing a "flaky" test that passes locally but fails in CI.
• When refactoring existing Page Object Models (POMs) or test fixtures.

When Not to Use

• When you need authenticated state reuse; use playwright-auth-state instead.
• When you need request interception; use playwright-network-mocking instead.
• When you are diagnosing a specific failure or flake; use playwright-debugging instead.
• When you need CI configuration, fixture scaffolding, or a broader test framework recipe.

The Five-Axis Test Review

Every Playwright test must be evaluated across these five dimensions before execution:

1. Resiliency (Locator Strategy)

Does the test target user intent, or is it coupled to implementation?

• Are we using getByRole as the absolute first choice?
• Are we avoiding CSS classes, XPaths, and DOM hierarchy dependencies?
• If the developer changes a <div> to a <span>, or swaps a CSS framework (e.g., Bootstrap to Tailwind), will the test survive?

2. Determinism (Web-First Assertions)