fix(image-comparison-core): use device platformVersion for Android hybrid status bar fallback

 - Use the device's platform version to select the correct offsets entry for the hybrid-app status bar

Author: wswebcreation

.changeset/implement-web-ignore-regions.md

@@ -9,12 +9,13 @@ Add `ignore` support to all web screenshot methods (`saveScreen`/`checkScreen`,
 
 ### Changes
 
-- **Ignore regions for full-page screenshots** — new `determineWebFullPageIgnoreRegions` function that calculates ignore-region rectangles for full-page screenshots, including a `fullPageCropTopPaddingCSS` correction for mobile scroll-and-stitch scenarios where the address-bar shadow padding shifts element positions
-- **Consolidated `ignoreRegionPadding`** — moved `ignoreRegionPadding` into `BaseWebScreenshotOptions` so it is inherited by all web methods instead of being duplicated per method
-- **Fix `isAndroidNativeWebScreenshot` type** — ensure `nativeWebScreenshot` is always a boolean (was accidentally an object for LambdaTest capabilities), preventing ignore-region DPR scaling failures
-- **Fix viewport rounding for mobile** — restore `Math.round()` in `injectWebviewOverlay` and remove `Math.min` clamping in `getMobileViewPortPosition` to prevent 1-pixel crop shifts during full-page stitching
-- **Fix `scrollElementIntoView` for scrolled pages** — account for `currentPosition` (existing scroll offset) when computing the target scroll position, so elements are scrolled into view correctly when the page is already scrolled
-- **Dismiss Chrome Start Surface on Android** — when Chrome's tab-overview UI blocks the webview overlay, automatically press the Android Back button (up to 4 retries) to restore the active tab before measuring the viewport
+- **Ignore regions for full-page screenshots:** new `determineWebFullPageIgnoreRegions` function that calculates ignore-region rectangles for full-page screenshots, including a `fullPageCropTopPaddingCSS` correction for mobile scroll-and-stitch scenarios where the address-bar shadow padding shifts element positions
+- **Consolidated `ignoreRegionPadding`:** moved `ignoreRegionPadding` into `BaseWebScreenshotOptions` so it is inherited by all web methods instead of being duplicated per method
+- **Fix `isAndroidNativeWebScreenshot` type:** ensure `nativeWebScreenshot` is always a boolean (was accidentally an object for LambdaTest capabilities), preventing ignore-region DPR scaling failures
+- **Fix viewport rounding for mobile:** restore `Math.round()` in `injectWebviewOverlay` and remove `Math.min` clamping in `getMobileViewPortPosition` to prevent 1-pixel crop shifts during full-page stitching
+- **Fix `scrollElementIntoView` for scrolled pages:** account for `currentPosition` (existing scroll offset) when computing the target scroll position, so elements are scrolled into view correctly when the page is already scrolled
+- **Dismiss Chrome Start Surface on Android:** when Chrome's tab-overview UI blocks the webview overlay, automatically press the Android Back button (up to 4 retries) to restore the active tab before measuring the viewport
+- **Add hybrid status bar blockout:** on hybrid apps the statusbar was not blocked out which could result in flaky tests regarding battery and reception
 
 # Committers: 1
 

packages/image-comparison-core/src/helpers/utils.interfaces.ts

@@ -169,6 +169,7 @@ export interface CommonCheckVariables {
 
     /** Optional instance data (not all methods need these) */
     platformName?: string;
+    platformVersion?: string;
     isIOS?: boolean;
 
     /** WIC options */
@@ -235,6 +236,8 @@ export interface BaseExecuteCompareOptions {
     isAndroidNativeWebScreenshot: boolean;
     /** Optional: platform name */
     platformName?: string;
+    /** Optional: platform version (e.g. "14.0" for Android API 14, "17.0" for iOS) */
+    platformVersion?: string;
     /** Optional: whether this is iOS */
     isIOS?: boolean;
     /** Optional: whether this is hybrid app */

packages/image-comparison-core/src/helpers/utils.ts

@@ -696,6 +696,7 @@ export function extractCommonCheckVariables(
 
         // Optional instance data
         ...(instanceData.platformName && { platformName: instanceData.platformName }),
+        ...(instanceData.platformVersion && { platformVersion: instanceData.platformVersion }),
         ...(instanceData.isIOS !== undefined && { isIOS: instanceData.isIOS }),
 
         // WIC options
@@ -766,6 +767,7 @@ export function buildBaseExecuteCompareOptions(
         isAndroidNativeWebScreenshot: commonCheckVariables.isAndroidNativeWebScreenshot,
         // Add optional properties from commonCheckVariables if they exist
         ...(commonCheckVariables.platformName && { platformName: commonCheckVariables.platformName }),
+        ...(commonCheckVariables.platformVersion && { platformVersion: commonCheckVariables.platformVersion }),
         ...(commonCheckVariables.isIOS !== undefined && { isIOS: commonCheckVariables.isIOS }),
         ...(commonCheckVariables.isHybridApp !== undefined && { isHybridApp: commonCheckVariables.isHybridApp }),
     }

packages/image-comparison-core/src/methods/images.interfaces.ts

@@ -47,6 +47,10 @@ export interface ImageCompareOptions {
     isAndroid: boolean;
     /** If this is a native web screenshot */
     isAndroidNativeWebScreenshot: boolean;
+    /** If this is a hybrid (native + webview) app; enables status bar fallback in webview when overlay reports zero */
+    isHybridApp?: boolean;
+    /** Platform version from the device (e.g. "14.0" for Android API 14); used for Android status bar fallback lookup */
+    platformVersion?: string;
 }
 
 export interface WicImageCompareOptions extends BaseImageCompareOptions, BaseMobileBlockOutOptions {

packages/image-comparison-core/src/methods/images.ts

@@ -434,6 +434,8 @@ export async function executeImageCompare(
             blockOutStatusBar: imageCompareOptions.blockOutStatusBar,
             blockOutToolBar: imageCompareOptions.blockOutToolBar,
         },
+        isHybridApp: options.isHybridApp,
+        platformVersion: options.platformVersion,
         actualFilePath: isViewPortScreenshot ? undefined : actualFilePath,
     })
 

packages/image-comparison-core/src/methods/rectangles.interfaces.ts

@@ -128,6 +128,10 @@ export interface PrepareIgnoreRectanglesOptions {
         blockOutStatusBar?: boolean;
         blockOutToolBar?: boolean;
     };
+    /** Whether this is a hybrid (native + webview) app; enables status bar fallback when overlay reports zero */
+    isHybridApp?: boolean;
+    /** Platform version from the device (e.g. "14.0"); used for Android API level lookup in fallback */
+    platformVersion?: string;
     actualFilePath?: string;
 }
 

packages/image-comparison-core/src/methods/rectangles.test.ts

@@ -1550,5 +1550,146 @@ describe('rectangles', () => {
                 bottom: 70,
             })
         })
