@wdio/image-comparison-core 1.0.0

package/dist/helpers/beforeScreenshot.test.js

@@ -0,0 +1,261 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { join } from 'node:path';
+import logger from '@wdio/logger';
+import beforeScreenshot from './beforeScreenshot.js';
+import hideScrollBars from '../clientSideScripts/hideScrollbars.js';
+import hideRemoveElements from '../clientSideScripts/hideRemoveElements.js';
+import setCustomCss from '../clientSideScripts/setCustomCss.js';
+import toggleTextTransparency from '../clientSideScripts/toggleTextTransparency.js';
+import waitForFonts from '../clientSideScripts/waitForFonts.js';
+import { CUSTOM_CSS_ID } from './constants.js';
+const log = logger('test');
+vi.mock('@wdio/logger', () => import(join(process.cwd(), '__mocks__', '@wdio/logger')));
+vi.mock('../methods/instanceData.js', () => ({
+    default: vi.fn().mockResolvedValue({
+        appName: 'mocked-app',
+        browserName: 'mocked-browser',
+        devicePixelRatio: 1,
+        isAndroid: false,
+        isIOS: false,
+        isMobile: false,
+        platformName: 'mocked-platform',
+    })
+}));
+describe('beforeScreenshot', () => {
+    let logDebugSpy;
+    let logWarnSpy;
+    const createMockBrowserInstance = (mockExecuteFn = vi.fn().mockResolvedValue(''), customProperties = {}) => {
+        return {
+            execute: mockExecuteFn,
+            ...customProperties
+        };
+    };
+    beforeEach(() => {
+        logDebugSpy = vi.spyOn(log, 'debug').mockImplementation(() => { });
+        logWarnSpy = vi.spyOn(log, 'warn').mockImplementation(() => { });
+    });
+    afterEach(() => {
+        vi.clearAllMocks();
+        logDebugSpy.mockRestore();
+        logWarnSpy.mockRestore();
+    });
+    const baseInstanceData = {
+        appName: 'appName',
+        browserName: 'browserName',
+        browserVersion: 'browserVersion',
+        deviceName: 'deviceName',
+        devicePixelRatio: 1,
+        logName: 'logName',
+        deviceRectangles: {
+            bottomBar: { y: 0, x: 0, width: 0, height: 0 },
+            homeBar: { x: 0, y: 0, width: 0, height: 0 },
+            leftSidePadding: { y: 0, x: 0, width: 0, height: 0 },
+            rightSidePadding: { y: 0, x: 0, width: 0, height: 0 },
+            screenSize: { height: 1, width: 1 },
+            statusBar: { x: 0, y: 0, width: 0, height: 0 },
+            statusBarAndAddressBar: { y: 0, x: 0, width: 0, height: 0 },
+            viewport: { y: 0, x: 0, width: 0, height: 0 },
+        },
+        isAndroid: false,
+        isIOS: false,
+        isMobile: false,
+        name: 'name',
+        nativeWebScreenshot: false,
+        platformName: 'platformName',
+        platformVersion: 'platformVersion',
+        initialDevicePixelRatio: 1,
+    };
+    const baseOptions = {
+        addressBarShadowPadding: 6,
+        disableBlinkingCursor: false,
+        disableCSSAnimation: false,
+        enableLayoutTesting: false,
+        noScrollBars: false,
+        toolBarShadowPadding: 6,
+        hideElements: [],
+        removeElements: [],
+        waitForFontsLoaded: false,
+    };
+    const createOptions = (overrides = {}) => ({
+        instanceData: baseInstanceData,
+        ...baseOptions,
+        ...overrides,
+    });
+    it('should be able to return the enriched instance data with default options', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const options = createOptions();
+        expect(await beforeScreenshot(mockBrowserInstance, options)).toMatchSnapshot();
+    });
+    it('should be able to return the enriched instance data with `addShadowPadding: true`', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const options = createOptions({
+            disableBlinkingCursor: true,
+            disableCSSAnimation: true,
+            noScrollBars: true,
+            hideElements: ['<div></div>'],
+            removeElements: ['<div></div>'],
+            waitForFontsLoaded: true,
+        });
+        expect(await beforeScreenshot(mockBrowserInstance, options, true)).toMatchSnapshot();
+    });
+    it('should handle waitForFontsLoaded functionality', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const options = createOptions({
+            waitForFontsLoaded: true,
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(waitForFonts);
+    });
+    it('should handle waitForFontsLoaded error gracefully and log debug message', async () => {
+        const fontError = new Error('Font load error');
+        const mockExecute = vi.fn().mockRejectedValue(fontError);
+        const mockBrowserInstance = createMockBrowserInstance(mockExecute);
+        const options = createOptions({
+            waitForFontsLoaded: true,
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(waitForFonts);
+        expect(logDebugSpy).toHaveBeenCalledWith('Waiting for fonts to load threw an error:', fontError);
+    });
+    it('should handle noScrollBars option', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const options = createOptions({
+            noScrollBars: true,
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(hideScrollBars, true);
+    });
+    it('should handle hide and remove elements', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const hideElements = ['<div></div>'];
+        const removeElements = ['<span></span>'];
+        const options = createOptions({
+            hideElements,
+            removeElements,
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(hideRemoveElements, { hide: hideElements, remove: removeElements }, true);
+    });
+    it('should handle hide/remove elements error gracefully and log warning', async () => {
+        const elementError = new Error('Element not found');
+        const mockExecute = vi.fn().mockRejectedValue(elementError);
+        const mockBrowserInstance = createMockBrowserInstance(mockExecute);
+        const hideElements = ['<div></div>'];
+        const options = createOptions({
+            hideElements,
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(hideRemoveElements, { hide: hideElements, remove: [] }, true);
+        expect(logWarnSpy.mock.calls[0]).toMatchSnapshot();
+    });
+    it('should handle CSS customization for desktop', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const options = createOptions({
+            disableBlinkingCursor: true,
+            disableCSSAnimation: true,
+            addressBarShadowPadding: 10,
+            toolBarShadowPadding: 15,
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(setCustomCss, {
+            addressBarPadding: 0,
+            disableBlinkingCursor: true,
+            disableCSSAnimation: true,
+            id: CUSTOM_CSS_ID,
+            toolBarPadding: 0,
+        });
+    });
+    it('should handle CSS customization for mobile platform', async () => {
+        const mockBrowserInstance = createMockBrowserInstance(undefined, { isAndroid: true, isIOS: false, isMobile: true });
+        const options = createOptions({
+            instanceData: {
+                ...baseInstanceData,
+                platformName: 'Android',
+                isAndroid: true,
+                isMobile: true,
+            },
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(setCustomCss, {
+            addressBarPadding: 0,
+            disableBlinkingCursor: false,
+            disableCSSAnimation: false,
+            id: CUSTOM_CSS_ID,
+            toolBarPadding: 0,
+        });
+    });
+    it('should handle layout testing', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const options = createOptions({
+            enableLayoutTesting: true,
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(toggleTextTransparency, true);
+    });
+    it('should handle layout testing with addShadowPadding', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const options = createOptions({
+            enableLayoutTesting: true,
+            instanceData: {
+                ...baseInstanceData,
+                browserName: 'Safari',
+                platformName: 'iOS',
+                isIOS: true,
+                isMobile: true,
+            },
+        });
+        await beforeScreenshot(mockBrowserInstance, options, true);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(toggleTextTransparency, true);
+    });
+    it('should not execute browser commands when no options are enabled', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const options = createOptions();
+        await beforeScreenshot(mockBrowserInstance, options);
+        // Should only call the instanceData mock, no browser execute calls
+        expect(mockBrowserInstance.execute).not.toHaveBeenCalled();
+        expect(logDebugSpy).not.toHaveBeenCalled();
+        expect(logWarnSpy).not.toHaveBeenCalled();
+    });
+    it('should handle multiple options simultaneously', async () => {
+        const mockBrowserInstance = createMockBrowserInstance();
+        const hideElements = ['<div></div>'];
+        const options = createOptions({
+            waitForFontsLoaded: true,
+            noScrollBars: true,
+            hideElements,
+            disableBlinkingCursor: true,
+            enableLayoutTesting: true,
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(waitForFonts);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(hideScrollBars, true);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(hideRemoveElements, { hide: hideElements, remove: [] }, true);
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(setCustomCss, expect.any(Object));
+        expect(mockBrowserInstance.execute).toHaveBeenCalledWith(toggleTextTransparency, true);
+    });
+    it('should handle multiple errors and log both debug and warning messages', async () => {
+        const fontError = new Error('Font load error');
+        const elementError = new Error('Element not found');
+        const mockExecute = vi.fn()
+            .mockRejectedValueOnce(fontError) // waitForFonts
+            .mockRejectedValueOnce(elementError); // hideRemoveElements
+        const mockBrowserInstance = createMockBrowserInstance(mockExecute);
+        const options = createOptions({
+            waitForFontsLoaded: true,
+            hideElements: ['<div></div>'],
+        });
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(logDebugSpy).toHaveBeenCalledWith('Waiting for fonts to load threw an error:', fontError);
+        expect(logWarnSpy.mock.calls[0]).toMatchSnapshot();
+    });
+    it('should handle custom browser properties when needed', async () => {
+        const mockBrowserInstance = createMockBrowserInstance(undefined, {
+            getWindowSize: vi.fn().mockResolvedValue({ width: 1920, height: 1080 }),
+            getOrientation: vi.fn().mockResolvedValue('LANDSCAPE')
+        });
+        const options = createOptions();
+        await beforeScreenshot(mockBrowserInstance, options);
+        expect(mockBrowserInstance.getWindowSize).toBeDefined();
+        expect(mockBrowserInstance.getOrientation).toBeDefined();
+    });
+});

package/dist/helpers/compare.interfaces.d.ts

@@ -0,0 +1,16 @@
+import type { BaseImageCompareOptions, BaseMobileBlockOutOptions } from '../base.interfaces.js';
+import type { RectanglesOutput } from '../methods/rectangles.interfaces.js';
+export interface CoreCompareOptions extends BaseImageCompareOptions {
+    blockOut?: RectanglesOutput[];
+}
+export interface ScreenCompareOptions extends CoreCompareOptions, BaseMobileBlockOutOptions {
+}
+export interface WicCompareOptions extends BaseImageCompareOptions {
+    /** Create a json file with the diff data, this can be used to create a custom report. */
+    createJsonReportFiles: boolean;
+    /** The proximity of the diff pixels to determine if a diff pixel is part of a group,
+     * the higher the number the more pixels will be grouped, the lower the number the less pixels will be grouped due to accuracy.
+     * Default is 5 pixels */
+    diffPixelBoundingBoxProximity: number;
+}
+//# sourceMappingURL=compare.interfaces.d.ts.map

package/dist/helpers/compare.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.interfaces.d.ts","sourceRoot":"","sources":["../../src/helpers/compare.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,yBAAyB,EAAE,MAAM,uBAAuB,CAAA;AAC/F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAE3E,MAAM,WAAW,kBAAmB,SAAQ,uBAAuB;IAC/D,QAAQ,CAAC,EAAE,gBAAgB,EAAE,CAAC;CACjC;AAED,MAAM,WAAW,oBAAqB,SAAQ,kBAAkB,EAAE,yBAAyB;CAC1F;AAED,MAAM,WAAW,iBAAkB,SAAQ,uBAAuB;IAC9D,yFAAyF;IACzF,qBAAqB,EAAE,OAAO,CAAC;IAC/B;;6BAEyB;IACzB,6BAA6B,EAAE,MAAM,CAAC;CACzC"}

package/dist/helpers/compare.interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/helpers/constants.d.ts

@@ -0,0 +1,108 @@
+import type { IosOffsets } from './constants.interfaces.js';
+import type { ResizeDimensions } from '../methods/images.interfaces.js';
+import type { TestContext } from 'src/methods/compareReport.interfaces.js';
+import type { DeviceRectangles } from '../methods/rectangles.interfaces.js';
+export declare const DEFAULT_COMPARE_OPTIONS: {
+    blockOutSideBar: boolean;
+    blockOutStatusBar: boolean;
+    blockOutToolBar: boolean;
+    createJsonReportFiles: boolean;
+    diffPixelBoundingBoxProximity: number;
+    ignoreAlpha: boolean;
+    ignoreAntialiasing: boolean;
+    ignoreColors: boolean;
+    ignoreLess: boolean;
+    ignoreNothing: boolean;
+    rawMisMatchPercentage: boolean;
+    returnAllCompareData: boolean;
+    saveAboveTolerance: number;
+    scaleImagesToSameSize: boolean;
+};
+export declare const DEFAULT_FORMAT_STRING = "{tag}-{browserName}-{width}x{height}-dpr-{dpr}";
+export declare const STORYBOOK_FORMAT_STRING = "{tag}-{logName}-{width}x{height}-dpr-{dpr}";
+export declare const FOLDERS: {
+    readonly ACTUAL: "actual";
+    readonly DIFF: "diff";
+    readonly TEMP_FULL_SCREEN: "tempFullScreen";
+    readonly DEFAULT: {
+        readonly BASE: "./__snapshots__/";
+        readonly SCREENSHOTS: ".tmp/";
+    };
+};
+export declare const DEFAULT_SHADOW: {
+    ADDRESS_BAR: number;
+    TOOL_BAR: number;
+};
+export declare const DESKTOP = "desktop";
+export declare const NOT_KNOWN = "not_known";
+export declare const CUSTOM_CSS_ID = "pic-css";
+export declare const DEFAULT_RESIZE_DIMENSIONS: Required<ResizeDimensions>;
+export declare const FULL_PAGE_SCROLL_TIMEOUT = 1500;
+export declare const DEFAULT_TABBABLE_OPTIONS: {
+    circle: {
+        backgroundColor: string;
+        borderColor: string;
+        borderWidth: number;
+        fontColor: string;
+        fontFamily: string;
+        fontSize: number;
+        size: number;
+        showNumber: boolean;
+    };
+    line: {
+        color: string;
+        width: number;
+    };
+};
+export declare const DEVICE_RECTANGLES: DeviceRectangles;
+export declare const ANDROID_OFFSETS: {
+    6: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+    7: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+    8: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+    9: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+    10: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+    11: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+    12: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+    13: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+    14: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+};
+export declare const IOS_OFFSETS: IosOffsets;
+export declare const supportedIosBezelDevices: string[];
+export declare const DEFAULT_TEST_CONTEXT: TestContext;
+//# sourceMappingURL=constants.d.ts.map

package/dist/helpers/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/helpers/constants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AACvE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAA;AAC1E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAE3E,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;CAenC,CAAA;AACD,eAAO,MAAM,qBAAqB,mDAAmD,CAAA;AACrF,eAAO,MAAM,uBAAuB,+CAA+C,CAAA;AACnF,eAAO,MAAM,OAAO;;;;;;;;CAQV,CAAA;AACV,eAAO,MAAM,cAAc;;;CAG1B,CAAA;AACD,eAAO,MAAM,OAAO,YAAY,CAAA;AAChC,eAAO,MAAM,SAAS,cAAc,CAAA;AACpC,eAAO,MAAM,aAAa,YAAY,CAAA;AACtC,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,gBAAgB,CAKhE,CAAA;AACD,eAAO,MAAM,wBAAwB,OAAO,CAAA;AAC5C,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;CAepC,CAAA;AACD,eAAO,MAAM,iBAAiB,EAAE,gBAS/B,CAAA;AAUD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAU3B,CAAA;AAsCD,eAAO,MAAM,WAAW,EAAE,UAuQzB,CAAA;AAED,eAAO,MAAM,wBAAwB,UA2BpC,CAAA;AAED,eAAO,MAAM,oBAAoB,EAAE,WAqBlC,CAAA"}

package/dist/helpers/constants.interfaces.d.ts

@@ -0,0 +1,30 @@
+import type { BaseRectangle } from '../base.interfaces.js';
+export interface AndroidOffsets {
+    [key: number]: {
+        STATUS_BAR: number;
+        ADDRESS_BAR: number;
+        TOOL_BAR: number;
+    };
+}
+declare enum IosDeviceEnum {
+    IPAD = "IPAD",
+    IPHONE = "IPHONE"
+}
+declare enum OrientationEnum {
+    LANDSCAPE = "LANDSCAPE",
+    PORTRAIT = "PORTRAIT"
+}
+export type IosOffsets = {
+    [key in IosDeviceEnum]: {
+        [key: number]: {
+            [key in OrientationEnum]: {
+                ADDRESS_BAR: number;
+                HOME_BAR: BaseRectangle;
+                SAFE_AREA: number;
+                STATUS_BAR: number;
+            };
+        };
+    };
+};
+export {};
+//# sourceMappingURL=constants.interfaces.d.ts.map

package/dist/helpers/constants.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.interfaces.d.ts","sourceRoot":"","sources":["../../src/helpers/constants.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D,MAAM,WAAW,cAAc;IAC3B,CAAC,GAAG,EAAE,MAAM,GAAG;QAEX,UAAU,EAAE,MAAM,CAAC;QAEnB,WAAW,EAAE,MAAM,CAAC;QAEpB,QAAQ,EAAE,MAAM,CAAC;KACpB,CAAC;CACL;AAED,aAAK,aAAa;IACd,IAAI,SAAS;IACb,MAAM,WAAW;CACpB;AAED,aAAK,eAAe;IAChB,SAAS,cAAc;IACvB,QAAQ,aAAa;CACxB;AAED,MAAM,MAAM,UAAU,GAAG;KACpB,GAAG,IAAI,aAAa,GAAG;QAEpB,CAAC,GAAG,EAAE,MAAM,GAAG;aACV,GAAG,IAAI,eAAe,GAAG;gBACtB,WAAW,EAAE,MAAM,CAAC;gBACpB,QAAQ,EAAE,aAAa,CAAC;gBACxB,SAAS,EAAE,MAAM,CAAC;gBAClB,UAAU,EAAE,MAAM,CAAC;aACtB;SACJ,CAAC;KACL;CACJ,CAAC"}

package/dist/helpers/constants.interfaces.js

@@ -0,0 +1,11 @@
+var IosDeviceEnum;
+(function (IosDeviceEnum) {
+    IosDeviceEnum["IPAD"] = "IPAD";
+    IosDeviceEnum["IPHONE"] = "IPHONE";
+})(IosDeviceEnum || (IosDeviceEnum = {}));
+var OrientationEnum;
+(function (OrientationEnum) {
+    OrientationEnum["LANDSCAPE"] = "LANDSCAPE";
+    OrientationEnum["PORTRAIT"] = "PORTRAIT";
+})(OrientationEnum || (OrientationEnum = {}));
+export {};