End-to-End Testing with Playwright

Playwright provides reliable end-to-end testing. Here's how to write effective E2E tests.

Setup and Configuration#

// playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ['html'],
    ['junit', { outputFile: 'results.xml' }],
  ],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    {
      name: 'chromium',
      use: { ...devices['Desktop Chrome'] },
    },
    {
      name: 'firefox',
      use: { ...devices['Desktop Firefox'] },
    },
    {
      name: 'webkit',
      use: { ...devices['Desktop Safari'] },
    },
    {
      name: 'Mobile Chrome',
      use: { ...devices['Pixel 5'] },
    },
    {
      name: 'Mobile Safari',
      use: { ...devices['iPhone 12'] },
    },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

Basic Tests#

// tests/e2e/home.spec.ts
import { test, expect } from '@playwright/test';

test.describe('Home Page', () => {
  test('has correct title', async ({ page }) => {
    await page.goto('/');
    await expect(page).toHaveTitle(/My App/);
  });

  test('navigation works', async ({ page }) => {
    await page.goto('/');

    await page.click('text=About');
    await expect(page).toHaveURL('/about');

    await page.click('text=Contact');
    await expect(page).toHaveURL('/contact');
  });

  test('search functionality', async ({ page }) => {
    await page.goto('/');

    await page.fill('[placeholder="Search..."]', 'test query');
    await page.press('[placeholder="Search..."]', 'Enter');

    await expect(page).toHaveURL('/search?q=test+query');
    await expect(page.locator('.search-results')).toBeVisible();
  });
});

Page Object Model#

// tests/e2e/pages/LoginPage.ts
import { Page, Locator, expect } from '@playwright/test';

export class LoginPage {
  readonly page: Page;
  readonly emailInput: Locator;
  readonly passwordInput: Locator;
  readonly submitButton: Locator;
  readonly errorMessage: Locator;

  constructor(page: Page) {
    this.page = page;
    this.emailInput = page.getByLabel('Email');
    this.passwordInput = page.getByLabel('Password');
    this.submitButton = page.getByRole('button', { name: 'Sign in' });
    this.errorMessage = page.getByRole('alert');
  }

  async goto() {
    await this.page.goto('/login');
  }

  async login(email: string, password: string) {
    await this.emailInput.fill(email);
    await this.passwordInput.fill(password);
    await this.submitButton.click();
  }

  async expectError(message: string) {
    await expect(this.errorMessage).toContainText(message);
  }

  async expectLoggedIn() {
    await expect(this.page).toHaveURL('/dashboard');
  }
}

// tests/e2e/pages/DashboardPage.ts
export class DashboardPage {
  readonly page: Page;
  readonly userMenu: Locator;
  readonly logoutButton: Locator;

  constructor(page: Page) {
    this.page = page;
    this.userMenu = page.getByTestId('user-menu');
    this.logoutButton = page.getByRole('button', { name: 'Logout' });
  }

  async logout() {
    await this.userMenu.click();
    await this.logoutButton.click();
  }
}

// Usage in tests
import { test } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';
import { DashboardPage } from './pages/DashboardPage';

test.describe('Authentication', () => {
  test('successful login', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login('user@example.com', 'password123');
    await loginPage.expectLoggedIn();
  });

  test('failed login shows error', async ({ page }) => {
    const loginPage = new LoginPage(page);
    await loginPage.goto();
    await loginPage.login('user@example.com', 'wrongpassword');
    await loginPage.expectError('Invalid credentials');
  });
});

Fixtures and Setup#

// tests/e2e/fixtures.ts
import { test as base, expect } from '@playwright/test';
import { LoginPage } from './pages/LoginPage';
import { DashboardPage } from './pages/DashboardPage';

// Custom fixtures
type MyFixtures = {
  loginPage: LoginPage;
  dashboardPage: DashboardPage;
  authenticatedPage: Page;
};

export const test = base.extend<MyFixtures>({
  loginPage: async ({ page }, use) => {
    const loginPage = new LoginPage(page);
    await use(loginPage);
  },

  dashboardPage: async ({ page }, use) => {
    const dashboardPage = new DashboardPage(page);
    await use(dashboardPage);
  },

  authenticatedPage: async ({ page }, use) => {
    // Login before test
    await page.goto('/login');
    await page.fill('[name="email"]', 'test@example.com');
    await page.fill('[name="password"]', 'password');
    await page.click('button[type="submit"]');
    await page.waitForURL('/dashboard');

    await use(page);

    // Cleanup after test
    await page.goto('/logout');
  },
});