+
+        it('should add hybrid-app status bar fallback when statusBarAndAddressBar height is 0 (iOS)', async () => {
+            const deviceRectangles = createDeviceRectanglesWithData({
+                screenSize: { width: 375, height: 812 },
+                statusBarAndAddressBar: { x: 0, y: 0, width: 375, height: 0 },
+                bottomBar: { y: 0, x: 0, width: 0, height: 0 },
+            })
+            const options = createPrepareIgnoreRectanglesOptions({
+                deviceRectangles,
+                isMobile: true,
+                isNativeContext: false,
+                isAndroid: false,
+                isAndroidNativeWebScreenshot: true,
+                isViewPortScreenshot: true,
+                devicePixelRatio: 3,
+                imageCompareOptions: {
+                    blockOutStatusBar: true,
+                },
+            })
+
+            const result = await prepareIgnoreRectangles(options)
+
+            expect(result.hasIgnoreRectangles).toBe(true)
+            const statusBarBox = result.ignoredBoxes.find(
+                (b: { top: number }) => b.top === 0
+            ) as { left: number; top: number; right: number; bottom: number }
+            expect(statusBarBox).toBeDefined()
+            expect(statusBarBox.left).toBe(0)
+            expect(statusBarBox.top).toBe(0)
+            expect(statusBarBox.right).toBe(1125)
+            expect(statusBarBox.bottom).toBe(132)
+        })
+
+        it('should add hybrid-app status bar fallback when isHybridApp is true (iOS)', async () => {
+            const deviceRectangles = createDeviceRectanglesWithData({
+                screenSize: { width: 390, height: 844 },
+                statusBarAndAddressBar: { x: 0, y: 0, width: 390, height: 47 },
+            })
+            const options = createPrepareIgnoreRectanglesOptions({
+                deviceRectangles,
+                isMobile: true,
+                isNativeContext: false,
+                isAndroid: false,
+                isAndroidNativeWebScreenshot: true,
+                isViewPortScreenshot: true,
+                devicePixelRatio: 2,
+                isHybridApp: true,
+                imageCompareOptions: {
+                    blockOutStatusBar: true,
+                },
+            })
+
+            const result = await prepareIgnoreRectangles(options)
+
+            expect(result.hasIgnoreRectangles).toBe(true)
+            const statusBarBoxes = result.ignoredBoxes.filter(
+                (b: { top: number }) => b.top === 0
+            ) as Array<{ left: number; top: number; right: number; bottom: number }>
+            expect(statusBarBoxes.length).toBeGreaterThanOrEqual(1)
+        })
+
+        it('should add hybrid-app status bar fallback for Android when overlay reports zero', async () => {
+            const deviceRectangles = createDeviceRectanglesWithData({
+                screenSize: { width: 412, height: 869 },
+                statusBarAndAddressBar: { x: 0, y: 0, width: 412, height: 0 },
+                bottomBar: { y: 0, x: 0, width: 0, height: 0 },
+            })
+            const options = createPrepareIgnoreRectanglesOptions({
+                deviceRectangles,
+                isMobile: true,
+                isNativeContext: false,
+                isAndroid: true,
+                isAndroidNativeWebScreenshot: true,
+                isViewPortScreenshot: true,
+                devicePixelRatio: 2,
+                imageCompareOptions: {
+                    blockOutStatusBar: true,
+                },
+            })
+
+            const result = await prepareIgnoreRectangles(options)
+
+            expect(result.hasIgnoreRectangles).toBe(true)
+            const statusBarBox = result.ignoredBoxes.find(
+                (b: { top: number }) => b.top === 0
+            ) as { left: number; top: number; right: number; bottom: number }
+            expect(statusBarBox).toBeDefined()
+            expect(statusBarBox.bottom).toBe(24)
+        })
+
+        it('should use device platformVersion for Android hybrid status bar fallback when in ANDROID_OFFSETS list', async () => {
+            const deviceRectangles = createDeviceRectanglesWithData({
+                screenSize: { width: 412, height: 869 },
+                statusBarAndAddressBar: { x: 0, y: 0, width: 412, height: 0 },
+            })
+            const options = createPrepareIgnoreRectanglesOptions({
+                deviceRectangles,
+                isMobile: true,
+                isNativeContext: false,
+                isAndroid: true,
+                isViewPortScreenshot: true,
+                devicePixelRatio: 2,
+                imageCompareOptions: { blockOutStatusBar: true },
+                platformVersion: '12',
+            })
+
+            const result = await prepareIgnoreRectangles(options)
+
+            expect(result.hasIgnoreRectangles).toBe(true)
+            const statusBarBox = result.ignoredBoxes.find(
+                (b: { top: number }) => b.top === 0
+            ) as { left: number; top: number; right: number; bottom: number }
+            expect(statusBarBox).toBeDefined()
+            expect(statusBarBox.bottom).toBe(24)
+        })
+
+        it('should fall back to latest API level for Android when platformVersion not in ANDROID_OFFSETS', async () => {
+            const deviceRectangles = createDeviceRectanglesWithData({
+                screenSize: { width: 412, height: 869 },
+                statusBarAndAddressBar: { x: 0, y: 0, width: 412, height: 0 },
+            })
+            const options = createPrepareIgnoreRectanglesOptions({
+                deviceRectangles,
+                isMobile: true,
+                isNativeContext: false,
+                isAndroid: true,
+                isViewPortScreenshot: true,
+                devicePixelRatio: 2,
+                imageCompareOptions: { blockOutStatusBar: true },
+                platformVersion: '99',
+            })
+
+            const result = await prepareIgnoreRectangles(options)
+
+            expect(result.hasIgnoreRectangles).toBe(true)
+            const statusBarBox = result.ignoredBoxes.find(
+                (b: { top: number }) => b.top === 0
+            ) as { left: number; top: number; right: number; bottom: number }
+            expect(statusBarBox).toBeDefined()
+            expect(statusBarBox.bottom).toBe(24)
+        })
     })
 })

