Blog about Testing

Visual Regression Testing with Playwright and TypeScript

This guide demonstrates how to implement visual regression testing in a Next.js 14 project using Playwright and TypeScript. Visual regression testing helps ensure your UI components maintain visual consistency across updates and releases.

Prerequisites

Before starting, check out the guide on setting up your first Playwright test and configuring the project:Playwright First Test Setup

Step 1: Writing Your First Visual Test

In your `tests` directory, create a file named `visual.spec.ts` to capture a visual snapshot of your homepage.

test('About page visual snapshot', async ({ page }) => {
    await page.goto('https://sergeipetrukhin.vercel.app/about');
    const screenshot = await page.screenshot();
    expect(screenshot).toMatchSnapshot('aboutpage.png');
});

This code snippet takes a screenshot of the 'About' page. On the first run, it saves a baseline image. On subsequent runs, it compares the new screenshot with the baseline, flagging any visual differences.

Step 2: Running the Visual Tests

Make sure your app is running locally before executing the Playwright test command:

npm run test src/tests/visual.spec.ts

Step 3: Handling First Attempt Error

Upon the first test run, an error may occur because no snapshot has been saved yet. The second run will execute successfully after creating the baseline snapshot. Here's an example error:

Error: A snapshot doesn't exist at /sergeipetrukhin/src/tests/visual.spec.ts-snapshots/aboutpage-darwin.png, writing actual.

Step 4: Handling Pixel Differences

Small differences in pixels could arise due to minor UI changes. To handle these, use the `maxDiffPixels` option to allow for a set number of pixel differences:

test('About page visual test with maxDiffPixels', async ({ page }) => {
    await page.goto('https://sergeipetrukhin.vercel.app/about');
    const screenshot = await page.screenshot();
    expect(screenshot).toMatchSnapshot('aboutpage.png', {
        maxDiffPixels: 100 // allows for up to 100 pixel differences
    });
});

Step 5: Analyzing Test Results

Playwright can generate an HTML report that provides a visual breakdown of the test results. To enable this, update your `playwright.config.js` as shown below:

reporter: [['html', { open: 'on-failure' }]]

Here's the full configuration for your Playwright setup:

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

export default defineConfig({
  testDir: 'src/tests', // path to your tests directory
  timeout: 30000,
  expect: {
    timeout: 5000
  },
  reporter: [['html', { open: 'on-failure' }]]
});

To generate and view the HTML report, run the following commands:

npm run test src/tests/visual.spec.ts
npx playwright show-report

Conclusion

Visual regression testing is an essential part of maintaining UI consistency in your web application. With Playwright, you can efficiently capture visual snapshots and detect any unintended UI changes as your project evolves.

Additional Resources