export { expect };

// Usage
import { test, expect } from './fixtures';

test('authenticated user can view dashboard', async ({ authenticatedPage }) => {
  await expect(authenticatedPage.locator('h1')).toContainText('Dashboard');
});

API Mocking#

// Mock API responses
test('displays products from API', async ({ page }) => {
  // Mock API before navigation
  await page.route('/api/products', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify([
        { id: 1, name: 'Product 1', price: 100 },
        { id: 2, name: 'Product 2', price: 200 },
      ]),
    });
  });

  await page.goto('/products');

  await expect(page.locator('.product-card')).toHaveCount(2);
  await expect(page.locator('text=Product 1')).toBeVisible();
});

// Mock API error
test('handles API error', async ({ page }) => {
  await page.route('/api/products', async (route) => {
    await route.fulfill({
      status: 500,
      body: JSON.stringify({ error: 'Server error' }),
    });
  });

  await page.goto('/products');

  await expect(page.locator('.error-message')).toContainText('Failed to load');
});

// Intercept and modify requests
test('modifies request headers', async ({ page }) => {
  await page.route('/api/**', async (route) => {
    await route.continue({
      headers: {
        ...route.request().headers(),
        'X-Test-Header': 'test-value',
      },
    });
  });

  await page.goto('/dashboard');
});

Visual Testing#

// Screenshot comparison
test('homepage looks correct', async ({ page }) => {
  await page.goto('/');

  // Full page screenshot
  await expect(page).toHaveScreenshot('homepage.png', {
    fullPage: true,
  });
});

// Element screenshot
test('header looks correct', async ({ page }) => {
  await page.goto('/');

  const header = page.locator('header');
  await expect(header).toHaveScreenshot('header.png');
});

// With threshold
test('chart renders correctly', async ({ page }) => {
  await page.goto('/dashboard');

  await expect(page.locator('.chart')).toHaveScreenshot('chart.png', {
    maxDiffPixels: 100,
    threshold: 0.2,
  });
});

// Mask dynamic content
test('page with dynamic content', async ({ page }) => {
  await page.goto('/profile');

  await expect(page).toHaveScreenshot('profile.png', {
    mask: [
      page.locator('.timestamp'),
      page.locator('.avatar'),
    ],
  });
});

Accessibility Testing#

import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';

test.describe('Accessibility', () => {
  test('home page passes accessibility checks', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page }).analyze();

    expect(results.violations).toEqual([]);
  });

  test('login form is accessible', async ({ page }) => {
    await page.goto('/login');

    const results = await new AxeBuilder({ page })
      .include('form')
      .withTags(['wcag2a', 'wcag2aa'])
      .analyze();

    expect(results.violations).toEqual([]);
  });

  // Check specific rules
  test('images have alt text', async ({ page }) => {
    await page.goto('/');

    const results = await new AxeBuilder({ page })
      .withRules(['image-alt'])
      .analyze();

    expect(results.violations).toEqual([]);
  });
});

CI Integration#

# .github/workflows/e2e.yml
name: E2E Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps

      - name: Run E2E tests
        run: npx playwright test

      - name: Upload report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: playwright-report
          path: playwright-report/
          retention-days: 30

Best Practices#

Selectors:
✓ Prefer user-visible locators
✓ Use getByRole, getByLabel, getByText
✓ Add data-testid for complex cases
✓ Avoid CSS selectors

Tests:
✓ Keep tests independent
✓ Use page objects for reusability
✓ Mock external dependencies
✓ Test critical user journeys

Performance:
✓ Run tests in parallel
✓ Use test.describe.parallel
✓ Share authentication state
✓ Minimize browser contexts

Playwright provides reliable E2E testing with excellent developer experience. Use page objects for maintainability, fixtures for setup/teardown, and API mocking for isolation. Integrate visual and accessibility testing for comprehensive coverage, and run tests in CI for confidence in deployments.