How do I set up Playwright for E2E testing?

Run 'npm init playwright@latest' to scaffold a project. Configure playwright.config.ts with a baseURL pointing to your app, enable the webServer option to auto-start your dev server, set fullyParallel to true, and define projects for Chromium, Firefox, and WebKit. Place E2E test files in a dedicated tests/e2e/ folder to separate them from unit or component tests.

Playwright End-to-End Testing: The Complete Guide (2026)

Q: What is end-to-end testing in Playwright?

End-to-end testing in Playwright means testing your entire application from the user's perspective — launching a real browser, navigating pages, filling forms, clicking buttons, and asserting that the whole workflow (login, search, checkout, etc.) works correctly. Playwright automates Chromium, Firefox, and WebKit so you can validate E2E flows across all major browsers with a single test suite.

Q: How do I handle authentication in Playwright E2E tests?

Use Playwright's storageState feature. Create a global setup file that logs in once via the UI or API, then saves the browser's cookies and localStorage to a JSON file (e.g., .auth/user.json). Reference that file in your test projects with 'storageState'. Every test starts already authenticated — no repeated login steps, dramatically faster execution.

Q: Can Playwright mock APIs during E2E tests?

Yes. Use page.route() to intercept any network request and return mock data. This is useful for testing edge cases (empty states, error responses, slow networks) without needing a real backend in that state. You can mock specific endpoints while letting others pass through to the real server, giving you fine-grained control over test scenarios.

Q: How do I run Playwright E2E tests in CI/CD?

Use GitHub Actions (or any CI) with the official Playwright Docker image or the setup-playwright action. Install browsers with 'npx playwright install --with-deps', run tests with 'npx playwright test', and upload the HTML report as an artifact. For large suites, use sharding (--shard=1/4) to split tests across parallel CI jobs for faster feedback.

Unit tests verify that individual functions work. Integration tests check that modules talk to each other. But only end-to-end tests answer the question that actually matters: can a real user complete their goal?

Playwright has become the default choice for E2E testing in 2026 — and for good reason. Its auto-waiting eliminates flaky selectors, browser context isolation makes parallel execution trivial, and native support for Chromium, Firefox, and WebKit means you cover every major browser without separate toolchains.

This guide covers everything: project setup, real-world test examples, authentication strategies, API mocking, visual regression, CI/CD configuration, and best practices. By the end, you'll have a complete Playwright E2E testing framework ready for production.

What Is End-to-End Testing?

End-to-end (E2E) testing validates complete user workflows from start to finish. Instead of testing a login function in isolation, an E2E test opens a real browser, navigates to the login page, types credentials, clicks the submit button, and verifies that the user lands on the dashboard with the correct data displayed.

The Testing Pyramid

The classic testing pyramid places tests in three layers:

Unit tests (base): Fast, cheap, isolated. Test individual functions and classes. Hundreds to thousands of them.
Integration tests (middle): Verify that modules, services, and APIs work together. Moderate speed and cost.
E2E tests (top): Simulate real user behavior in a real browser. Slowest, most expensive, but highest confidence. Keep these focused on critical user journeys.

E2E tests sit at the top because they're the most expensive to write and maintain — but they're also the only tests that catch cross-layer bugs. A checkout flow might pass every unit test and integration test individually, yet still fail because a frontend state change breaks the API call sequence. Only an E2E test catches that.

Rule of thumb: Write E2E tests for every critical revenue path — signup, login, checkout, payment, and core product workflows. If a flow breaking would wake someone up at 2 AM, it needs an E2E test.

Why Playwright for E2E Testing

Playwright isn't just another browser automation library. It was designed from the ground up for reliable end-to-end testing. Here's what sets it apart:

Auto-waiting. Every Playwright action automatically waits for the element to be visible, enabled, and stable before interacting with it. No more sleep(3000) or manual wait logic. This single feature eliminates the majority of flaky test failures.

Browser context isolation. Each test gets its own BrowserContext — a fresh, isolated session with its own cookies, localStorage, and cache. Tests can run in parallel without interfering with each other, even on the same browser instance.

