npm package: @react-lens/test
Description: Visual snapshot testing for ReactLens previews
Latest version: 0.2.0

# @react-lens/test

Visual snapshot testing for React components using [ReactLens](https://gitlab.com/jorgeecardona/react-lens) `@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

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

Peer dependencies (you likely already have these):

```bash
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:

```tsx
/**
 * @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:

```tsx
/**
 * @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

```bash
# 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:

```ts
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

```ts
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:

```ts
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:

```bash
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