@wdio/image-comparison-core 1.2.1 → 1.2.3

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # @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
+
+- db33fa7: #### `@wdio/image-comparison-core` and `@wdio/ocr-service` Security: update jimp (CVE in `file-type` transitive dep)
+
+  Bumped `jimp` to the latest version to resolve a reported vulnerability in its `file-type` transitive dependency (see [#1130](https://github.com/webdriverio/visual-testing/issues/1130), raised by [@denis-sokolov](https://github.com/denis-sokolov), thank you!).
+
+  **Actual impact on these packages**
+  `file-type` is used by `@jimp/core` solely to detect image MIME types when reading a buffer. In both `@wdio/image-comparison-core` and `@wdio/ocr-service`, every image passed to jimp originates from either WebDriver screenshots (browser-controlled base64 data) or local files written by the framework itself. There is no code path where untrusted external input is fed directly into jimp, which removes the exploitability that the CVE describes.
+
+  That said, the reputational and compliance risk was real, security scanners flag the package as vulnerable, enterprise users hit audit failures, and some organisations block installation of packages with known CVEs. The update addresses all of that.
+
+  #### `@wdio/visual-reporter` and `@wdio/visual-service`
+
+  Updated internal dependencies to pick up the jimp bump in `@wdio/image-comparison-core`.
+
+  ### Committers: 1
+
+  - Wim Selles ([@wswebcreation](https://github.com/wswebcreation))
+
 ## 1.2.1
 
 ### 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.1",
+  "version": "1.2.3",
   "author": "Wim Selles - wswebcreation",
   "description": "Image comparison core module for @wdio/visual-service - WebdriverIO visual testing framework",
   "keywords": [
@@ -26,12 +26,12 @@
     "url": "https://github.com/webdriverio/visual-testing/issues"
   },
   "dependencies": {
-    "jimp": "^1.6.0",
+    "jimp": "^1.6.1",
     "@wdio/logger": "^9.18.0",
-    "@wdio/types": "^9.25.0"
+    "@wdio/types": "^9.27.0"
   },
   "devDependencies": {
-    "webdriverio": "^9.25.0"
+    "webdriverio": "^9.27.0"
   },
   "publishConfig": {
     "access": "public"