Comprehensive visual test build execution, monitoring, and progress tracking system for Chromatic integration.
Execute and control Chromatic visual test builds with real-time progress monitoring.
/**
* Execute a Chromatic visual test build
* Internal function called by the preset via channel events
* @param localBuildProgress - Shared state object for build progress
* @param options - Build configuration with configFile, projectId, userToken
*/
function runChromaticBuild(
localBuildProgress: SharedState<LocalBuildProgress>,
options: { configFile?: string; projectId?: string; userToken?: string }
): void;
/**
* Stop a currently running Chromatic build
* Cancels the build process using AbortController
*/
function stopChromaticBuild(): void;Usage Note:
These functions are internal to the addon and are called automatically through Storybook's channel system. They are not directly importable or callable by users. Visual tests are triggered through the Storybook UI panel provided by the addon.
Real-time build progress tracking with detailed step-by-step updates.
/**
* Monitor build progress with timeout handling
* @param localBuildProgress - Build progress state to monitor
* @param timeout - Optional timeout in milliseconds
* @returns Promise that resolves when progress event occurs
*/
function onStartOrProgress(
localBuildProgress: LocalBuildProgress,
timeout?: number
): Promise<void>;
/**
* Handle build completion or error states
* @param localBuildProgress - Build progress state to monitor
* @param timeout - Optional timeout in milliseconds
* @returns Promise that resolves when build completes or errors
*/
function onCompleteOrError(
localBuildProgress: LocalBuildProgress,
timeout?: number
): Promise<void>;
interface LocalBuildProgress {
/** The id of the build, available after the initialize step */
buildId?: string;
/** The branch we ran the local build on */
branch?: string;
/** Overall percentage of build progress */
buildProgressPercentage: number;
/** The step of the build process we have reached */
currentStep: KnownStep | 'aborted' | 'complete' | 'error' | 'limited';
/** Number of visual changes detected */
changeCount?: number;
/** Number of component errors detected */
errorCount?: number;
/** The error message formatted to display in CLI */
formattedError?: string;
/** The original error without formatting */
originalError?: Error | Error[];
/** URL relevant to the error */
errorDetailsUrl?: string;
/** Progress tracking data for each step */
stepProgress: Record<KnownStep, StepProgressPayload>;
/** Progress tracking data from the previous build (if any) */
previousBuildProgress?: Record<KnownStep, StepProgressPayload>;
}Predefined build steps with configuration and progress tracking.
/**
* Known build step types in execution order
*/
type KnownStep = 'initialize' | 'build' | 'upload' | 'verify' | 'snapshot';
/**
* Array of build steps in execution order
*/
declare const BUILD_STEP_ORDER: KnownStep[];
/**
* Configuration for each build step
*/
interface BuildStepConfig {
/** Display emoji for the step */
emoji: string;
/** Human-readable step name */
name: string;
/** Function to render progress for this step */
renderProgress: (progress: number) => string;
/** Estimated duration in milliseconds */
estimatedDuration: number;
}
declare const BUILD_STEP_CONFIG: Record<KnownStep, BuildStepConfig>;
/**
* Default initial build progress state
*/
declare const INITIAL_BUILD_PAYLOAD: LocalBuildProgress;
/**
* Serialized initial build state for channel communication
*/
declare const INITIAL_BUILD_PAYLOAD_JSON: string;Detailed progress information for individual build steps.
interface StepProgressPayload {
/** Current task progress value (e.g. bytes or snapshots) */
numerator?: number;
/** Current task progress total (e.g. bytes or snapshots) */
denominator?: number;
/** Step start timestamp */
startedAt?: number;
/** Step completion timestamp */
completedAt?: number;
}
/**
* Check if a task string represents a known build step
* @param task - Task identifier to check
* @returns True if task is a known step type
*/
function isKnownStep(task: string): task is KnownStep;
/**
* Check if a build step supports progress events
* @param task - Task identifier to check
* @returns True if step emits progress events
*/
function hasProgressEvent(task: string): boolean;Callback system for receiving build progress updates.
/**
* Function type for receiving build status updates
* Called whenever build progress changes
* @param statuses - Array of Storybook status objects
*/
type UpdateStatusFunction = (statuses: Status[]) => void;Usage Note:
Status update functions are used internally by the addon to communicate build progress through Storybook's channel system. Users interact with build progress through the Visual Tests panel UI, not directly through these callback functions.
Complete build lifecycle state tracking from announcement to completion.
interface AnnouncedBuild {
id: string;
status: 'ANNOUNCED';
branch: string;
commit: string;
createdAt: string;
}
interface PublishedBuild extends AnnouncedBuild {
status: 'PUBLISHED';
publishedAt: string;
storybookUrl: string;
}
interface StartedBuild extends PublishedBuild {
status: 'STARTED';
startedAt: string;
buildUrl: string;
}
interface CompletedBuild extends StartedBuild {
status: 'PASSED' | 'FAILED' | 'CANCELLED' | 'PENDING';
completedAt: string;
changeCount: number;
errorCount: number;
testCount: number;
specCount: number;
componentCount: number;
}
/**
* Union type for builds that have tests available
*/
type SelectedBuildWithTests = StartedBuild | CompletedBuild;