packages/image-comparison-core/src/methods/rectangles.ts

@@ -1,4 +1,5 @@
 import { Jimp } from 'jimp'
+import { ANDROID_OFFSETS, IOS_OFFSETS } from '../helpers/constants.js'
 import { calculateDprData, getBase64ScreenshotSize, isObject } from '../helpers/utils.js'
 import { getElementPositionAndroid, getElementPositionDesktop, getElementWebviewPosition } from './elementPosition.js'
 import type {
@@ -561,6 +562,59 @@ export async function determineDeviceBlockOuts({ isAndroid, screenCompareOptions
     return rectangles
 }
 
+/**
+ * Return a status bar rectangle for hybrid-app fallback when the overlay reports zero height.
+ * Uses IOS_OFFSETS / ANDROID_OFFSETS so the system status bar is blocked out in webview context.
+ * Android: uses device platformVersion (e.g. "14.0") as API level when present and in list; otherwise latest.
+ * iOS: keyed by screen size only (no OS version in data). When device not in list, uses latest entry.
+ */
+function getHybridAppStatusBarFallback(
+    deviceRectangles: DeviceRectangles,
+    isAndroid: boolean,
+    platformVersion?: string,
+): RectanglesOutput | null {
+    const { width: screenWidth, height: screenHeight } = deviceRectangles.screenSize
+    if (screenWidth === 0 || screenHeight === 0) {
+        return null
+    }
+
+    if (isAndroid) {
+        const apiLevels = Object.keys(ANDROID_OFFSETS).map(Number)
+        const latestApiLevel = apiLevels.length > 0 ? Math.max(...apiLevels) : 14
+        const deviceApiLevel = platformVersion !== undefined ? parseInt(platformVersion, 10) : NaN
+        const useApiLevel =
+            Number.isInteger(deviceApiLevel) && apiLevels.includes(deviceApiLevel)
+                ? deviceApiLevel
+                : latestApiLevel
+        const statusBarHeight = ANDROID_OFFSETS[useApiLevel as keyof typeof ANDROID_OFFSETS]?.STATUS_BAR ?? 24
+        return {
+            x: 0,
+            y: 0,
+            width: screenWidth,
+            height: statusBarHeight,
+        }
+    }
+
+    const isIphone = screenWidth < 1024 && screenHeight < 1024
+    const deviceType = isIphone ? 'IPHONE' : 'IPAD'
+    const portraitHeight = screenWidth > screenHeight ? screenWidth : screenHeight
+    const keys = Object.keys(IOS_OFFSETS[deviceType]).map(Number)
+    const exactMatch = keys.includes(portraitHeight)
+    const offsetPortraitHeight = exactMatch
+        ? portraitHeight
+        : (keys.length > 0 ? Math.max(...keys) : (isIphone ? 667 : 1024))
+    const orientation = screenWidth > screenHeight ? 'LANDSCAPE' : 'PORTRAIT'
+    const currentOffsets = IOS_OFFSETS[deviceType][offsetPortraitHeight]?.[orientation]
+    const statusBarHeight = currentOffsets?.STATUS_BAR ?? (isIphone ? 44 : 20)
+
+    return {
+        x: 0,
+        y: 0,
+        width: screenWidth,
+        height: statusBarHeight,
+    }
+}
+
 /**
  * Prepare all ignore rectangles for image comparison
  */
@@ -576,6 +630,8 @@ export async function prepareIgnoreRectangles(options: PrepareIgnoreRectanglesOp
         isAndroidNativeWebScreenshot,
         isViewPortScreenshot,
         imageCompareOptions,
+        isHybridApp,
+        platformVersion,
         actualFilePath
     } = options
 
@@ -598,6 +654,18 @@ export async function prepareIgnoreRectangles(options: PrepareIgnoreRectanglesOp
             ...(determineStatusAddressToolBarRectangles({ deviceRectangles, options: statusAddressToolBarOptions })) || []
         )
 
+        // Hybrid-app fallback: in webview the overlay often reports statusBarAndAddressBar height 0.
+        // Use native offsets (IOS_OFFSETS / ANDROID_OFFSETS) so the system status bar is still blocked out.
+        const needStatusBarFallback =
+            imageCompareOptions.blockOutStatusBar !== false &&
+            (isHybridApp === true || deviceRectangles.statusBarAndAddressBar.height === 0)
+        if (needStatusBarFallback) {
+            const fallback = getHybridAppStatusBarFallback(deviceRectangles, isAndroid, platformVersion)
+            if (fallback && fallback.height > 0) {
+                webStatusAddressToolBarOptions.push(fallback)
+            }
+        }
+
         if (webStatusAddressToolBarOptions.length > 0) {
             // There's an issue with the resemble lib when all the rectangles are 0,0,0,0, it will see this as a full
             // blockout of the image and the comparison will succeed with 0 % difference.