playwright-test-patterns-guide

Idiomatic Playwright Test Patterns

A comprehensive guide for writing clean, maintainable, and production-ready Playwright E2E tests.

---

Table of Contents

1. Core Principles
2. Test File Structure
3. Assertion Patterns
4. Navigation and Waiting
5. Authentication Strategies
6. Test Organization
7. Page Object Models
8. Test Data Management
9. Error Handling
10. Common Patterns Library
11. Anti-Patterns to Avoid
12. Complete Examples

---

Core Principles

✅ Idiomatic Playwright Testing

1. Auto-waiting is your friend - Trust Playwright's built-in waiting
2. Explicit is better than implicit - Make intentions clear
3. Arrange-Act-Assert - Clear test structure
4. Independent tests - Each test can run alone
5. Descriptive names - Tests are documentation
6. Minimal setup - Only what's necessary
7. Stable selectors - Role-first, semantic locators

❌ Never Do These

• ❌ Manual waits (page.waitForTimeout(5000)) except for debugging
• ❌ Broad try/catch blocks that hide failures
• ❌ Tests that depend on other tests
• ❌ Hard-coded URLs and credentials in test files
• ❌ Generic test names like "test 1" or "works correctly"
• ❌ Unnecessary waitForSelector (built into locators)

---

Test File Structure

Basic Test File Template

import { test, expect } from '@playwright/test';

test.describe('Feature Name', () => {
  test.beforeEach(async ({ page }) => {
    // Setup before each test
    await page.goto('/starting-point');
  });

  test('should do specific thing', async ({ page }) => {
    // Arrange: Set up test data/state
    
    // Act: Perform user actions
    
    // Assert: Verify expected outcomes
  });

  test('should handle error case', async ({ page }) => {
    // Test error scenarios
  });
});