Steph Huynh

● Guidelines / Visual testing

Visual testing.

Superbloom stories are the visual contract. Argos compares screenshots on every pull request so token, primitive, and pattern changes do not slip through unnoticed. This page covers how the pipeline works and how to run it locally. For the workflow write-up and screenshots, see the Visual regression for Superbloom post.

How it fits the system

Storybook is where primitives and patterns are documented and tested. The Vitest addon runs those stories in a real browser; Argos stores screenshots and diffs them against approved baselines. The same stories power the Vercel deploy , but Argos does not pull from that URL. It renders stories inside CI.

At a glance

Tooling

Storybook Vitest addon, Playwright, Argos

Coverage

Every story in light and dark mode

CI

GitHub Actions on pull requests and main

Storybook hosting

Vercel (stable) + Argos (per-build review)

CI pipeline

The Argos workflow runs on pull requests and pushes to main. Visual diffs surface on the pull request; intentional changes get approved before merge.

01

Render stories in CI

Vitest runs each Storybook story in headless Chromium via @storybook/addon-vitest. Argos captures a screenshot after each story renders.

02

Compare to baselines

Uploads go to Argos with separate baselines per mode. Visual diffs appear on the pull request when pixels change.

03

Review and approve

Accept intentional changes in the Argos UI. The GitHub check passes once all diffs are approved or unchanged.

Light and dark modes

Each story is captured twice. Modes in .storybook/modes.ts set Storybook globals that the theme decorator applies before the screenshot is taken.

export const allModes = {
  light: { theme: 'light' },
  dark: { theme: 'dark' }
};

Commands

Story tests run through Vitest. Playwright supplies the browser. Argos joins on upload or in CI.

pnpm storybook

Local Storybook on :6006 for iteration and a11y addon checks.

pnpm test:storybook

Run story tests locally. Does not upload to Argos unless CI=1 is set.

pnpm argos:upload

Run tests once and upload screenshots (requires ARGOS_TOKEN in .env).

pnpm build-storybook

Static Storybook build to storybook-static/.

pnpm deploy:storybook

Deploy static Storybook to Vercel (huynhicode-storybook.vercel.app).

When you run story tests

  • You run: pnpm test:storybook
  • Vitest says: "Run the Button default story."
  • Playwright says: "Opening Chromium, loading that story now."
  • Argos says: "Here is what it looked like; does it match last time?"

Argos only captures screenshots with pnpm argos:upload or in CI. pnpm test:storybook runs Vitest and Playwright without uploading.

Key files

vite.config.ts

storybookTest + argosVitestPlugin in the storybook Vitest project.

.storybook/modes.ts

light and dark globals applied as Argos snapshot modes.

.storybook/preview.ts

parameters.argos.modes and withThemeByClassName decorator.

.github/workflows/argos.yml

CI: visual tests, build-storybook, argos deploy.

Guidelines

  • Every new primitive or pattern needs a Storybook story. Visual coverage follows automatically.
  • Test hover, focus, and open states in Storybook before merging. Argos captures the default render, not every interaction, unless you add a play function with argosScreenshot.
  • Intentional visual changes need baseline approval in Argos before the check goes green.
  • Keep ARGOS_TOKEN in GitHub repository secrets for CI. Local .env is for manual uploads only.
  • Vercel Storybook deploy and Argos are separate: Vercel is the public reference URL; Argos is regression testing and per-PR review.

Quick checks

Does a new component need extra setup?

Add a story. Modes inherit from preview.ts.

Need dark mode coverage?

Already covered via allModes in .storybook/modes.ts.

CI shows missing ARGOS_TOKEN?

Add the project token to GitHub Actions secrets.

Playwright not found locally?

pnpm exec playwright install --with-deps chromium

Where to browse live stories?

Vercel Storybook deploy or pnpm storybook locally.

Related