fix: add bidi screenshot support for webscreenshots (#917)

* fix: add bidi screenshot support for webscreenshots

* chore: add changeset

* chore: two fixes

- fix the bidi check
- fix fullpage bidi setting

* feat: add bidi support for element screenshots

* tesT: add UT's

* feat: add enableLegacyScreenshotMethod

- add bidi tests
- add new screenshots

* chore: add proper js doc for methods

* chore: update changeset

* test: fixed more stable tests on chrome

Author: wswebcreation

.changeset/neat-regions-smell.md

@@ -0,0 +1,82 @@
+---
+"webdriver-image-comparison": major
+"@wdio/visual-service": major
+---
+
+## 💥 BREAKING CHANGES
+
+### 🧪 Web Screenshot Strategy Now Uses BiDi by Default
+
+#### What was the problem?
+
+Screenshots taken via WebDriver's traditional protocol often lacked precision:
+
+* Emulated devices didn't reflect true resolutions
+* Device Pixel Ratio (DPR) was often lost
+* Images were cropped or downscaled
+
+#### What changed?
+
+All screenshot-related methods now use the **WebDriver BiDi protocol** by default (if supported by the browser), enabling:
+
+✅ Native support for emulated and high-DPR devices
+✅ Better fidelity in screenshot size and clarity
+✅ Faster, browser-native screenshots via [`browsingContext.captureScreenshot`](https://w3c.github.io/webdriver-bidi/#command-browsingContext-captureScreenshot)
+
+The following methods now use BiDi:
+
+* `saveScreen` / `checkScreen`
+* `saveElement` / `checkElement`
+* `saveFullPageScreen` / `checkFullPageScreen`
+
+#### What’s the impact?
+
+⚠️ **Existing baselines may no longer match.**
+Because BiDi screenshots are **sharper** and **match device settings more accurately**, even a small difference in resolution or DPR can cause mismatches.
+
+> If you rely on existing baseline images, you'll need to regenerate them to avoid false positives.
+
+#### Want to keep using the legacy method?
+
+You can disable BiDi screenshots globally or per test using the `enableLegacyScreenshotMethod` flag:
+
+**Globally in `wdio.conf.ts`:**
+
+```ts
+import { join } from 'node:path'
+
+export const config = {
+    services: [
+        [
+            'visual',
+            {
+                baselineFolder: join(process.cwd(), './localBaseline/'),
+                debug: true,
+                formatImageName: '{tag}-{logName}-{width}x{height}',
+                screenshotPath: join(process.cwd(), '.tmp/'),
+                enableLegacyScreenshotMethod: true // 👈 fallback to W3C-based screenshots
+            },
+        ]
+    ],
+}
+```
+
+**Or per test:**
+
+```ts
+it('should compare an element successfully using legacy screenshots', async function () {
+    await expect($('.hero__title-logo')).toMatchElementSnapshot(
+        'legacyScreenshotLogo',
+        { enableLegacyScreenshotMethod: true } // 👈 fallback to W3C-based screenshots
+    )
+})
+```
+
+## 🐛 Bug Fixes
+
+-  ✅ [#916](https://github.com/webdriverio/visual-testing/issues/916): Visual Testing Screenshot Behavior Changed in Emulated Devices
+
+
+## Committers: 1
+
+- Wim Selles ([@wswebcreation](https://github.com/wswebcreation))

packages/visual-service/src/service.ts

@@ -227,13 +227,15 @@ export default class WdioImageComparisonService extends BaseClass {
 
                         return [{
                             methods: {
+                                bidiScreenshot: isBiDiScreenshotSupported(browser) ? this.browsingContextCaptureScreenshot.bind(browser) : undefined,
                                 executor: <ReturnValue, InnerArguments extends unknown[]>(
                                     fn: string | ((...args: InnerArguments) => ReturnValue),
                                     ...args: InnerArguments
                                 ): Promise<ReturnValue> => {
                                     return this.execute(fn, ...args) as Promise<ReturnValue>
                                 },
                                 getElementRect: this.getElementRect.bind(this),
+                                getWindowHandle: this.getWindowHandle.bind(browser),
                                 screenShot: this.takeScreenshot.bind(this),
                                 takeElementScreenshot: this.takeElementScreenshot.bind(this),
                             },
@@ -471,13 +473,15 @@ export default class WdioImageComparisonService extends BaseClass {
 
                             return [{
                                 methods: {
+                                    bidiScreenshot: isBiDiScreenshotSupported(browserInstance) ? browserInstance.browsingContextCaptureScreenshot.bind(browserInstance) : undefined,
                                     executor: <ReturnValue, InnerArguments extends unknown[]>(
                                         fn: string | ((...args: InnerArguments) => ReturnValue),
                                         ...args: InnerArguments
                                     ): Promise<ReturnValue> => {
                                         return browserInstance.execute(fn, ...args) as Promise<ReturnValue>
                                     },
                                     getElementRect: browserInstance.getElementRect.bind(browserInstance),
+                                    getWindowHandle: browserInstance.getWindowHandle.bind(browserInstance),
                                     screenShot: browserInstance.takeScreenshot.bind(browserInstance),
                                 },
                                 instanceData: updatedInstanceData,

packages/webdriver-image-comparison/src/__snapshots__/base.test.ts.snap

@@ -26,6 +26,7 @@ exports[`BaseClass > initializes default options correctly 1`] = `
   "disableBlinkingCursor": false,
   "disableCSSAnimation": false,
   "enableLayoutTesting": false,
+  "enableLegacyScreenshotMethod": false,
   "formatImageName": "{tag}-{browserName}-{width}x{height}-dpr-{dpr}",
   "fullPageScrollTimeout": 1500,
   "hideScrollBars": true,

packages/webdriver-image-comparison/src/commands/check.interfaces.ts

@@ -7,33 +7,73 @@ import type { CheckScreenOptions } from './screen.interfaces.js'
 import type { CheckTabbableOptions } from './tabbable.interfaces.js'
 
 export interface CheckMethodOptions {
-    // Block out array with x, y, width and height values
+    /**
+     * Block out array with x, y, width and height values
+     */
     blockOut?: RectanglesOutput[];
-    // Block out the side bar on iOS iPads in landscape mode
+    /**
+     * Block out the side bar on iOS iPads in landscape mode
+     * @default false
+     */
     blockOutSideBar?: boolean;
-    // Block out the status bar yes or no
+    /**
+     * Block out the status bar yes or no
+     * @default false
+     */
     blockOutStatusBar?: boolean;
-    // Block out the tool bar yes or no
+    /**
+     * Block out the tool bar yes or no
+     * @default false
+     */
     blockOutToolBar?: boolean;
-    // Ignore elements and or areas
+    /**
+     * Ignore elements and or areas
+     */
     ignore?: (RectanglesOutput | WebdriverIO.Element | ChainablePromiseElement)[];
-    // Compare images and discard alpha
+    /**
+     * Compare images and discard alpha
+     * @default false
+     */
     ignoreAlpha?: boolean;
-    // Compare images an discard anti aliasing
+    /**
+     * Compare images an discard anti aliasing
+     * @default false
+     */
     ignoreAntialiasing?: boolean;
-    // Even though the images are in color, the comparison wil compare 2 black/white images
+    /**
+     * Even though the images are in color, the comparison wil compare 2 black/white images
+     * @default false
+     */
     ignoreColors?: boolean;
-    // Compare images and compare with red = 16, green = 16, blue = 16, alpha = 16, minBrightness=16, maxBrightness=240
+    /**
+     * Compare images and compare with red = 16, green = 16, blue = 16, alpha = 16, minBrightness=16, maxBrightness=240
+     * @default false
+     */
     ignoreLess?: boolean;
-    // Compare images and compare with red = 0, green = 0, blue = 0, alpha = 0, minBrightness=0, maxBrightness=255
+    /**
+     * Compare images and compare with red = 0, green = 0, blue = 0, alpha = 0, minBrightness=0, maxBrightness=255
+     * @default false
+     */
     ignoreNothing?: boolean;
-    // Default false. If true, return percentage will be like 0.12345678, default is 0.12
+    /**
+     * Default false. If true, return percentage will be like 0.12345678, default is 0.12
+     * @default false
+     */
     rawMisMatchPercentage?: boolean;
-    // Return all the compare data object
+    /**
+     * Return all the compare data object
+     * @default false
+     */
     returnAllCompareData?: boolean;
-    // Allowable value of misMatchPercentage that prevents saving image with
+    /**
+     * Allowable value of misMatchPercentage that prevents saving image with differences
+     * @default 0
+     */
     saveAboveTolerance?: number;
-    //Scale images to same size before comparison
+    /**
+     * Scale images to same size before comparison
+     * @default false
+     */
     scaleImagesToSameSize?: boolean;
 }
 

packages/webdriver-image-comparison/src/commands/checkFullPageScreen.ts

@@ -32,6 +32,7 @@ export default async function checkFullPageScreen(
             disableBlinkingCursor: checkFullPageOptions.method.disableBlinkingCursor,
             disableCSSAnimation: checkFullPageOptions.method.disableCSSAnimation,
             enableLayoutTesting: checkFullPageOptions.method.enableLayoutTesting,
+            enableLegacyScreenshotMethod: checkFullPageOptions.method.enableLegacyScreenshotMethod,
             fullPageScrollTimeout: checkFullPageOptions.method.fullPageScrollTimeout,
             hideAfterFirstScroll: checkFullPageOptions.method.hideAfterFirstScroll || [],
             hideScrollBars: checkFullPageOptions.method.hideScrollBars,

packages/webdriver-image-comparison/src/commands/checkWebElement.ts

@@ -28,6 +28,7 @@ export default async function checkWebElement(
             disableBlinkingCursor: checkElementOptions.method.disableBlinkingCursor,
             disableCSSAnimation: checkElementOptions.method.disableCSSAnimation,
             enableLayoutTesting: checkElementOptions.method.enableLayoutTesting,
+            enableLegacyScreenshotMethod: checkElementOptions.method.enableLegacyScreenshotMethod,
             hideScrollBars: checkElementOptions.method.hideScrollBars,
             resizeDimensions: checkElementOptions.method.resizeDimensions,
             hideElements: checkElementOptions.method.hideElements || [],

packages/webdriver-image-comparison/src/commands/checkWebScreen.ts

@@ -27,6 +27,7 @@ export default async function checkWebScreen(
             disableBlinkingCursor: checkScreenOptions.method.disableBlinkingCursor,
             disableCSSAnimation: checkScreenOptions.method.disableCSSAnimation,
             enableLayoutTesting: checkScreenOptions.method.enableLayoutTesting,
+            enableLegacyScreenshotMethod: checkScreenOptions.method.enableLegacyScreenshotMethod,
             hideScrollBars: checkScreenOptions.method.hideScrollBars,
             hideElements: checkScreenOptions.method.hideElements || [],
             removeElements: checkScreenOptions.method.removeElements || [],

packages/webdriver-image-comparison/src/commands/element.interfaces.ts

@@ -10,25 +10,61 @@ export interface SaveElementOptions {
 }
 
 export interface SaveElementMethodOptions extends Partial<Folders> {
-    // The padding that needs to be added to the address bar on iOS and Android
+    /**
+     * The padding that needs to be added to the address bar on iOS and Android
+     * @default 6
+     */
     addressBarShadowPadding?: number;
-    // Disable the blinking cursor
+    /**
+     * Disable the blinking cursor
+     * @default false
+     */
     disableBlinkingCursor?: boolean;
-    // Disable all css animations
+    /**
+     * Disable all css animations
+     * @default false
+     */
     disableCSSAnimation?: boolean;
-    // Make all text on a page transparent to only focus on the layout
+    /**
+     * Make all text on a page transparent to only focus on the layout
+     * @default false
+     */
     enableLayoutTesting?: boolean;
-    // Hide all scrollbars
+    /**
+     * By default the screenshots are taken with the BiDi protocol if Bidi is available.
+     * If you want to use the legacy method, set this to true.
+     * @default false
+     */
+    enableLegacyScreenshotMethod?: boolean;
+    /**
+     * Hide all scrollbars
+     * @default true
+     */
     hideScrollBars?: boolean;
-    // The resizeDimensions
+    /**
+     * The resizeDimensions
+     * @default { top: 0, left: 0, width: 0, height: 0 }
+     */
     resizeDimensions?: ResizeDimensions;
-    // The padding that needs to be added to the tool bar on iOS and Android
+    /**
+     * The padding that needs to be added to the tool bar on iOS and Android
+     * @default 6
+     */
     toolBarShadowPadding?: number;
-    // Elements that need to be hidden (visibility: hidden) before saving a screenshot
+    /**
+     * Elements that need to be hidden (visibility: hidden) before saving a screenshot
+     * @default []
+     */
     hideElements?: HTMLElement[];
-    // Elements that need to be removed (display: none) before saving a screenshot
+    /**
+     * Elements that need to be removed (display: none) before saving a screenshot
+     * @default []
+     */
     removeElements?: HTMLElement[];
-    // Wait for the fonts to be loaded
+    /**
+     * Wait for the fonts to be loaded
+     * @default true
+     */
     waitForFontsLoaded?: boolean;
 }
 

packages/webdriver-image-comparison/src/commands/fullPage.interfaces.ts

@@ -9,31 +9,77 @@ export interface SaveFullPageOptions {
 }
 
 export interface SaveFullPageMethodOptions extends Partial<Folders> {
-    // The padding that needs to be added to the address bar on iOS and Android
+    /**
+     * The padding that needs to be added to the address bar on iOS and Android
+     * @default 6
+     */
     addressBarShadowPadding?: number;
-    // Create fullpage screenshots with the bidi protocol
+    /**
+     * Create fullpage screenshots with the "legacy" protocol which used scrolling and stitching
+     * @default false
+     */
     userBasedFullPageScreenshot?: boolean;
-    // Disable the blinking cursor
+    /**
+     * Disable the blinking cursor
+     * @default false
+     */
     disableBlinkingCursor?: boolean;
-    // Disable all css animations
+    /**
+     * Disable all css animations
+     * @default false
+     */
     disableCSSAnimation?: boolean;
-    // Make all text on a page transparent to only focus on the layout
+    /**
+     * Make all text on a page transparent to only focus on the layout
+     * @default false
+     */
     enableLayoutTesting?: boolean;
-    // Hide all scrollbars
+    /**
+     * By default the screenshots are taken with the BiDi protocol if Bidi is available.
+     * If you want to use the legacy method, set this to true.
+     * @default false
+     */
+    enableLegacyScreenshotMethod?: boolean;
+    /**
+     * Hide all scrollbars
+     * @default true
+     */
     hideScrollBars?: boolean;
-    // The amount of milliseconds to wait for a new scroll
+    /**
+     * The amount of milliseconds to wait for a new scroll. This will be used for the legacy
+     * fullpage screenshot method.
+     * @default 1500
+     */
     fullPageScrollTimeout?: number;
-    // The resizeDimensions
+    /**
+     * The resizeDimensions
+     * @default { top: 0, left: 0, width: 0, height: 0 }
+     */
     resizeDimensions?: ResizeDimensions;
-    // The padding that needs to be added to the tool bar on iOS and Android
+    /**
+     * The padding that needs to be added to the tool bar on iOS and Android
+     * @default 6
+     */
     toolBarShadowPadding?: number;
-    // Elements that need to be hidden (visibility: hidden) before saving a screenshot
+    /**
+     * Elements that need to be hidden (visibility: hidden) before saving a screenshot
+     * @default []
+     */
     hideElements?: HTMLElement[];
-    // Elements that need to be removed (display: none) before saving a screenshot
+    /**
+     * Elements that need to be removed (display: none) before saving a screenshot
+     * @default []
+     */
     removeElements?: HTMLElement[];
-    // Elements that need to be hidden after the first scroll for a fullpage scroll
+    /**
+     * Elements that need to be hidden after the first scroll for a fullpage scroll
+     * @default []
+     */
     hideAfterFirstScroll?: HTMLElement[];
-    // Wait for the fonts to be loaded
+    /**
+     * Wait for the fonts to be loaded
+     * @default true
+     */
     waitForFontsLoaded?: boolean;
 }