/rules - Playwright Best Practices Guide

Comprehensive rules and best practices for writing reliable, maintainable Playwright tests. 31 documented rules across 8 categories.

When to Use

• Writing new Playwright test files
• Reviewing test code for anti-patterns
• Debugging flaky tests
• Learning Playwright best practices
• Code review - referencing specific rule violations

Quick Reference

Critical Rules (ERROR Severity)

Rule	Category	Issue
wait-no-timeout	Waits	Never use waitForTimeout() - causes flaky tests
assert-web-first	Assertions	Use web-first assertions with auto-retry
test-isolation	Organization	Tests must be independent for parallel execution
parallel-worker-isolation	Parallel	Workers cannot share state
parallel-shared-state	Parallel	No shared mutable state between tests
selector-no-xpath	Locators	XPath is fragile and breaks easily
locator-first	Locators	Use .first() explicitly when multiple match
network-route-handlers	Network	Always resolve routes (continue/fulfill/abort)
debug-slow-mo	Debugging	Never leave slowMo in CI

Quick Patterns

Locators (Do → Don't)

// ✅ getByRole('button', { name: 'Submit' })  →  ❌ locator('.btn-submit')
// ✅ getByTestId('user-avatar')               →  ❌ locator('#avatar-12345')
// ✅ getByLabel('Email')                      →  ❌ locator('input[type="email"]')
// ✅ locator('.item').first()                 →  ❌ locator('.item') when multiple

Waits (Do → Don't)

// ✅ await expect(el).toBeVisible()           →  ❌ await page.waitForTimeout(1000)
// ✅ await page.waitForURL('/dashboard')      →  ❌ await page.waitForLoadState('networkidle')
// ✅ await response.finished()                →  ❌ await page.waitForTimeout(500)

Assertions (Do → Don't)

// ✅ await expect(locator).toHaveText('Hi')   →  ❌ expect(await locator.textContent()).toBe('Hi')
// ✅ await expect(locator).toBeVisible()      →  ❌ expect(await locator.isVisible()).toBe(true)
// ✅ await expect(page).toHaveURL('/home')    →  ❌ expect(page.url()).toBe('/home')

Rule Categories

Read the full documentation at ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/:

1. Locators (6 rules)

Finding elements reliably and maintainably.

# Read all locator rules
cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/locator-*.md
cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/selector-*.md

Rule	Description
locator-visibility	Verify element visibility before interactions
locator-first	Use .first() explicitly or refine locators
locator-chaining	Chain locators to narrow scope
selector-testid	Prefer getByTestId over CSS selectors
selector-no-xpath	Avoid fragile XPath expressions
selector-role-based	Prefer role-based locators (getByRole)

2. Waits & Timing (4 rules)

Handling asynchronous operations without flakiness.

cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/wait-*.md

Rule	Description
wait-no-timeout	CRITICAL - No hardcoded waitForTimeout
wait-for-state	Prefer waitFor over networkidle
wait-auto-waiting	Leverage Playwright's auto-waiting
wait-explicit-conditions	Use explicit wait conditions

3. Assertions (4 rules)

Verifying outcomes with auto-retry.

cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/assert-*.md

Rule	Description
assert-web-first	CRITICAL - Use web-first assertions
assert-specific	Use specific assertion methods
assert-soft	Use soft assertions appropriately
assert-timeout	Configure assertion timeouts properly

4. Page Objects (4 rules)

Organizing locators and actions.

cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/page-object-*.md

Rule	Description
page-object-locators	Move inline locators to Page Objects
page-object-actions	Encapsulate actions in methods
page-object-composition	Compose Page Objects for complex pages
page-object-no-assertions	Keep assertions in tests, not POs

5. Test Organization (5 rules)

Structuring tests for maintainability and parallel execution.

cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/test-*.md

Rule	Description
test-isolation	CRITICAL - Tests must be independent
test-hooks	Use beforeEach/afterEach properly
test-fixtures	Leverage Playwright fixtures
test-describe-grouping	Group related tests with describe
test-naming	Use descriptive test names

6. Network (4 rules)

Mocking and intercepting network requests.

cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/network-*.md

Rule	Description
network-mock-api	Mock external API calls
network-route-handlers	CRITICAL - Always resolve routes
network-wait-response	Wait for specific responses
network-abort-unnecessary	Abort unnecessary requests

7. Debugging (4 rules)

Troubleshooting and diagnosing test failures.

cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/debug-*.md

Rule	Description
debug-trace-on-failure	Enable traces for failed tests
debug-screenshots	Capture screenshots strategically
debug-video-recording	Configure video recording
debug-slow-mo	CRITICAL - Never in CI

8. Parallelization (4 rules)

Running tests safely in parallel.

cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/parallel-*.md

Rule	Description
parallel-worker-isolation	CRITICAL - Ensure worker isolation
parallel-shared-state	CRITICAL - No shared mutable state
parallel-test-data	Use unique test data per worker
parallel-serial-when-needed	Mark serial tests explicitly

Usage

Review Code Against Rules

When reviewing test code, read the relevant rule files:

// If you see this in a test:
await page.waitForTimeout(2000);

// Reference: wait-no-timeout.md (ERROR severity)
// This is the #1 cause of flaky tests!

Fix Violations

Each rule file includes:

• Summary - One-line description
• Rationale - Why the rule exists
• Best Practice - Correct code examples
• Anti-Pattern - What to avoid
• Auto-fix - How to transform bad code to good code

Code Review Comments

Reference rules in code reviews:

This violates `wait-no-timeout` (ERROR) - use explicit conditions instead:
- Before: `await page.waitForTimeout(2000)`
- After: `await expect(element).toBeVisible()`
See: docs/playwright-rules/rules/wait-no-timeout.md

Read Specific Rules

To read a specific rule:

# Read a specific rule
cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/wait-no-timeout.md

# Read all rules in a category
cat ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/assert-*.md

# Search for patterns
grep -r "auto-fix" ${CLAUDE_PLUGIN_ROOT}/docs/playwright-rules/rules/

Integration with Other Skills

• /test --explore - Apply rules when writing ad-hoc tests
• /test - Use patterns when creating production tests
• /test --ticket - Reference rules when generating from tickets

Severity Levels

• ERROR - Must fix; will cause flaky or broken tests
• WARNING - Should fix; may cause issues
• INFO - Recommended best practice

What This Skill Does

• Provides comprehensive Playwright best practices reference
• Documents patterns and anti-patterns with code examples
• Helps diagnose why tests are flaky
• Serves as a code review checklist

What This Skill Does NOT Do

• Auto-fix code (use /check --fix for auto-fixes)
• Run tests (use /test or /test --explore)
• Create Page Objects (use /test)