Visual Regression Testing

Overview

Visual regression tests capture screenshots of your resources and compare them against saved baselines. This catches unintended visual changes across themes, display modes, and hosts. Screenshot comparisons only run when you pass --visual. Without it, result.screenshot() calls are silently skipped, so you can include them in your regular e2e tests without affecting normal runs.

Running Visual Tests

pnpm
npm
yarn

pnpm test:visual                           # Compare against baselines
pnpm test:visual -- --update               # Update baselines

npm run test:visual                           # Compare against baselines
npm run test:visual -- --update               # Update baselines

yarn test:visual                           # Compare against baselines
yarn test:visual --update                  # Update baselines

Writing Visual Tests

Use result.screenshot() in any e2e test. It accepts an optional name and Playwright toHaveScreenshot options:

import { test, expect } from 'sunpeak/test';

test('albums renders correctly in light mode', async ({ inspector }) => {
  const result = await inspector.renderTool('show-albums', {}, { theme: 'light' });
  const app = result.app();
  await expect(app.locator('button:has-text("Summer Slice")')).toBeVisible();

  await result.screenshot('albums-light');
});

test('albums renders correctly in dark mode', async ({ inspector }) => {
  const result = await inspector.renderTool('show-albums', {}, { theme: 'dark' });
  const app = result.app();
  await expect(app.locator('button:has-text("Summer Slice")')).toBeVisible();

  await result.screenshot('albums-dark');
});

Screenshot Targets

By default, inspector.renderTool() hides the inspector sidebars, and screenshot() captures the app content inside the double-iframe. This keeps visual baselines stable when the inspector UI changes. Pass a specific element locator to narrow the capture further:

// Screenshot just the app (default)
await result.screenshot('app-view');

// Screenshot a specific element
await result.screenshot('album-card', {
  element: result.app().locator('button:has-text("Summer Slice")'),
});

Configuring Visual Defaults

Pass a visual option to defineConfig() to set project-wide defaults for screenshot comparison:

import { defineConfig } from 'sunpeak/test/config';
export default defineConfig({
  visual: {
    threshold: 0.2,
    maxDiffPixelRatio: 0.05,
    snapshotPathTemplate: '{testDir}/__screenshots__/{projectName}/{testFilePath}/{arg}{ext}',
  },
});

All Playwright toHaveScreenshot options (threshold, maxDiffPixelRatio, maxDiffPixels, animations, etc.) are supported. The snapshotPathTemplate controls where baseline images are stored.

E2E Testing

Full E2E testing guide with the mcp fixture.

Inspector

The runtime that powers visual tests.

​Overview

​Running Visual Tests

​Writing Visual Tests

​Screenshot Targets

​Configuring Visual Defaults

​See Also