E2E Testing With Playwright: A Comprehensive Guide

by Alex Johnson 51 views

End-to-end (E2E) testing is crucial for ensuring the reliability and functionality of web applications. This guide provides a comprehensive overview of how to implement E2E tests using Playwright, covering setup, configuration, test scenarios, and continuous integration. Let's dive into how you can ensure your application performs flawlessly from the user's perspective.

What are End-to-End (E2E) Tests?

End-to-end (E2E) tests validate the entire application flow from start to finish, mimicking real user scenarios. Unlike unit tests that focus on individual components, E2E tests verify the interaction between different parts of the system, including the frontend, backend, and database. This ensures that all components work together seamlessly, providing a cohesive user experience.

Why are E2E Tests Important?

  • Comprehensive Validation: E2E tests cover the entire application flow, ensuring all components work together correctly.
  • Real User Scenarios: They mimic user interactions, providing confidence in the application's usability.
  • Early Bug Detection: E2E tests can catch issues that unit and integration tests might miss, such as problems with data flow or UI interactions.
  • Regression Prevention: They help prevent regressions by ensuring that new changes do not break existing functionality.
  • Improved User Experience: By validating critical user flows, E2E tests ensure a smooth and reliable user experience.

Playwright: A Powerful E2E Testing Framework

Playwright is a modern, open-source testing framework developed by Microsoft. It supports multiple browsers (Chromium, Firefox, and WebKit) and provides a rich set of features for automating browser interactions. Playwright's robust API and excellent performance make it an ideal choice for E2E testing.

Key Features of Playwright:

  • Cross-Browser Support: Playwright supports Chromium, Firefox, and WebKit, ensuring your tests cover a wide range of browsers.
  • Auto-Waiting: Playwright automatically waits for elements to be actionable before performing actions, reducing the need for manual waits.
  • Reliable Selectors: Playwright's selectors are designed to be resilient to changes in the DOM, minimizing flaky tests.
  • Test Isolation: Each test runs in its own context, ensuring tests do not interfere with each other.
  • Debugging Tools: Playwright provides excellent debugging tools, including a trace viewer and interactive debugger.

Setting Up Playwright for E2E Testing

To get started with Playwright, you'll need to install it and configure your project. Here’s a step-by-step guide to setting up Playwright for E2E testing:

1. Installing Playwright

First, install Playwright as a development dependency in your project using your preferred package manager. If you are using pnpm, run the following command:

pnpm add -D @playwright/test

This command adds Playwright to your project’s devDependencies.

2. Installing Browser Binaries

Next, run the Playwright installation command to download the browser binaries:

pnpm exec playwright install

This command downloads the necessary browser binaries (Chromium, Firefox, and WebKit) that Playwright will use for testing.

3. Creating playwright.config.ts

Create a playwright.config.ts file in your project root to configure Playwright. This file specifies the test directory, parallelization settings, reporters, and other options.

Here’s an example playwright.config.ts file:

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

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: 'html',
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
  webServer: {
    command: 'pnpm dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

Explanation of Configuration Options:

  • testDir: Specifies the directory where your test files are located.
  • fullyParallel: Enables running tests in parallel.
  • forbidOnly: Prevents committing tests that are focused (using .only).
  • retries: Sets the number of retries for failed tests.
  • workers: Specifies the number of worker processes to use for running tests in parallel.
  • reporter: Configures the test reporter (e.g., html for an HTML report).
  • use: Defines options for test execution, such as the base URL and trace settings.
  • projects: Configures different browser projects (e.g., Chromium, Firefox, WebKit).
  • webServer: Defines how to start your application’s development server.

4. Creating the e2e/ Directory Structure

Organize your test files by creating an e2e/ directory in your project root. Within this directory, you can create subdirectories and test files for different parts of your application.

Here’s an example directory structure:

e2e/
├── health.spec.ts      # API health check
├── chat.spec.ts        # Chat send/receive
├── memory.spec.ts      # Memory CRUD + inline edit
├── workspace.spec.ts   # Workspace CRUD + proposals
├── settings.spec.ts    # Settings page
└── fixtures/
    └── test-utils.ts   # Shared helpers

5. Adding the test:e2e Script to package.json

Add a test:e2e script to your package.json file to easily run your E2E tests:

"scripts": {
  "test:e2e": "playwright test"
}

Now you can run your tests using the command:

pnpm run test:e2e

6. Creating Shared Helpers

For reusable test logic, create a fixtures/ directory within e2e/ and add a test-utils.ts file. This file can contain helper functions and custom test fixtures.

Example e2e/fixtures/test-utils.ts:

// e2e/fixtures/test-utils.ts
import { test as base } from '@playwright/test';

export const test = base.extend({
  // Add custom fixtures here
});

Writing E2E Tests with Playwright

Now that you have set up Playwright, you can start writing E2E tests. Let’s look at some critical test scenarios and how to implement them.

Critical Test Scenarios

1. API Health Check (health.spec.ts)

Verify that your API is healthy by checking the /api/health endpoint.

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

test('GET /api/health returns 200', async ({ request }) => {
  const response = await request.get('/api/health');
  expect(response.status()).toBe(200);
});

test('Response has status: \