Difora › Guides

Review Storybook changes from your own CI.

Use your existing stories as the capture surface. The Storybook test-runner renders them and completes their play functions; Difora compares the PNGs and gives your team a shared review.

For teams already using the test-runner

This recipe uses an existing @storybook/test-runner setup and a reachable Storybook. It is not an integration with Storybook’s Vitest addon. Difora does not publish or host your Storybook, run interaction tests for you, or determine which stories a code change affects.

Capture after the story is ready

Install difora as a development dependency (Node 20+) alongside your compatible Storybook/test-runner versions. Add these hooks to .storybook/test-runner.ts; merge them with existing hooks so your own setup and assertions still execute.

import type { TestRunnerConfig } from '@storybook/test-runner';
import { createPostVisit } from 'difora/storybook';

const capture = createPostVisit({
  fullPage: true, viewportSuffix: true, captureMetadata: true,
});
export default {
  async preVisit(page) {
    await page.setViewportSize({ width: 1280, height: 800 });
  },
  async postVisit(page, context) {
    await page.evaluate(() => document.fonts.ready);
    await capture(page, context);
  },
} satisfies TestRunnerConfig;

Start Storybook with your project’s existing command and wait until it is ready. The example below assumes port 6006; use your actual URL. Clear only generated captures before each complete run.

node -e "require('node:fs').rmSync('screenshots', { recursive: true, force: true })"
# With DIFORA_TOKEN set as a CI secret; upload only if the complete suite succeeds:
npx test-storybook --url http://127.0.0.1:6006 &&
  npx difora upload ./screenshots

A story titled Components/Button with name Primary produces screenshots/Components/Button/Primary@1280.png and its metadata sidecar. Renaming titles or stories changes snapshot names. Use separate stable variants for browsers or themes that share a width.

Turn the first suite into a baseline

Create a project, accept Agreements as an organization owner and create its upload token. Run all intended stories on your baseline branch, inspect the initial build and approve the screenshots. Run the same suite again: unchanged images pass; intended design changes need a conscious decision.

Use discussions and optional reviewer assignment to coordinate a design-system review. Assignment alone does not restrict who may approve; owners configure approval policies separately. Review capabilities explains the current scope.

Keep the snapshot set complete

Skipping or filtering previously captured stories can report removals. Do not upload a partially failed run. Wait for application data and images in your existing story lifecycle, keep fonts and browsers pinned, and keep metadata beside each PNG. See environment matching.

Evaluating hosted browser execution? Read the Chromatic comparison. Capturing application journeys instead? Use the Playwright workflow.

Reference: Storybook 9 test-runner lifecycle and hooks. Confirm compatibility with your installed Storybook version.

Difora is an independent service. Product names identify the tools discussed; no affiliation or endorsement is implied.