Parallel execution out of the box. Playwright Test runs tests in parallel by default using worker processes. Combined with context isolation, you can run hundreds of E2E tests in minutes instead of hours.

Cross-browser coverage. One test suite runs on Chromium (Chrome/Edge), Firefox, and WebKit (Safari). No separate drivers, no configuration headaches. Define your browser matrix in the config file and every test runs everywhere.

Built-in tooling. Trace Viewer for debugging failed tests, codegen for recording interactions, HTML reporter for results, and visual comparison for screenshot testing — all included, no third-party plugins needed.

Setting Up a Playwright E2E Project

Start by scaffolding a new project with the Playwright CLI. This creates the config file, example tests, and installs browsers:

Terminal

npm init playwright@latest
# Choose TypeScript, tests folder, GitHub Actions workflow
npx playwright install

Now configure playwright.config.ts specifically for E2E testing. The key settings are baseURL (so you write relative paths in tests), webServer (to auto-start your app), and fullyParallel:

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 ? 4 : undefined,
  reporter: 'html',

  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

  /* Auto-start your dev server before tests */
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 120_000,
  },

  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 7'] },
    },
  ],
});

Tip: The webServer option is a game-changer for E2E. It starts your application before tests run and shuts it down after. No more manual "start the server in another terminal" workflows. In CI, set reuseExistingServer: false to ensure a clean start.

Writing Real-World E2E Tests

Let's write three real-world E2E tests that cover the most common user journeys: login, product search, and checkout. These aren't toy examples — they use the patterns you'll actually need in production.

Login Flow

A login E2E test should verify the complete flow: navigate to login, enter credentials, submit, and confirm the user reaches the authenticated dashboard.

tests/e2e/login.spec.ts

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

test.describe('Login Flow', () => {
  test('successful login redirects to dashboard', async ({ page }) => {
    await page.goto('/login');

    // Fill credentials using accessible locators
    await page.getByLabel('Email address').fill('user@example.com');
    await page.getByLabel('Password').fill('SecurePass123!');

    // Submit and wait for navigation
    await page.getByRole('button', { name: 'Sign in' }).click();

    // Assert: user lands on dashboard
    await expect(page).toHaveURL('/dashboard');
    await expect(
      page.getByRole('heading', { name: 'Welcome back' })
    ).toBeVisible();
  });

  test('invalid credentials show error message', async ({ page }) => {
    await page.goto('/login');

    await page.getByLabel('Email address').fill('wrong@example.com');
    await page.getByLabel('Password').fill('WrongPassword');
    await page.getByRole('button', { name: 'Sign in' }).click();

    // Assert: error appears, URL stays on login
    await expect(
      page.getByRole('alert')
    ).toContainText('Invalid email or password');
    await expect(page).toHaveURL('/login');
  });
});

Product Search

tests/e2e/search.spec.ts

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

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

  // Type search query
  const searchBox = page.getByPlaceholder('Search products...');
  await searchBox.fill('wireless headphones');
  await searchBox.press('Enter');

  // Wait for results to load
  const results = page.getByTestId('product-card');
  await expect(results).not.toHaveCount(0);

  // Verify first result is relevant
  const firstProduct = results.first();
  await expect(firstProduct).toContainText(/headphone|wireless|audio/i);

  // Verify URL updated with search params
  await expect(page).toHaveURL(/\?q=wireless\+headphones/);
});

Checkout Flow

tests/e2e/checkout.spec.ts

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

