@react-lens/test

Visual snapshot testing for React components using ReactLens @preview annotations.

Renders your components with Vite + Playwright, captures screenshots, and compares them against baselines using pixel-level diffing. Designed for CI — no browser UI needed.

Install

npm install --save-dev @react-lens/test playwright
npx playwright install chromium

Peer dependencies (you likely already have these):

npm install --save-dev vite @vitejs/plugin-react

How it works

1. Scans your project for @preview annotations that include a snapshot field
2. Spins up a Vite dev server and Playwright browser
3. Renders each preview and captures a screenshot
4. Compares against baseline PNGs in __snapshots__/
5. Reports pass/fail with diff images for mismatches

Only previews with an explicit snapshot field are included — it's opt-in.

Annotate your components

Add a snapshot field to any @preview annotation:

/**
 * @preview {
 *   name: "Primary",
 *   snapshot: "button-primary",
 *   props: { label: "Click me", variant: "primary" }
 * }
 */
export function Button({ label, variant, onClick }: ButtonProps) {
  return <button className={variant} onClick={onClick}>{label}</button>;
}

For .preview.tsx files:

/**
 * @preview {
 *   name: "Card Previews",
 *   snapshot: "card"
 * }
 */
export default {
  'Basic': <Card title="Hello" />,
  'With Image': <Card title="Hello" image="/photo.jpg" />,
};

This generates snapshots card-basic and card-with-image.

CLI usage

# Run snapshot tests (compares against baselines)
npx reactlens test

# Create or update all baselines
npx reactlens test --update

# Update only baselines matching a filter
npx reactlens test --update button

Exit codes: 0 = all pass, 1 = mismatches or errors.

Output

ReactLens Visual Snapshot Tests

  PASS  button-primary
  FAIL  card-actions (0.45% diff, 1234 pixels)
        Diff: __snapshots__/card-actions-diff.png
  NEW   avatar-default (baseline created)

Results: 1 passed, 1 failed, 1 new | Duration: 4.2s

On failure, a -diff.png image is written showing the changed pixels in red.

Configuration

Create a reactlens.config.ts in your project root:

import { defineConfig } from '@react-lens/test';

export default defineConfig({
  // Glob patterns for finding component files (default: ['**/*.tsx', '**/*.jsx'])
  include: ['src/**/*.tsx'],

  // Snapshot settings
  snapshots: {
    // Output directory for baseline PNGs (default: '__snapshots__')
    directory: '__snapshots__',
    // Max fraction of pixels that can differ (0-1, default: 0.01 = 1%)
    threshold: 0.01,
  },
});

Programmatic API

import { runTests } from '@react-lens/test';

const summary = await runTests({
  projectRoot: process.cwd(),
  update: false,
  threshold: 0.01,
});

console.log(`${summary.passed} passed, ${summary.failed} failed`);

Individual modules are also exported:

import {
  discoverPreviews,   // Scan project for snapshot-enabled previews
  PreviewRenderer,    // Vite + Playwright screenshot capture
  compareImages,      // Pixel-level image comparison
  BaselineManager,    // Read/write baseline PNGs
} from '@react-lens/test';

CI setup

Add to your CI pipeline:

npm ci
npx playwright install --with-deps chromium
npx reactlens test

The test command exits with code 1 on mismatches, failing the build.

License

MIT