or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-management.mdconfiguration.mdindex.mdstorybook-integration.mdvisual-test-modes.md
tile.json

tessl/npm-chromatic-com--storybook

Catch unexpected visual changes & UI bugs in your stories

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@chromatic-com/storybook@4.1.x

To install, run

npx @tessl/cli install tessl/npm-chromatic-com--storybook@4.1.0

index.mddocs/

Visual Tests Addon for Storybook

The @chromatic-com/storybook addon provides comprehensive visual testing capabilities that integrate with Chromatic to catch unexpected visual changes and UI bugs in your Storybook stories. It enables automated visual regression testing directly from the Storybook interface, with support for multiple viewports, themes, and browsers.

Package Information

  • Package Name: @chromatic-com/storybook
  • Package Type: npm
  • Language: TypeScript
  • Installation: npx storybook add @chromatic-com/storybook

Core Imports

For Storybook preset configuration:

// .storybook/main.ts
export default {
  addons: ['@chromatic-com/storybook'],
};

Package exports (from package.json):

{
  "exports": {
    ".": "./dist/index.js",           // Main entry (empty export)
    "./manager": "./dist/manager.js", // Manager UI bundle
    "./preset": "./dist/preset.js",   // Server preset configuration
    "./package.json": "./package.json"
  }
}

Basic Usage

The addon provides zero-config visual testing through Storybook's interface:

// Stories automatically get visual testing capability
export default {
  title: 'Button',
  component: Button,
  parameters: {
    chromatic: {
      // Optional: Configure visual test behavior
      modes: {
        light: { theme: 'light' },
        dark: { theme: 'dark' },
      },
    },
  },
};

export const Primary = {
  args: {
    primary: true,
    label: 'Button',
  },
};

Architecture

The addon is built around several key components:

  • Storybook Integration: Automatic addon registration through preset and manager entries
  • Visual Test Panel: Dedicated UI panel in Storybook for running and monitoring visual tests
  • Build Management: Comprehensive build execution and progress tracking system
  • Chromatic Service: GraphQL-based integration with Chromatic's visual testing platform
  • Configuration System: Environment-based and parameter-based configuration options
  • Real-time Updates: Live build progress and status monitoring through Storybook's channel system

Capabilities

Storybook Integration

Core Storybook addon functionality including preset configuration and UI panel registration. This handles the automatic setup and integration with Storybook's architecture.

// Preset configuration (automatic via package.json exports)
interface PresetConfig {
  managerEntries: () => string[];
  experimental_serverChannel: (channel: any) => void;
  staticDirs: () => string[];
  env: () => Record<string, string>;
}

Storybook Integration

Build Management

Visual test build execution, monitoring, and status tracking. Provides real-time progress updates and comprehensive build state management.

/**
 * Execute a Chromatic visual test build
 * @param localBuildProgress - Build progress state object
 * @param options - Build configuration options
 * @returns Promise that resolves when build completes
 */
function runChromaticBuild(
  localBuildProgress: LocalBuildProgress,
  options: Record<string, any>
): Promise<void>;

/**
 * Stop a currently running Chromatic build
 */
function stopChromaticBuild(): void;

interface LocalBuildProgress {
  buildId: string;
  branch: string;
  progress: number;
  currentStep: KnownStep;
  changeCount: number;
  errorCount: number;
  stepProgress: StepProgressPayload[];
}

type KnownStep = 'initialize' | 'build' | 'upload' | 'verify' | 'snapshot';

Build Management

Configuration & Constants

Environment configuration, package identifiers, and channel event constants used throughout the addon.

// Environment URLs
declare const CHROMATIC_BASE_URL: string;
declare const CHROMATIC_API_URL: string;
declare const CHROMATIC_INDEX_URL: string;

// Package identifiers
declare const PACKAGE_NAME: '@chromatic-com/storybook';
declare const ADDON_ID: 'chromaui/addon-visual-tests';
declare const PANEL_ID: string;
declare const PARAM_KEY: 'chromatic';

// Channel events
declare const START_BUILD: string;
declare const STOP_BUILD: string;
declare const LOCAL_BUILD_PROGRESS: string;
declare const CONFIG_INFO: string;
declare const GIT_INFO: string;

Configuration & Constants

Visual Test Modes

Predefined visual testing configurations for different themes, viewports, and layout options.

interface VisualTestMode {
  name: string;
  viewport?: { width: number; height: number };
  theme?: string;
  [key: string]: any;
}

// Predefined mode collections
declare const baseModes: VisualTestMode[];
declare const panelModes: VisualTestMode[];

Visual Test Modes

Types

Build State Types

interface AnnouncedBuild {
  id: string;
  status: 'ANNOUNCED';
  branch: string;
  commit: string;
}

interface StartedBuild extends AnnouncedBuild {
  status: 'STARTED';
  startedAt: string;
}

interface CompletedBuild extends StartedBuild {
  status: 'PASSED' | 'FAILED' | 'CANCELLED';
  completedAt: string;
  changeCount: number;
  errorCount: number;
}

type SelectedBuildWithTests = StartedBuild | CompletedBuild;

Configuration Types

interface ConfigurationUpdate {
  [key: string]: any;
}

interface ConfigInfoPayload {
  configuration: Record<string, any>;
  problems: string[];
  suggestions: string[];
}

interface ProjectInfoPayload {
  projectId: string;
  projectToken: string;
  projectName: string;
}

interface GitInfoPayload {
  branch: string;
  commit: string;
  uncommittedHash?: string;
  parentCommits: string[];
}

Progress Tracking Types

interface StepProgressPayload {
  step: KnownStep;
  progress: number;
  estimatedDuration: number;
  startedAt?: string;
  completedAt?: string;
}

type UpdateStatusFunction = (progress: LocalBuildProgress) => void;