@coder/pixel-storybook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Chris Kalmar & Dimitri Ivashchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @coder/pixel-storybook
+
+Visual regression testing tool for Storybook.
+
+## Installation
+
+```sh
+npm install @coder/pixel-storybook
+```
+
+## Usage
+
+```sh
+npx pixel-storybook
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/api.d.ts

@@ -0,0 +1,56 @@
+import type { PlatformModeConfig } from './config.js';
+import { type LogMemory, log } from './log.js';
+import type { StabilizationResult } from './types.js';
+export type ShotConfig = {
+    name: string;
+    threshold?: number;
+    /**
+     * Metadata about the pre-screenshot stability wait for this shot. Sent
+     * alongside the shot config so the platform can track stability metrics
+     * across builds.
+     */
+    stabilization?: StabilizationResult;
+};
+type ApiPayloadProcessShots = {
+    uploadToken: string;
+    config: {
+        threshold?: number;
+        shots?: ShotConfig[];
+    };
+    log: LogMemory;
+};
+export declare const getApiToken: (config: PlatformModeConfig) => Promise<{
+    apiToken: string;
+}>;
+export declare const sendInitToAPI: (config: PlatformModeConfig, apiToken: string) => Promise<unknown>;
+export declare const sendFinalizeToAPI: (config: PlatformModeConfig, apiToken: string) => Promise<unknown>;
+export declare const prepareUpload: (config: PlatformModeConfig, apiToken: string, shotNamesWithHashes: Array<{
+    name: string;
+    hash: string;
+}>) => Promise<{
+    requiredFileHashes: string[];
+    uploadToken: string;
+    uploadUrl: string;
+}>;
+export declare const uploadShot: ({ config, apiToken, uploadToken, uploadUrl, name, file, logger, }: {
+    config: PlatformModeConfig;
+    apiToken: string;
+    uploadToken: string;
+    uploadUrl: string;
+    name: string;
+    file: string;
+    logger?: ReturnType<typeof log.item>;
+}) => Promise<{
+    success: true;
+    details: {
+        projectId: string;
+        commit: string;
+        buildNumber: string;
+        branchName: string;
+        name: string;
+    };
+}>;
+export declare const processShots: (config: PlatformModeConfig, apiToken: string, uploadToken: string, shotsConfig?: ApiPayloadProcessShots["config"]["shots"]) => Promise<void>;
+export declare const uploadStorybookBuild: (config: PlatformModeConfig, apiToken: string, filePath: string) => Promise<void>;
+export declare const sendRecordLogsToAPI: (config: PlatformModeConfig, apiToken: string) => Promise<void>;
+export {};

package/dist/api.js

@@ -0,0 +1,238 @@
+import { readFile } from 'node:fs/promises';
+import { retry } from './concurrency.js';
+import { log, logMemory } from './log.js';
+import { getVersion } from './utils.js';
+const version = getVersion();
+const defaultHeaders = {
+    'x-api-version': '3',
+    'x-client-version': version ?? 'unknown',
+};
+const apiRoutes = {
+    getApiToken: '/auth/get-api-token',
+    init: '/app/init',
+    finalize: '/app/finalize',
+    prepareUpload: '/file/prepare-upload',
+    uploadShot: '/file/upload-shot',
+    processShots: '/app/process-shots',
+    recordLogs: '/app/record-logs',
+    uploadStorybookBuild: '/app/upload-storybook',
+};
+class ApiError extends Error {
+    status;
+    responseData;
+    constructor(message, status, responseData) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.responseData = responseData;
+    }
+}
+const sendToAPI = async (config, parameters, fileKey, customLogger) => {
+    const logger = customLogger?.process ?? log.process;
+    logger('info', 'api', `⚡️ Sending to API [${parameters.action}]`);
+    logger('info', 'api', `Endpoint: ${config.lostPixelPlatform}${apiRoutes[parameters.action]}`);
+    try {
+        const apiCall = async () => {
+            const url = `${config.lostPixelPlatform}${apiRoutes[parameters.action]}`;
+            let body;
+            const headers = {
+                ...defaultHeaders,
+                Authorization: `Bearer ${parameters.apiToken ?? ''}`,
+                'x-api-key': config.apiKey ?? 'undefined',
+            };
+            if (fileKey) {
+                const form = new FormData();
+                for (const [key, element] of Object.entries(parameters.payload)) {
+                    if (key === fileKey) {
+                        const fileBuffer = await readFile(element);
+                        const blob = new Blob([fileBuffer], { type: 'image/png' });
+                        form.append(key, blob, element.split('/').pop());
+                    }
+                    else {
+                        form.append(key, element);
+                    }
+                }
+                body = form;
+                // Let fetch set Content-Type with boundary for FormData
+            }
+            else {
+                body = JSON.stringify(parameters.payload);
+                headers['Content-type'] = 'application/json';
+            }
+            const response = await fetch(url, {
+                method: 'POST',
+                headers,
+                body,
+            });
+            const responseData = await response.json().catch(() => ({}));
+            if (!response.ok) {
+                const error = new ApiError(`API request failed with status ${response.status} ${response.statusText}`, response.status, responseData);
+                throw error;
+            }
+            return {
+                ok: response.ok,
+                status: response.status,
+                data: responseData,
+                headers: Object.fromEntries(response.headers.entries()),
+            };
+        };
+        const response = await retry({
+            times: 3,
+            interval(retryCount) {
+                const delay = Math.round(2 ** retryCount * 3000 * Math.random());
+                logger('info', 'api', `🔄 Retry attempt ${retryCount} in ${delay}ms [${parameters.action}]`);
+                logger('info', 'api', `${config.lostPixelPlatform}${apiRoutes[parameters.action]}`);
+                return delay;
+            },
+            errorFilter(error) {
+                if (error instanceof ApiError) {
+                    return ((error.status >= 500 && error.status <= 599) || error.status === 0);
+                }
+                // Network errors (fetch throws TypeError for network failures)
+                return true;
+            },
+        }, apiCall);
+        if (!response.ok) {
+            logger('error', 'api', `Error: Failed to send to API [${parameters.action}]. Status: ${response.status}`);
+            process.exit(1);
+        }
+        const outdatedApiRequest = response?.headers?.['x-api-version-warning'];
+        if (outdatedApiRequest &&
+            (parameters.action === 'prepareUpload' ||
+                parameters.action === 'finalize')) {
+            logger('info', 'api', [
+                '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~',
+                `~~ ⚠️  ${outdatedApiRequest}`,
+                '~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~',
+            ].join('\n'));
+        }
+        logger('info', 'api', `🤘 Successfully sent to API [${parameters.action}]`);
+        return response.data;
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            logger('error', 'api', 'API response: ', error.responseData || error.message);
+        }
+        else if (error instanceof Error) {
+            logger('error', 'api', error.message);
+        }
+        else {
+            logger('error', 'api', error);
+        }
+        if (parameters.action === 'getApiToken') {
+            process.exit(1);
+        }
+        throw error;
+    }
+};
+export const getApiToken = async (config) => {
+    return sendToAPI(config, {
+        action: 'getApiToken',
+        payload: {
+            projectId: config.lostPixelProjectId,
+        },
+    });
+};
+export const sendInitToAPI = async (config, apiToken) => {
+    return sendToAPI(config, {
+        action: 'init',
+        apiToken,
+        payload: {
+            commit: config.commitHash,
+            branchName: config.commitRefName,
+            buildNumber: config.ciBuildNumber,
+        },
+    });
+};
+export const sendFinalizeToAPI = async (config, apiToken) => {
+    return sendToAPI(config, {
+        action: 'finalize',
+        apiToken,
+        payload: {
+            projectId: config.lostPixelProjectId,
+            branchName: config.commitRefName,
+            commit: config.commitHash,
+            buildNumber: config.ciBuildNumber,
+        },
+    });
+};
+export const prepareUpload = async (config, apiToken, shotNamesWithHashes) => {
+    return sendToAPI(config, {
+        action: 'prepareUpload',
+        apiToken,
+        payload: {
+            branchName: config.commitRefName,
+            commit: config.commitHash,
+            buildNumber: config.ciBuildNumber,
+            currentShots: shotNamesWithHashes,
+        },
+    });
+};
+export const uploadShot = async ({ config, apiToken, uploadToken, uploadUrl, name, file, logger, }) => {
+    return sendToAPI({
+        ...config,
+        lostPixelPlatform: uploadUrl,
+    }, {
+        action: 'uploadShot',
+        apiToken,
+        payload: {
+            uploadToken,
+            name,
+            file,
+        },
+    }, 'file', logger);
+};
+export const processShots = async (config, apiToken, uploadToken, shotsConfig) => {
+    return sendToAPI(config, {
+        action: 'processShots',
+        apiToken,
+        payload: {
+            uploadToken,
+            config: {
+                shots: shotsConfig,
+                threshold: config.threshold,
+            },
+            log: logMemory,
+        },
+    });
+};
+export const uploadStorybookBuild = async (config, apiToken, filePath) => {
+    return sendToAPI(config, {
+        action: 'uploadStorybookBuild',
+        apiToken,
+        payload: {
+            projectId: config.lostPixelProjectId,
+            buildId: config.ciBuildId,
+            buildNumber: config.ciBuildNumber,
+            branchName: config.commitRefName,
+            commit: config.commitHash,
+            file: filePath,
+        },
+    }, 'file');
+};
+export const sendRecordLogsToAPI = async (config, apiToken) => {
+    try {
+        await sendToAPI(config, {
+            action: 'recordLogs',
+            apiToken,
+            payload: {
+                branchName: config.commitRefName,
+                buildNumber: config.ciBuildNumber,
+                commit: config.commitHash,
+                log: logMemory,
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof ApiError) {
+            log.process('error', 'api', 'API response: ', error.responseData || error.message);
+        }
+        else if (error instanceof Error) {
+            log.process('error', 'api', error.message);
+        }
+        else {
+            log.process('error', 'api', error);
+        }
+        log.process('error', 'api', 'Error: Failed to send logs to API');
+    }
+};

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from 'node:fs';
+import { cp } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { sendFinalizeToAPI } from './api.js';
+import { config, configure, isPlatformModeConfig } from './config.js';
+import { log } from './log.js';
+import { getPlatformApiToken, platformRunner, runner } from './runner.js';
+import { uploadStorybook } from './uploadStorybook.js';
+import { getVersion, isLocalDebugMode } from './utils.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const { positionals: commandArgs, values: optionValues } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        help: { type: 'boolean', short: 'h' },
+        version: { type: 'boolean', short: 'v' },
+    },
+    allowPositionals: true,
+    strict: false,
+});
+const version = getVersion();
+if (optionValues.version) {
+    log.process('info', 'general', version ?? 'unknown');
+    process.exit(0);
+}
+if (optionValues.help) {
+    printHelp();
+    process.exit(0);
+}
+if (version) {
+    log.process('info', 'general', `Version: ${version}`);
+}
+function printHelp() {
+    log.process('info', 'general', [
+        'Usage: pixel-storybook [command] [options]',
+        '',
+        'Visual regression testing tool for Storybook. Captures screenshots',
+        'via Playwright and compares them against baselines.',
+        '',
+        'Commands:',
+        '  init-js             Create a lostpixel.config.js in the current directory',
+        '  init-ts             Create a lostpixel.config.ts in the current directory',
+        '  update              Update baseline images with the current shots',
+        '  local               Enable local debug mode',
+        '  meta                Generate metadata for each shot',
+        '  finalize            Finalize a platform run (platform mode)',
+        '  upload-storybook    Upload a Storybook build to the platform',
+        '',
+        'Options:',
+        '  -h, --help          Print this help message and exit',
+        '  -v, --version       Print the version and exit',
+        '  -m <mode>           Set the mode (e.g. update)',
+        '  --shard <n/total>   Run a specific shard of the suite (e.g. 2/4)',
+        '',
+        'Environment variables:',
+        '  LOST_PIXEL_MODE             Same as -m',
+        '  LOST_PIXEL_LOCAL            Set to "true" for local debug mode',
+        '  LOST_PIXEL_GENERATE_META    Set to "true" to generate metadata',
+        '  LOST_PIXEL_SHARD            Same as --shard',
+    ].join('\n'));
+}
+(async () => {
+    if (commandArgs.includes('init-js')) {
+        log.process('info', 'general', 'Initializing javascript lost-pixel config');
+        await cp(path.join(__dirname, '..', 'config-templates', 'example.lostpixel.config.js'), path.join(process.cwd(), './lostpixel.config.js'));
+        log.process('info', 'general', '✅ Config successfully initialized');
+    }
+    else if (commandArgs.includes('init-ts')) {
+        log.process('info', 'general', 'Initializing typescript lost-pixel config');
+        // Replace local type resolution with module resolution
+        const file = readFileSync(path.join(__dirname, '..', 'config-templates', 'example.lostpixel.config.ts'));
+        const modifiedFile = file.toString().replace('../src/config', 'lost-pixel');
+        writeFileSync(path.join(process.cwd(), './lostpixel.config.ts'), modifiedFile);
+        log.process('info', 'general', '✅ Config successfully initialized');
+    }
+    else {
+        await configure({
+            localDebugMode: isLocalDebugMode(),
+        });
+        if (isPlatformModeConfig(config)) {
+            log.process('info', 'general', `🚀 Starting Pixel Storybook in 'platform' mode`);
+            const apiToken = await getPlatformApiToken(config);
+            if (commandArgs.includes('finalize')) {
+                await sendFinalizeToAPI(config, apiToken);
+            }
+            else if (commandArgs.includes('upload-storybook')) {
+                log.process('info', 'general', '📤 Starting Pixel storybook build upload');
+                await uploadStorybook(config, apiToken);
+            }
+            else {
+                await platformRunner(config, apiToken);
+            }
+        }
+        else {
+            log.process('info', 'general', `🚀 Starting Pixel Storybook in 'generateOnly' mode`);
+            await runner(config);
+        }
+    }
+})();

package/dist/checkDifferences.d.ts

@@ -0,0 +1,63 @@
+import type { ShotItem } from './types.js';
+export declare const checkDifferences: (shotItems: ShotItem[]) => Promise<{
+    aboveThresholdDifferenceItems: {
+        shotMode: "storybook";
+        id: string;
+        shotName: string;
+        url: string;
+        filePathBaseline: string;
+        filePathCurrent: string;
+        filePathDifference: string;
+        threshold: number;
+        browserConfig?: import("playwright-core").BrowserContextOptions | undefined;
+        waitBeforeScreenshot?: number | undefined;
+        stabilizeBeforeScreenshot?: boolean | undefined;
+        stabilization?: {
+            status: "stable" | "fonts-not-ready" | "images-not-ready" | "unstable";
+            elapsedMs: number;
+            capMs: number;
+        } | undefined;
+        importPath?: string | undefined;
+        mask?: {
+            selector: string;
+        }[] | undefined;
+        viewport?: {
+            width: number;
+            height?: number | undefined;
+        } | undefined;
+        breakpoint?: number | undefined;
+        breakpointGroup?: string | undefined;
+        elementLocator?: string | undefined;
+        waitForSelector?: string | undefined;
+    }[];
+    noBaselinesItems: {
+        shotMode: "storybook";
+        id: string;
+        shotName: string;
+        url: string;
+        filePathBaseline: string;
+        filePathCurrent: string;
+        filePathDifference: string;
+        threshold: number;
+        browserConfig?: import("playwright-core").BrowserContextOptions | undefined;
+        waitBeforeScreenshot?: number | undefined;
+        stabilizeBeforeScreenshot?: boolean | undefined;
+        stabilization?: {
+            status: "stable" | "fonts-not-ready" | "images-not-ready" | "unstable";
+            elapsedMs: number;
+            capMs: number;
+        } | undefined;
+        importPath?: string | undefined;
+        mask?: {
+            selector: string;
+        }[] | undefined;
+        viewport?: {
+            width: number;
+            height?: number | undefined;
+        } | undefined;
+        breakpoint?: number | undefined;
+        breakpointGroup?: string | undefined;
+        elementLocator?: string | undefined;
+        waitForSelector?: string | undefined;
+    }[];
+}>;

package/dist/checkDifferences.js

@@ -0,0 +1,67 @@
+import { existsSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { compareImages } from './compare/compare.js';
+import { mapLimit } from './concurrency.js';
+import { config, isPlatformModeConfig } from './config.js';
+import { log } from './log.js';
+import { featureNotSupported, shallGenerateMeta } from './utils.js';
+export const checkDifferences = async (shotItems) => {
+    if (isPlatformModeConfig(config)) {
+        return featureNotSupported('checkDifferences()');
+    }
+    log.process('info', 'general', `Comparing ${shotItems.length} screenshots using '${config.compareEngine}' as compare engine`);
+    const total = shotItems.length;
+    const noBaselinesItems = [];
+    const aboveThresholdDifferenceItems = [];
+    const comparisonResults = {};
+    await mapLimit([...shotItems.entries()], config.compareConcurrency, async ([index, shotItem]) => {
+        const logger = (message) => {
+            log
+                .item({
+                shotMode: shotItem.shotMode,
+                uniqueItemId: shotItem.shotName,
+                itemIndex: index,
+                totalItems: total,
+            })
+                .process('info', 'general', message);
+        };
+        logger(`Comparing '${shotItem.id}'`);
+        const baselineImageExists = existsSync(shotItem.filePathBaseline);
+        if (!baselineImageExists) {
+            logger('Baseline image missing. Will be treated as addition.');
+            noBaselinesItems.push(shotItem);
+            return;
+        }
+        const currentImageExists = existsSync(shotItem.filePathCurrent);
+        if (!currentImageExists) {
+            throw new Error(`Error: Missing current image: ${shotItem.filePathCurrent}`);
+        }
+        const { pixelDifference, pixelDifferencePercentage, isWithinThreshold } = await compareImages(shotItem.threshold, shotItem.filePathBaseline, shotItem.filePathCurrent, shotItem.filePathDifference);
+        if (shallGenerateMeta()) {
+            comparisonResults[shotItem.id] = {
+                pixelDifference,
+                pixelDifferencePercentage,
+                isWithinThreshold,
+            };
+        }
+        if (pixelDifference > 0) {
+            const percentage = (pixelDifferencePercentage * 100).toFixed(2);
+            if (isWithinThreshold) {
+                logger(`Difference of ${pixelDifference} pixels (${percentage}%) found but within threshold.`);
+            }
+            else {
+                aboveThresholdDifferenceItems.push(shotItem);
+                logger(`Difference of ${pixelDifference} pixels (${percentage}%) found. Difference image saved to: ${shotItem.filePathDifference}`);
+            }
+        }
+        else {
+            logger('No difference found.');
+        }
+    });
+    if (shallGenerateMeta()) {
+        log.process('info', 'general', `Writing meta file with ${Object.entries(comparisonResults).length} items.`);
+        writeFileSync(`${path.join(config.imagePathCurrent, 'meta')}.json`, JSON.stringify(comparisonResults, null, 2));
+    }
+    log.process('info', 'general', 'Comparison done!');
+    return { aboveThresholdDifferenceItems, noBaselinesItems };
+};

package/dist/compare/compare.d.ts

@@ -0,0 +1,5 @@
+import { type CompareResult } from './pixelmatch.js';
+export { checkThreshold } from './pixelmatch.js';
+export declare const compareImagesViaPixelmatch: (threshold: number, baselineShotPath: string, currentShotPath: string, differenceShotPath?: string) => Promise<CompareResult>;
+export declare const compareImagesViaOdiff: (threshold: number, baselineShotPath: string, currentShotPath: string, differenceShotPath: string) => Promise<CompareResult>;
+export declare const compareImages: (threshold: number, baselineShotPath: string, currentShotPath: string, differenceShotPath: string) => Promise<CompareResult>;

package/dist/compare/compare.js

@@ -0,0 +1,80 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Worker } from 'node:worker_threads';
+import { compare as odiffCompare } from 'odiff-bin';
+import { config, isPlatformModeConfig } from '../config.js';
+import { featureNotSupported } from '../utils.js';
+import { runPixelmatchComparison } from './pixelmatch.js';
+export { checkThreshold } from './pixelmatch.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+// Resolve the compiled worker script. Available after `pnpm build`.
+// When running from source (e.g. vitest), the .js file won't exist
+// and we fall back to inline comparison on the main thread.
+const workerScript = path.join(__dirname, 'worker.js');
+const canUseWorker = existsSync(workerScript);
+const comparePixelmatchWorker = (threshold, baselineShotPath, currentShotPath, differenceShotPath) => {
+    return new Promise((resolve, reject) => {
+        const worker = new Worker(workerScript, {
+            workerData: {
+                threshold,
+                baselineShotPath,
+                currentShotPath,
+                differenceShotPath,
+            },
+        });
+        worker.on('message', resolve);
+        worker.on('error', reject);
+        worker.on('exit', (code) => {
+            if (code !== 0) {
+                reject(new Error(`Pixelmatch worker exited with code ${code}`));
+            }
+        });
+    });
+};
+export const compareImagesViaPixelmatch = async (threshold, baselineShotPath, currentShotPath, differenceShotPath) => {
+    if (canUseWorker) {
+        return comparePixelmatchWorker(threshold, baselineShotPath, currentShotPath, differenceShotPath);
+    }
+    return runPixelmatchComparison(threshold, baselineShotPath, currentShotPath, differenceShotPath);
+};
+export const compareImagesViaOdiff = async (threshold, baselineShotPath, currentShotPath, differenceShotPath) => {
+    const result = await odiffCompare(baselineShotPath, currentShotPath, differenceShotPath, {
+        failOnLayoutDiff: false,
+    });
+    if (result.match) {
+        return {
+            pixelDifference: 0,
+            pixelDifferencePercentage: 0,
+            isWithinThreshold: true,
+        };
+    }
+    if (result.reason === 'pixel-diff') {
+        let isWithinThreshold = true;
+        // Treat theshold as percentage
+        const pixelDifferencePercentage = Number(result.diffPercentage / 100);
+        if (threshold < 1) {
+            isWithinThreshold = pixelDifferencePercentage <= threshold;
+        }
+        else {
+            // Treat threshold as absolute value
+            isWithinThreshold = result.diffCount <= threshold;
+        }
+        return {
+            pixelDifference: Number(result.diffCount),
+            pixelDifferencePercentage,
+            isWithinThreshold,
+        };
+    }
+    throw new Error("Couldn't compare images");
+};
+export const compareImages = async (threshold, baselineShotPath, currentShotPath, differenceShotPath) => {
+    if (isPlatformModeConfig(config)) {
+        return featureNotSupported('compareImages()');
+    }
+    if (config.compareEngine === 'pixelmatch') {
+        return compareImagesViaPixelmatch(threshold, baselineShotPath, currentShotPath, differenceShotPath);
+    }
+    return compareImagesViaOdiff(threshold, baselineShotPath, currentShotPath, differenceShotPath);
+};

package/dist/compare/pixelmatch.d.ts

@@ -0,0 +1,7 @@
+export type CompareResult = {
+    pixelDifference: number;
+    pixelDifferencePercentage: number;
+    isWithinThreshold: boolean;
+};
+export declare const checkThreshold: (threshold: number, pixelsTotal: number, pixelDifference: number) => boolean;
+export declare const runPixelmatchComparison: (threshold: number, baselineShotPath: string, currentShotPath: string, differenceShotPath?: string) => CompareResult;