test('complete checkout flow', async ({ page }) => {
  // Step 1: Add item to cart
  await page.goto('/products/wireless-headphones-pro');
  await page.getByRole('button', { name: 'Add to Cart' }).click();

  // Assert cart badge updates
  await expect(
    page.getByTestId('cart-count')
  ).toHaveText('1');

  // Step 2: Go to cart and proceed
  await page.getByRole('link', { name: 'Cart' }).click();
  await expect(page).toHaveURL('/cart');
  await page.getByRole('button', { name: 'Proceed to Checkout' }).click();

  // Step 3: Fill shipping details
  await page.getByLabel('Full name').fill('Jane Doe');
  await page.getByLabel('Address').fill('123 Test Street');
  await page.getByLabel('City').fill('San Francisco');
  await page.getByLabel('ZIP code').fill('94102');

  // Step 4: Fill payment (test card)
  const stripeFrame = page.frameLocator('iframe[name*="stripe"]');
  await stripeFrame.getByPlaceholder('Card number')
    .fill('4242424242424242');
  await stripeFrame.getByPlaceholder('MM / YY').fill('12/28');
  await stripeFrame.getByPlaceholder('CVC').fill('123');

  // Step 5: Place order
  await page.getByRole('button', { name: 'Place Order' }).click();

  // Assert: confirmation page
  await expect(page).toHaveURL(/\/order-confirmation/);
  await expect(
    page.getByRole('heading', { name: 'Order Confirmed' })
  ).toBeVisible();
  await expect(
    page.getByText('Wireless Headphones Pro')
  ).toBeVisible();
});

Test Isolation and Authentication

Most E2E tests require an authenticated user. Logging in through the UI for every single test wastes time and adds fragility. Playwright's storageState feature solves this elegantly.

Global Setup for Authentication

Create a global setup file that runs once before all tests. It logs in, then saves the authenticated browser state to a JSON file:

tests/e2e/auth.setup.ts

import { test as setup } from '@playwright/test';

const authFile = '.auth/user.json';

setup('authenticate', async ({ page }) => {
  // Navigate and log in
  await page.goto('/login');
  await page.getByLabel('Email address').fill('e2e-user@example.com');
  await page.getByLabel('Password').fill(process.env.E2E_PASSWORD!);
  await page.getByRole('button', { name: 'Sign in' }).click();

  // Wait for authenticated state
  await page.waitForURL('/dashboard');

  // Save auth state for all tests to reuse
  await page.context().storageState({ path: authFile });
});

Then wire it into your config so authenticated tests skip the login step entirely:

playwright.config.ts (projects section)

projects: [
  // Setup project runs first
  { name: 'setup', testMatch: /.*\.setup\.ts/ },

  // All E2E tests depend on setup
  {
    name: 'chromium',
    use: {
      ...devices['Desktop Chrome'],
      storageState: '.auth/user.json',
    },
    dependencies: ['setup'],
  },
],

Tip: For tests that need different user roles (admin vs. regular user), create multiple auth setup files and storage state files. Reference the appropriate one in each project configuration.

Mocking APIs in E2E Tests

Sometimes you need to test edge cases that are hard to reproduce with a real backend — empty states, error responses, slow network conditions, or third-party API failures. Playwright's page.route() lets you intercept and mock any network request. For a deeper dive, see our Playwright API testing guide.

Mocking a REST API Response

tests/e2e/empty-state.spec.ts

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

test('displays empty state when no products exist', async ({ page }) => {
  // Intercept the products API and return empty array
  await page.route('**/api/products*', async (route) => {
    await route.fulfill({
      status: 200,
      contentType: 'application/json',
      body: JSON.stringify({ products: [], total: 0 }),
    });
  });

  await page.goto('/products');

  // Assert empty state UI renders
  await expect(
    page.getByText('No products found')
  ).toBeVisible();
  await expect(
    page.getByRole('link', { name: 'Browse categories' })
  ).toBeVisible();
});

Simulating Server Errors

tests/e2e/error-handling.spec.ts

test('handles 500 server error gracefully', async ({ page }) => {
  await page.route('**/api/checkout', async (route) => {
    await route.fulfill({
      status: 500,
      contentType: 'application/json',
      body: JSON.stringify({ error: 'Internal Server Error' }),
    });
  });

  // Navigate to checkout (already has items in cart via storageState)
  await page.goto('/checkout');
  await page.getByRole('button', { name: 'Place Order' }).click();

  // Assert: user-friendly error, not a crash
  await expect(
    page.getByRole('alert')
  ).toContainText('Something went wrong. Please try again.');
});

