@wdio/image-comparison-core 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @wdio/image-comparison-core
 
+## 1.2.3
+
+### Patch Changes
+
+- c56e1ae: ## #1146 Fix BiDi element screenshots missing composited layers (scrollbars, fixed/sticky overlays)
+
+  ### Root cause
+
+  When `checkElement` / `saveElement` is used with the WebDriver BiDi protocol, the screenshot was taken with `browsingContext.captureScreenshot` using `origin: 'document'`. This renders the document layout independently of the browser's compositor, which means **composited layers are never included** — element-level scrollbars, `position: fixed` / `position: sticky` overlays, and elements with a `will-change` CSS property all render as invisible or without their correct visual state.
+
+  The switch to `origin: 'document'` was introduced in an earlier fix (commit `227f10a`) to avoid a `zero dimensions` error that occurred when `origin: 'viewport'` was used for elements that were outside the visible viewport. That fix was correct for out-of-viewport elements, but it also silently broke composited-layer capture for all elements.
+
+  ### Fix: new `biDiOrigin` method option
+
+  A new **method-level** option `biDiOrigin` has been added to `saveElement` / `checkElement`. It is BiDi-only and ignored for the legacy WebDriver screenshot path.
+
+  | Value                    | Behaviour                                                                                                                                                                                                                    |
+  | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+  | `'document'` _(default)_ | Previous behaviour — works for any element position but composited layers (scrollbars, overlays, `will-change`) are not captured                                                                                             |
+  | `'viewport'`             | Captures the composited frame as the browser painted it — scrollbars, fixed/sticky overlays and `will-change` layers are included. The element must be visible in the viewport; descriptive errors are thrown when it is not |
+
+  #### Usage
+
+  ```ts
+  // Capture an element with its scrollbar / overlay visible:
+  await browser.checkElement(element, "myTag", { biDiOrigin: "viewport" });
+  await browser.saveElement(element, "myTag", { biDiOrigin: "viewport" });
+  ```
+
+  #### Error messages when `biDiOrigin: 'viewport'` cannot produce a valid screenshot
+
+  **Element larger than the viewport** — must fall back to `'document'`:
+
+  ```
+  [BiDi viewport screenshot] The element dimensions (1400x800px) exceed the viewport (1280x720px).
+  You must use the default `biDiOrigin: 'document'` for this element.
+  Note: with `'document'` origin, composited layers such as scrollbars, fixed/sticky overlays,
+  and elements using `will-change` may not appear in the screenshot.
+  ```
+
+  **Element not in the viewport at all** — needs scrolling:
+
+  ```
+  [BiDi viewport screenshot] The element is not in the viewport
+  (element: x=0, y=900, 300x200px; viewport: 1280x720px).
+  Call `element.scrollIntoView()` before taking the screenshot, or set `autoElementScroll: true`.
+  ```
+
+  **Element partially outside the viewport but fits** — needs to be scrolled fully into view:
+
+  ```
+  [BiDi viewport screenshot] The element is not fully visible in the viewport
+  (element: x=-20, y=100, 300x200px; viewport: 1280x720px).
+  The element fits within the viewport — scroll it fully into view by calling
+  `element.scrollIntoView()` or setting `autoElementScroll: true`.
+  ```
+
+  ### Committers: 1
+
+  - Wim Selles ([@wswebcreation](https://github.com/wswebcreation))
+
 ## 1.2.2
 
 ### Patch Changes

package/dist/commands/checkWebElement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkWebElement.d.ts","sourceRoot":"","sources":["../../src/commands/checkWebElement.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AAIzE,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAA;AAE9E;;GAEG;AACH,wBAA8B,eAAe,CACzC,EACI,eAAe,EACf,YAAY,EACZ,OAAO,EACP,OAAO,EACP,GAAG,EACH,mBAAmB,EACnB,WAAW,EACX,eAAuB,GAC1B,EAAE,iCAAiC,GACrC,OAAO,CAAC,kBAAkB,GAAG,MAAM,CAAC,CAgEtC"}
+{"version":3,"file":"checkWebElement.d.ts","sourceRoot":"","sources":["../../src/commands/checkWebElement.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAA;AAIzE,OAAO,KAAK,EAAE,iCAAiC,EAAE,MAAM,uBAAuB,CAAA;AAE9E;;GAEG;AACH,wBAA8B,eAAe,CACzC,EACI,eAAe,EACf,YAAY,EACZ,OAAO,EACP,OAAO,EACP,GAAG,EACH,mBAAmB,EACnB,WAAW,EACX,eAAuB,GAC1B,EAAE,iCAAiC,GACrC,OAAO,CAAC,kBAAkB,GAAG,MAAM,CAAC,CAkEtC"}

package/dist/commands/checkWebElement.js

@@ -8,11 +8,12 @@ import { extractCommonCheckVariables, buildBaseExecuteCompareOptions } from '../
 export default async function checkWebElement({ browserInstance, instanceData, folders, element, tag, checkElementOptions, testContext, isNativeContext = false, }) {
     // 1. Extract common variables
     const commonCheckVariables = extractCommonCheckVariables({ folders, instanceData, wicOptions: checkElementOptions.wic });
-    const { disableBlinkingCursor, disableCSSAnimation, enableLayoutTesting, enableLegacyScreenshotMethod, hideScrollBars, resizeDimensions, ignoreRegionPadding, hideElements = [], removeElements = [], waitForFontsLoaded = false, } = checkElementOptions.method;
+    const { biDiOrigin, disableBlinkingCursor, disableCSSAnimation, enableLayoutTesting, enableLegacyScreenshotMethod, hideScrollBars, resizeDimensions, ignoreRegionPadding, hideElements = [], removeElements = [], waitForFontsLoaded = false, } = checkElementOptions.method;
     // 2. Take the actual element screenshot and retrieve the needed data
     const saveElementOptions = {
         wic: checkElementOptions.wic,
         method: {
+            biDiOrigin,
             disableBlinkingCursor,
             disableCSSAnimation,
             enableLayoutTesting,

package/dist/commands/element.interfaces.d.ts

@@ -14,6 +14,16 @@ export interface SaveElementMethodOptions extends Partial<Folders>, BaseWebScree
      * @default undefined
      */
     resizeDimensions?: ResizeDimensions;
+    /**
+     * BiDi-only: which coordinate origin to use when capturing element screenshots via the BiDi protocol.
+     * - `'document'` (default): renders the document layout, works for any element position but
+     *   does NOT capture composited layers (scrollbars, fixed/sticky overlays, `will-change` elements).
+     * - `'viewport'`: captures the composited frame as painted, which includes scrollbars and overlays,
+     *   but requires the element to be fully visible in the viewport. Throws a descriptive error when the
+     *   element is outside, partially outside, or larger than the viewport.
+     * @default 'document'
+     */
+    biDiOrigin?: 'document' | 'viewport';
 }
 export interface CheckElementMethodOptions extends SaveElementMethodOptions, CheckMethodOptions {
 }

package/dist/commands/element.interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"element.interfaces.d.ts","sourceRoot":"","sources":["../../src/commands/element.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,KAAK,EAAE,8BAA8B,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAC9G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAE3E,MAAM,WAAW,kBAAkB;IAC/B,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,wBAAwB,CAAC;CACpC;AAED,MAAM,WAAW,wBAAyB,SAAQ,OAAO,CAAC,OAAO,CAAC,EAAE,wBAAwB,EAAE,8BAA8B;IACxH;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;CACvC;AAED,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB,EAAE,kBAAkB;CAAI;AAEnG,MAAM,WAAW,mBAAmB;IAChC,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,yBAAyB,CAAC;CACrC;AAED,sBAAsB;AACtB,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,GAAG,uBAAuB,CAAA;AAEtE,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,UAAU,CAAA"}
+{"version":3,"file":"element.interfaces.d.ts","sourceRoot":"","sources":["../../src/commands/element.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAC1D,OAAO,KAAK,EAAE,8BAA8B,EAAE,wBAAwB,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AAC9G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAA;AACtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AACvE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC/D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAE3E,MAAM,WAAW,kBAAkB;IAC/B,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,wBAAwB,CAAC;CACpC;AAED,MAAM,WAAW,wBAAyB,SAAQ,OAAO,CAAC,OAAO,CAAC,EAAE,wBAAwB,EAAE,8BAA8B;IACxH;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;CACxC;AAED,MAAM,WAAW,yBAA0B,SAAQ,wBAAwB,EAAE,kBAAkB;CAAI;AAEnG,MAAM,WAAW,mBAAmB;IAChC,GAAG,EAAE,cAAc,CAAC;IACpB,MAAM,EAAE,yBAAyB,CAAC;CACrC;AAED,sBAAsB;AACtB,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,OAAO,GAAG,uBAAuB,CAAA;AAEtE,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,UAAU,CAAA"}

package/dist/commands/saveWebElement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"saveWebElement.d.ts","sourceRoot":"","sources":["../../src/commands/saveWebElement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAA;AAOhF,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAA;AAG5E;;GAEG;AACH,wBAA8B,cAAc,CACxC,EACI,eAAe,EACf,YAAY,EACZ,OAAO,EACP,OAAO,EACP,GAAG,EACH,MAAM,EACN,kBAAkB,GACrB,EAAE,gCAAgC,GACpC,OAAO,CAAC,gBAAgB,CAAC,CA0F3B"}
+{"version":3,"file":"saveWebElement.d.ts","sourceRoot":"","sources":["../../src/commands/saveWebElement.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAA;AAOhF,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,sBAAsB,CAAA;AAG5E;;GAEG;AACH,wBAA8B,cAAc,CACxC,EACI,eAAe,EACf,YAAY,EACZ,OAAO,EACP,OAAO,EACP,GAAG,EACH,MAAM,EACN,kBAAkB,GACrB,EAAE,gCAAgC,GACpC,OAAO,CAAC,gBAAgB,CAAC,CA8F3B"}

package/dist/commands/saveWebElement.js

@@ -16,11 +16,13 @@ export default async function saveWebElement({ browserInstance, instanceData, fo
     // 2.  Prepare the screenshot
     const beforeOptions = createBeforeScreenshotOptions(instanceData, saveElementOptions.method, saveElementOptions.wic);
     const enrichedInstanceData = await beforeScreenshot(browserInstance, beforeOptions, true);
-    const { deviceName, dimensions: { window: { devicePixelRatio, innerHeight, isEmulated, isLandscape, }, }, initialDevicePixelRatio, isAndroid, isAndroidChromeDriverScreenshot, isAndroidNativeWebScreenshot, isIOS, isMobile, } = enrichedInstanceData;
+    const { deviceName, dimensions: { window: { devicePixelRatio, innerHeight, innerWidth, isEmulated, isLandscape, }, }, initialDevicePixelRatio, isAndroid, isAndroidChromeDriverScreenshot, isAndroidNativeWebScreenshot, isIOS, isMobile, } = enrichedInstanceData;
     // 3. Take the screenshot
+    const biDiOrigin = saveElementOptions.method.biDiOrigin ?? 'document';
     const elementScreenshotOptions = {
         addressBarShadowPadding,
         autoElementScroll,
+        biDiOrigin,
         deviceName,
         devicePixelRatio: devicePixelRatio || 1,
         deviceRectangles: instanceData.deviceRectangles,
@@ -28,6 +30,7 @@ export default async function saveWebElement({ browserInstance, instanceData, fo
         isEmulated,
         initialDevicePixelRatio: initialDevicePixelRatio || 1,
         innerHeight,
+        innerWidth,
         isAndroidNativeWebScreenshot,
         isAndroidChromeDriverScreenshot,
         isAndroid,

package/dist/methods/screenshots.interfaces.d.ts

@@ -192,10 +192,14 @@ export interface WebScreenshotDataOptions extends ScreenshotInfo, MobileDeviceIn
 export interface ElementScreenshotDataOptions extends ScreenshotInfo, MobileDeviceInfo, AndroidScreenshotOptions, MobileCroppingOptions {
     /** Whether to automatically scroll the element into view. */
     autoElementScroll: boolean;
+    /** BiDi-only: coordinate origin for element screenshots ('document' | 'viewport'). */
+    biDiOrigin?: 'document' | 'viewport';
     /** The element to take a screenshot of. */
     element: HTMLElement | WebdriverIO.Element | ChainablePromiseElement;
-    /** The inner height. */
+    /** The inner height of the viewport. */
     innerHeight?: number;
+    /** The inner width of the viewport. */
+    innerWidth?: number;
     /** Resize dimensions for the screenshot. */
     resizeDimensions: any;
 }

package/dist/methods/screenshots.interfaces.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"screenshots.interfaces.d.ts","sourceRoot":"","sources":["../../src/methods/screenshots.interfaces.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"screenshots.interfaces.d.ts","sourceRoot":"","sources":["../../src/methods/screenshots.interfaces.ts"],"names":[],"mappings":"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"}

package/dist/methods/takeElementScreenshots.js

@@ -12,11 +12,12 @@ export async function takeElementScreenshot(browserInstance, options, shouldUseB
     return await takeWebDriverElementScreenshot(browserInstance, options);
 }
 async function takeBiDiElementScreenshot(browserInstance, options) {
-    const isWebDriverElementScreenshot = false;
     // Fix #1129: scrollElementIntoView receives a promise
-    // The element might be a promise, so we need to resolve it before using it as a browser.execute() argument
-    // if we need to use it in browser.execute()
     const element = await options.element;
+    if (options.biDiOrigin === 'viewport') {
+        return takeBiDiElementScreenshotFromViewport(browserInstance, element, options);
+    }
+    // Default: origin: 'document' path.
     // Scroll the element into the viewport so any lazy‑load / intersection
     // observers are triggered. We always capture from the *document* origin,
     // so the clip coordinates are document‑relative and independent of scroll.
@@ -35,13 +36,63 @@ async function takeBiDiElementScreenshot(browserInstance, options) {
         origin: 'document',
         clip,
     });
-    // Restore scroll position
     if (options.autoElementScroll && currentPosition) {
         await browserInstance.execute(scrollToPosition, currentPosition);
     }
     return {
         base64Image,
-        isWebDriverElementScreenshot,
+        isWebDriverElementScreenshot: false,
+    };
+}
+async function takeBiDiElementScreenshotFromViewport(browserInstance, element, options) {
+    // Scroll element into view first so getElementRect reflects its viewport position.
+    let currentPosition;
+    if (options.autoElementScroll) {
+        currentPosition = await browserInstance.execute(scrollElementIntoView, element, options.addressBarShadowPadding);
+        await waitFor(100);
+    }
+    // getElementRect returns viewport-relative coordinates per W3C BiDi spec.
+    const rect = await browserInstance.getElementRect(element.elementId);
+    const elX = Math.floor(rect.x);
+    const elY = Math.floor(rect.y);
+    const elW = Math.floor(rect.width);
+    const elH = Math.floor(rect.height);
+    const vpW = options.innerWidth ?? 0;
+    const vpH = options.innerHeight ?? 0;
+    // Case 1: element larger than viewport, can never be fully captured with 'viewport' origin.
+    if (elW > vpW || elH > vpH) {
+        throw new Error(`[BiDi viewport screenshot] The element dimensions (${elW}x${elH}px) exceed the viewport ` +
+            `(${vpW}x${vpH}px). You must use the default \`biDiOrigin: 'document'\` for this element. ` +
+            'Note: with `\'document\'` origin, composited layers such as scrollbars, fixed/sticky overlays, ' +
+            'and elements using `will-change` may not appear in the screenshot.');
+    }
+    // Case 2: element has no overlap with the viewport at all.
+    const isOutsideViewport = elX + elW <= 0 || elX >= vpW || elY + elH <= 0 || elY >= vpH;
+    if (isOutsideViewport) {
+        throw new Error('[BiDi viewport screenshot] The element is not in the viewport ' +
+            `(element: x=${elX}, y=${elY}, ${elW}x${elH}px; viewport: ${vpW}x${vpH}px). ` +
+            'Call `element.scrollIntoView()` before taking the screenshot, or set `autoElementScroll: true`.');
+    }
+    // Case 3: element is partially outside the viewport but fits, suggest scrolling it fully into view.
+    const isPartiallyOutside = elX < 0 || elX + elW > vpW || elY < 0 || elY + elH > vpH;
+    if (isPartiallyOutside) {
+        throw new Error('[BiDi viewport screenshot] The element is not fully visible in the viewport ' +
+            `(element: x=${elX}, y=${elY}, ${elW}x${elH}px; viewport: ${vpW}x${vpH}px). ` +
+            'The element fits within the viewport, scroll it fully into view by calling ' +
+            '`element.scrollIntoView()` or setting `autoElementScroll: true`.');
+    }
+    const clip = { x: elX, y: elY, width: elW, height: elH };
+    const base64Image = await takeBase64BiDiScreenshot({
+        browserInstance,
+        origin: 'viewport',
+        clip,
+    });
+    if (options.autoElementScroll && currentPosition) {
+        await browserInstance.execute(scrollToPosition, currentPosition);
+    }
+    return {
+        base64Image,
+        isWebDriverElementScreenshot: false,
     };
 }
 async function takeWebDriverElementScreenshot(browserInstance, options) {

package/dist/methods/takeElementScreenshots.test.js

@@ -129,6 +129,72 @@ describe('takeElementScreenshot', () => {
             expect(executeMock.mock.calls[0][1]).toEqual(resolvedElement);
         });
     });
+    describe('BiDi viewport screenshots', () => {
+        const vpOptions = {
+            ...baseOptions,
+            biDiOrigin: 'viewport',
+            innerWidth: 1280,
+            innerHeight: 720,
+        };
+        it('should take viewport screenshot when element is fully inside the viewport', async () => {
+            // element at (10, 20, 100x200) — fits in 1280x720 viewport
+            const result = await takeElementScreenshot(browserInstance, vpOptions, true);
+            expect(result).toEqual({
+                base64Image: 'bidi-screenshot-data',
+                isWebDriverElementScreenshot: false,
+            });
+            expect(takeBase64BiDiScreenshotSpy).toHaveBeenCalledWith({
+                browserInstance,
+                origin: 'viewport',
+                clip: { x: 10, y: 20, width: 100, height: 200 },
+            });
+        });
+        it('should throw when element dimensions exceed the viewport', async () => {
+            getElementRectMock.mockResolvedValueOnce({ x: 0, y: 0, width: 1400, height: 800 });
+            const err = await takeElementScreenshot(browserInstance, vpOptions, true).catch(e => e);
+            expect(err.message).toMatch(/element dimensions \(1400x800px\) exceed the viewport \(1280x720px\)/);
+            expect(err.message).toMatch(/biDiOrigin: 'document'/);
+            expect(err.message).toMatch(/composited layers/);
+        });
+        it('should throw when element is completely outside the viewport', async () => {
+            // element below the fold
+            getElementRectMock.mockResolvedValueOnce({ x: 0, y: 800, width: 100, height: 200 });
+            const err = await takeElementScreenshot(browserInstance, vpOptions, true).catch(e => e);
+            expect(err.message).toMatch(/element is not in the viewport/);
+            expect(err.message).toMatch(/scrollIntoView/);
+            expect(err.message).toMatch(/autoElementScroll: true/);
+        });
+        it('should throw when element is partially outside the viewport but fits', async () => {
+            // element starts at x=-10, so it bleeds left of the viewport
+            getElementRectMock.mockResolvedValueOnce({ x: -10, y: 0, width: 100, height: 200 });
+            const err = await takeElementScreenshot(browserInstance, vpOptions, true).catch(e => e);
+            expect(err.message).toMatch(/not fully visible in the viewport/);
+            expect(err.message).toMatch(/fits within the viewport/);
+            expect(err.message).toMatch(/autoElementScroll: true/);
+        });
+        it('should include element and viewport dimensions in the error messages', async () => {
+            getElementRectMock.mockResolvedValueOnce({ x: 0, y: 900, width: 200, height: 100 });
+            const err = await takeElementScreenshot(browserInstance, vpOptions, true).catch(e => e);
+            expect(err.message).toMatch(/x=0, y=900, 200x100px/);
+            expect(err.message).toMatch(/viewport: 1280x720px/);
+        });
+        it('should scroll element into view before validating when autoElementScroll is true', async () => {
+            const vpScrollOptions = { ...vpOptions, autoElementScroll: true };
+            // After scroll, element is fully in viewport
+            executeMock.mockResolvedValueOnce(300); // previous scroll position
+            const result = await takeElementScreenshot(browserInstance, vpScrollOptions, true);
+            expect(result.base64Image).toBe('bidi-screenshot-data');
+            // scrollElementIntoView + scrollToPosition (restore)
+            expect(executeMock).toHaveBeenCalledTimes(2);
+            expect(takeBase64BiDiScreenshotSpy).toHaveBeenCalledWith(expect.objectContaining({ origin: 'viewport' }));
+        });
+        it('should use origin: document for the default (no biDiOrigin set)', async () => {
+            const defaultOptions = { ...vpOptions, biDiOrigin: undefined };
+            const result = await takeElementScreenshot(browserInstance, defaultOptions, true);
+            expect(result.base64Image).toBe('bidi-screenshot-data');
+            expect(takeBase64BiDiScreenshotSpy).toHaveBeenCalledWith(expect.objectContaining({ origin: 'document' }));
+        });
+    });
     describe('Legacy screenshots', () => {
         let logErrorSpy;
         beforeEach(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wdio/image-comparison-core",
-  "version": "1.2.2",
+  "version": "1.2.3",
   "author": "Wim Selles - wswebcreation",
   "description": "Image comparison core module for @wdio/visual-service - WebdriverIO visual testing framework",
   "keywords": [