test('shows loading state on slow network', async ({ page }) => {
  // Simulate a 3-second delay on the API
  await page.route('**/api/products*', async (route) => {
    await new Promise(r => setTimeout(r, 3000));
    await route.continue();
  });

  await page.goto('/products');

  // Assert: skeleton loader appears while waiting
  await expect(
    page.getByTestId('product-skeleton')
  ).toBeVisible();
});

Tip: You can selectively mock some endpoints while letting others hit the real server. This lets you test your frontend against real auth and real data while controlling specific edge cases.

Visual Regression in E2E Flows

Functional assertions verify that elements exist and contain the right text. But they don't catch visual bugs — overlapping elements, broken layouts, wrong colors, or missing icons. Playwright's built-in toHaveScreenshot() fills this gap. For a comprehensive walkthrough, see our visual regression testing guide.

tests/e2e/visual.spec.ts

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

test('dashboard renders correctly after login', async ({ page }) => {
  await page.goto('/dashboard');

  // Wait for all data to load
  await expect(
    page.getByTestId('dashboard-stats')
  ).toBeVisible();

  // Full page screenshot comparison
  await expect(page).toHaveScreenshot('dashboard-full.png', {
    fullPage: true,
    maxDiffPixelRatio: 0.01, // Allow 1% pixel diff
  });
});

test('checkout form layout is pixel-perfect', async ({ page }) => {
  await page.goto('/checkout');

  // Screenshot just the form component
  const form = page.getByTestId('checkout-form');
  await expect(form).toHaveScreenshot('checkout-form.png');
});

The first time you run these tests, Playwright creates baseline screenshots. On subsequent runs, it compares the current screenshot against the baseline and fails if they differ beyond the threshold. Update baselines with npx playwright test --update-snapshots.

Running E2E Tests in CI/CD

E2E tests deliver the most value when they run on every pull request. Here's a production-ready GitHub Actions configuration with sharding for fast feedback:

.github/workflows/e2e.yml

name: E2E Tests
on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  e2e-tests:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard: [1/4, 2/4, 3/4, 4/4]

    steps:
      - uses: actions/checkout@v4

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

      - run: npm ci

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

      - name: Run E2E Tests
        run: npx playwright test --shard=${{ matrix.shard }}
        env:
          E2E_PASSWORD: ${{ secrets.E2E_PASSWORD }}

      - name: Upload Report
        uses: actions/upload-artifact@v4
        if: '!cancelled()'
        with:
          name: playwright-report-${{ strategy.job-index }}
          path: playwright-report/
          retention-days: 14

      - name: Upload Traces
        uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: test-traces-${{ strategy.job-index }}
          path: test-results/
          retention-days: 7

This configuration splits your test suite across four parallel CI machines using the --shard flag. A suite that takes 20 minutes on one machine finishes in roughly 5 minutes across four shards. The fail-fast: false ensures all shards complete so you see every failure, not just the first one.

Tip: Always upload traces on failure. The Playwright Trace Viewer shows a complete timeline of every action, network request, and DOM snapshot — making remote CI failures as debuggable as local ones.

E2E Testing Best Practices

After building E2E suites with hundreds of tests, these ten practices consistently separate reliable suites from flaky ones. For more depth on each, see our Playwright best practices guide.

Test User Journeys, Not Individual Pages

Each E2E test should follow a complete user workflow: search → select → add to cart → checkout. Testing pages in isolation is for integration tests. E2E tests prove the journey works end to end.

Use Role-Based Locators Exclusively

Always prefer getByRole(), getByLabel(), and getByText() over CSS selectors. They're resilient to refactors and double as accessibility checks.

Isolate Every Test Completely

No test should depend on another test's output. Use storageState for auth, API calls for data seeding, and fresh browser contexts for state isolation. Tests must pass when run in any order.

Seed Test Data via API, Not UI

Use request.post() in fixtures to create users, products, and orders. UI-based setup is slow, fragile, and makes test failures ambiguous — is the test broken or the setup flow?

Never Use Hard-Coded Waits

Replace every page.waitForTimeout() with a web-first assertion or waitForResponse(). Hard-coded waits are slow when the app is fast and flaky when it's slow.

Keep E2E Tests Under 30 Seconds Each

If a test takes longer than 30 seconds, it's doing too much. Break it into focused journeys. Fast tests get run more often and provide quicker feedback.

Run Cross-Browser But Prioritize Chromium

Run Chromium on every PR. Run Firefox and WebKit on the nightly or release pipeline. This keeps PR feedback fast while still catching cross-browser issues before release.

Use Traces and Video for Debugging

Configure trace: 'on-first-retry' and video: 'retain-on-failure'. When a test fails in CI, you'll have a complete timeline instead of a cryptic assertion error.

Tag and Organize Tests by Feature

Use test.describe() blocks and file naming conventions (e.g., checkout.spec.ts, auth.spec.ts) to group tests by feature. Use --grep to run subsets during development.

Treat E2E Failures as Production Bugs

When an E2E test fails, investigate immediately. Don't disable it and move on. If the test is flaky, fix the flakiness. If the app is broken, fix the app. A disabled test provides zero value.

Accelerate E2E Testing with Claude AI

Writing comprehensive E2E tests is time-consuming. You need to think through user flows, handle edge cases, set up authentication, mock APIs, and maintain the suite as the application evolves. This is where Claude AI and the Playwright MCP Server change the game.

AI-Powered Test Generation

Instead of writing every test by hand, you can describe the user journey in plain English and let Claude AI generate the complete Playwright test — including locators, assertions, error handling, and data setup. Claude understands Playwright's API deeply, so the generated tests follow all the best practices covered in this guide.

The Playwright MCP Server

The Model Context Protocol (MCP) Server for Playwright connects Claude directly to your running application. Claude can browse your app in real-time, inspect the DOM, identify elements, and generate tests based on what it actually sees — not just what you describe. This eliminates the guesswork of writing locators and assertions.

What the Course Covers

Complete Playwright E2E framework from scratch
Claude AI for automatic test generation
MCP Server setup and configuration
Authentication and storageState patterns
API mocking and network interception
Visual regression testing workflows
CI/CD pipeline with GitHub Actions
Self-healing locators with AI

Frequently Asked Questions

What is end-to-end testing in Playwright?

End-to-end testing in Playwright means automating complete user workflows in a real browser — navigating pages, filling forms, clicking buttons, and verifying outcomes across the entire application stack. Playwright supports Chromium, Firefox, and WebKit, so you test across all major browsers with a single test suite.

How do I handle authentication in Playwright E2E tests?

Use Playwright's storageState feature. Create a global setup file that logs in once and saves cookies/localStorage to a JSON file. Reference that file in your test projects. Every subsequent test starts already authenticated, eliminating repeated login steps and speeding up your suite dramatically.

Can Playwright mock APIs during E2E tests?

Yes. Use page.route() to intercept any network request and return mock responses. This lets you test edge cases like empty states, error responses, and slow networks without needing a real backend in those states. You can mock specific endpoints while letting others pass through to the real server.

How many E2E tests should I write?

Cover every critical revenue path: signup, login, core product workflows, checkout, and payment. A typical mid-size application has 50–150 E2E tests covering 15–30 core user journeys. Don't aim for 100% coverage with E2E — that's what unit and integration tests are for. Focus E2E tests on flows where failure means lost revenue or broken user experience.

How do I run Playwright E2E tests in CI/CD?

Use GitHub Actions with the official Playwright setup. Install browsers with npx playwright install --with-deps, run tests with npx playwright test, and upload the HTML report as an artifact. For large suites, use sharding (--shard=1/4) to split tests across parallel CI jobs for faster feedback.

Meet Your Instructor

Asim Noaman

Senior QA Automation Engineer & AI Testing Specialist

With years of hands-on experience building test automation frameworks for production applications, Asim specializes in combining traditional QA methodologies with cutting-edge AI tools. He has helped teams adopt Playwright and AI-driven testing workflows to ship faster with fewer bugs.

Udemy Instructor Published course author

Playwright + AI Expert Specialized in AI-powered QA

Production Experience Enterprise-grade frameworks

Connect on LinkedIn