@cloudscape-design/browser-test-tools 3.0.135 → 3.0.136

package/image-utils/compare.d.ts

@@ -1,5 +1,6 @@
 import { PNG } from 'pngjs';
-import { ElementSize, ScreenshotWithOffset } from '../page-objects/types';
+import { ElementSize, RawScreenshot, ScreenshotWithOffset } from '../page-objects/types';
+type Screenshot = ScreenshotWithOffset | RawScreenshot;
 export declare function compareImages(firstImage: PNG, secondImage: PNG, { width, height }: ElementSize): {
     diffPixels: number;
     diffImage: null;
@@ -14,4 +15,5 @@ export interface CropAndCompareResult {
     isEqual: boolean;
     diffPixels: number;
 }
-export declare function cropAndCompare(firstScreenshot: ScreenshotWithOffset, secondScreenshot: ScreenshotWithOffset): Promise<CropAndCompareResult>;
+export declare function cropAndCompare(firstScreenshot: Screenshot, secondScreenshot: Screenshot): Promise<CropAndCompareResult>;
+export {};

package/image-utils/compare.js

@@ -29,37 +29,50 @@ function normalizeSize(firstScreenshot, secondScreenshot) {
         width: Math.round(Math.max(firstScreenshot.width, secondScreenshot.width)),
     };
 }
+function isScreenshotWithOffset(s) {
+    return 'offset' in s && s.offset !== undefined;
+}
 function scaleSize(size, pixelRatio) {
     return {
         width: Math.ceil(size.width * pixelRatio),
         height: Math.ceil(size.height * pixelRatio),
     };
 }
+async function getDecodedImage(screenshot) {
+    if (isScreenshotWithOffset(screenshot)) {
+        return screenshot.image;
+    }
+    return (0, utils_1.parsePng)(screenshot.rawBase64);
+}
+async function cropIfNeeded(screenshot, size) {
+    const image = await getDecodedImage(screenshot);
+    if (isScreenshotWithOffset(screenshot)) {
+        return (0, utils_1.cropImage)(image, buildCropRect(screenshot, size), screenshot.pixelRatio);
+    }
+    else {
+        return image;
+    }
+}
 async function cropAndCompare(firstScreenshot, secondScreenshot) {
+    // Fast path: if rawBase64 is present on both, identical, and no cropping needed, skip all decoding entirely.
+    if (!isScreenshotWithOffset(firstScreenshot) &&
+        !isScreenshotWithOffset(secondScreenshot) &&
+        firstScreenshot.rawBase64 === secondScreenshot.rawBase64) {
+        const buffer = Buffer.from(firstScreenshot.rawBase64, 'base64');
+        return { firstImage: buffer, secondImage: buffer, diffImage: null, isEqual: true, diffPixels: 0 };
+    }
     const pixelRatio = firstScreenshot.pixelRatio || 1;
     const size = normalizeSize(firstScreenshot, secondScreenshot);
-    const firstImageCropRect = {
-        height: size.height,
-        width: size.width,
-        bottom: firstScreenshot.offset.top + size.height,
-        right: firstScreenshot.offset.left + size.width,
-        top: firstScreenshot.offset.top,
-        left: firstScreenshot.offset.left,
-    };
-    const secondImageCropRect = {
-        height: size.height,
-        width: size.width,
-        bottom: secondScreenshot.offset.top + size.height,
-        right: secondScreenshot.offset.left + size.width,
-        top: secondScreenshot.offset.top,
-        left: secondScreenshot.offset.left,
-    };
-    const firstImage = (0, utils_1.cropImage)(firstScreenshot.image, firstImageCropRect, pixelRatio);
-    const secondImage = (0, utils_1.cropImage)(secondScreenshot.image, secondImageCropRect, pixelRatio);
-    const { diffImage, diffPixels } = compareImages(firstImage, secondImage, scaleSize(size, pixelRatio));
+    const scaledSize = scaleSize(size, pixelRatio);
+    const firstImage = await cropIfNeeded(firstScreenshot, size);
+    const secondImage = await cropIfNeeded(secondScreenshot, size);
+    const { diffImage, diffPixels } = compareImages(firstImage, secondImage, scaledSize);
+    // Skip packPng when no cropping was needed and rawBase64 is available
     const [firstPacked, secondPacked, diffPacked] = await Promise.all([
-        (0, utils_1.packPng)(firstImage),
-        (0, utils_1.packPng)(secondImage),
+        !isScreenshotWithOffset(firstScreenshot) ? Buffer.from(firstScreenshot.rawBase64, 'base64') : (0, utils_1.packPng)(firstImage),
+        !isScreenshotWithOffset(secondScreenshot)
+            ? Buffer.from(secondScreenshot.rawBase64, 'base64')
+            : (0, utils_1.packPng)(secondImage),
         diffImage && (0, utils_1.packPng)(diffImage),
     ]);
     return {
@@ -70,3 +83,16 @@ async function cropAndCompare(firstScreenshot, secondScreenshot) {
         diffPixels,
     };
 }
+function buildCropRect(screenshot, size) {
+    var _a, _b, _c, _d;
+    const top = (_b = (_a = screenshot.offset) === null || _a === void 0 ? void 0 : _a.top) !== null && _b !== void 0 ? _b : 0;
+    const left = (_d = (_c = screenshot.offset) === null || _c === void 0 ? void 0 : _c.left) !== null && _d !== void 0 ? _d : 0;
+    return {
+        height: size.height,
+        width: size.width,
+        bottom: top + size.height,
+        right: left + size.width,
+        top,
+        left,
+    };
+}

package/internal/manifest.json

@@ -1,3 +1,3 @@
 {
-  "commit": "bead6a8bf3fe674ef2dc8e17050fff1a046529ec"
+  "commit": "e9d80de15a044bf7259bbc3f8f4219a89fdf6b78"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudscape-design/browser-test-tools",
-  "version": "3.0.135",
+  "version": "3.0.136",
   "repository": {
     "type": "git",
     "url": "https://github.com/cloudscape-design/browser-test-tools.git"

package/page-objects/index.d.ts

@@ -1,4 +1,6 @@
 export { default as BasePageObject } from './base';
+export { default as ScreenshotBasePageObject } from './screenshot-base';
 export { default as ScreenshotPageObject, PermutationScreenshot } from './screenshot';
+export { default as RawScreenshotPageObject, RawPermutationScreenshot } from './raw-screenshot';
 export { default as EventsSpy } from './events-spy';
-export { ScreenshotWithOffset, ElementSize, ElementRect, ElementOffset } from './types';
+export { ScreenshotWithOffset, RawScreenshot, ElementSize, ElementRect, ElementOffset } from './types';

package/page-objects/index.js

@@ -3,12 +3,16 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EventsSpy = exports.ScreenshotPageObject = exports.BasePageObject = void 0;
+exports.EventsSpy = exports.RawScreenshotPageObject = exports.ScreenshotPageObject = exports.ScreenshotBasePageObject = exports.BasePageObject = void 0;
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 var base_1 = require("./base");
 Object.defineProperty(exports, "BasePageObject", { enumerable: true, get: function () { return __importDefault(base_1).default; } });
+var screenshot_base_1 = require("./screenshot-base");
+Object.defineProperty(exports, "ScreenshotBasePageObject", { enumerable: true, get: function () { return __importDefault(screenshot_base_1).default; } });
 var screenshot_1 = require("./screenshot");
 Object.defineProperty(exports, "ScreenshotPageObject", { enumerable: true, get: function () { return __importDefault(screenshot_1).default; } });
+var raw_screenshot_1 = require("./raw-screenshot");
+Object.defineProperty(exports, "RawScreenshotPageObject", { enumerable: true, get: function () { return __importDefault(raw_screenshot_1).default; } });
 var events_spy_1 = require("./events-spy");
 Object.defineProperty(exports, "EventsSpy", { enumerable: true, get: function () { return __importDefault(events_spy_1).default; } });

package/page-objects/raw-screenshot.d.ts

@@ -0,0 +1,19 @@
+import ScreenshotBasePageObject from './screenshot-base';
+import { RawScreenshot } from './types';
+/**
+ * Raw permutation screenshot captured via takeElementScreenshot.
+ * No decoded image, no offset — just the raw base64 PNG per element.
+ */
+export interface RawPermutationScreenshot extends RawScreenshot {
+    id: string;
+}
+/**
+ * A page object that captures screenshots using takeElementScreenshot.
+ * Returns raw base64 PNGs without decoding, cropping, or re-encoding —
+ * significantly faster when pixel-level comparison can be done on raw bytes.
+ */
+export default class RawScreenshotPageObject extends ScreenshotBasePageObject {
+    captureBySelector(selector: string): Promise<RawScreenshot>;
+    captureViewport(): Promise<RawScreenshot>;
+    capturePermutations(): Promise<RawPermutationScreenshot[]>;
+}

package/page-objects/raw-screenshot.js

@@ -0,0 +1,56 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+const screenshot_base_1 = __importDefault(require("./screenshot-base"));
+/**
+ * A page object that captures screenshots using takeElementScreenshot.
+ * Returns raw base64 PNGs without decoding, cropping, or re-encoding —
+ * significantly faster when pixel-level comparison can be done on raw bytes.
+ */
+class RawScreenshotPageObject extends screenshot_base_1.default {
+    async captureBySelector(selector) {
+        await this.waitForVisible(selector);
+        const { pixelRatio } = await this.getViewportSize();
+        const box = await this.getBoundingBox(selector);
+        const originalWindowSize = await this.fitWindowHeightToContent();
+        const element = this.browser.$(selector);
+        const rawBase64 = await this.browser.takeElementScreenshot(await element.elementId);
+        await this.safeSetWindowSize(originalWindowSize.width, originalWindowSize.height);
+        return { rawBase64, pixelRatio, height: box.height, width: box.width };
+    }
+    async captureViewport() {
+        const { height, width } = await this.getViewportSize();
+        const rawBase64 = await this.browser.takeScreenshot();
+        return { rawBase64, height, width };
+    }
+    async capturePermutations() {
+        await this.windowScrollTo({ top: 0, left: 0 });
+        // Adapt viewport height to fit all elements before taking screenshots
+        const originalWindowSize = await this.fitWindowHeightToContent();
+        const elements = await this.browser.$$('[data-permutation]').map(el => el);
+        if (elements.length === 0) {
+            await this.safeSetWindowSize(originalWindowSize.width, originalWindowSize.height);
+            throw new Error('No permutations found on current page.');
+        }
+        const { pixelRatio } = await this.getViewportSize();
+        const results = [];
+        for (const element of elements) {
+            const id = (await element.getAttribute('data-permutation')) || '';
+            const rawBase64 = await this.browser.takeElementScreenshot(await element.elementId);
+            const size = await element.getSize();
+            results.push({
+                id,
+                rawBase64,
+                width: size.width * pixelRatio,
+                height: size.height * pixelRatio,
+            });
+        }
+        await this.safeSetWindowSize(originalWindowSize.width, originalWindowSize.height);
+        return results;
+    }
+}
+exports.default = RawScreenshotPageObject;

package/page-objects/screenshot-base.d.ts

@@ -0,0 +1,18 @@
+import BasePageObject from './base';
+/**
+ * Base class for screenshot page objects. Provides scroll helpers,
+ * full-page screenshot support, and window size management.
+ */
+export default class ScreenshotBasePageObject extends BasePageObject {
+    readonly forceScrollAndMerge: boolean;
+    constructor(browser: WebdriverIO.Browser, forceScrollAndMerge?: boolean);
+    focusNextElement(): Promise<void>;
+    scrollToBottom(selector: string): Promise<void>;
+    scrollToRight(selector: string): Promise<void>;
+    fullPageScreenshot(): Promise<string>;
+    protected fitWindowHeightToContent(): Promise<{
+        width: number;
+        height: number;
+    }>;
+    protected safeSetWindowSize(width: number, height: number): Promise<void>;
+}

package/page-objects/screenshot-base.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+const browser_scripts_1 = require("../browser-scripts");
+const base_1 = __importDefault(require("./base"));
+const full_page_screenshot_1 = __importDefault(require("./full-page-screenshot"));
+/**
+ * Base class for screenshot page objects. Provides scroll helpers,
+ * full-page screenshot support, and window size management.
+ */
+class ScreenshotBasePageObject extends base_1.default {
+    constructor(browser, forceScrollAndMerge = false) {
+        super(browser);
+        this.forceScrollAndMerge = forceScrollAndMerge;
+    }
+    async focusNextElement() {
+        return this.keys('Tab');
+    }
+    async scrollToBottom(selector) {
+        const action = 'scrollToBottom';
+        await this.browser.execute(browser_scripts_1.scrollAction, { action, selector });
+    }
+    async scrollToRight(selector) {
+        const action = 'scrollToRight';
+        await this.browser.execute(browser_scripts_1.scrollAction, { action, selector });
+    }
+    async fullPageScreenshot() {
+        // preserve scroll position in order to avoid side effects after screenshot taking
+        const scrollPosition = await this.getWindowScroll();
+        // Wait for the page to settle before taking a screenshot
+        await this.waitForJsTimers();
+        const screenshot = await (0, full_page_screenshot_1.default)(this.browser, this.forceScrollAndMerge);
+        // restore scroll position
+        await this.windowScrollTo(scrollPosition);
+        return screenshot;
+    }
+    async fitWindowHeightToContent() {
+        const originalWindowSize = await this.browser.getWindowSize();
+        const { viewportHeight, pageHeight } = await this.browser.execute(browser_scripts_1.getPageDimensions);
+        const windowUIHeight = originalWindowSize.height - viewportHeight;
+        await this.safeSetWindowSize(originalWindowSize.width, pageHeight + windowUIHeight);
+        return originalWindowSize;
+    }
+    /* istanbul ignore next -- setWindowSize is unsupported on some mobile browsers, not testable in CI */
+    async safeSetWindowSize(width, height) {
+        try {
+            await this.browser.setWindowSize(width, height);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes('Method has not yet been implemented')) {
+                console.log('setWindowSize is not supported on this device');
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+}
+exports.default = ScreenshotBasePageObject;

package/page-objects/screenshot.d.ts

@@ -1,18 +1,10 @@
-import BasePageObject from './base';
 import { ScreenshotCapturingOptions, ScreenshotWithOffset } from './types';
+import ScreenshotBasePageObject from './screenshot-base';
 export interface PermutationScreenshot extends ScreenshotWithOffset {
     id: string;
 }
-export default class ScreenshotPageObject extends BasePageObject {
-    readonly forceScrollAndMerge: boolean;
-    constructor(browser: WebdriverIO.Browser, forceScrollAndMerge?: boolean);
-    focusNextElement(): Promise<void>;
-    scrollToBottom(selector: string): Promise<void>;
-    scrollToRight(selector: string): Promise<void>;
-    fullPageScreenshot(): Promise<string>;
+export default class ScreenshotPageObject extends ScreenshotBasePageObject {
     captureBySelector(selector: string, options?: ScreenshotCapturingOptions): Promise<ScreenshotWithOffset>;
     captureViewport(): Promise<ScreenshotWithOffset>;
     capturePermutations(): Promise<PermutationScreenshot[]>;
-    private fitWindowHeightToContent;
-    private safeSetWindowSize;
 }

package/page-objects/screenshot.js

@@ -7,34 +7,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 // SPDX-License-Identifier: Apache-2.0
 const browser_scripts_1 = require("../browser-scripts");
 const image_utils_1 = require("../image-utils");
-const base_1 = __importDefault(require("./base"));
-const full_page_screenshot_1 = __importDefault(require("./full-page-screenshot"));
-class ScreenshotPageObject extends base_1.default {
-    constructor(browser, forceScrollAndMerge = false) {
-        super(browser);
-        this.forceScrollAndMerge = forceScrollAndMerge;
-    }
-    async focusNextElement() {
-        return this.keys('Tab');
-    }
-    async scrollToBottom(selector) {
-        const action = 'scrollToBottom';
-        await this.browser.execute(browser_scripts_1.scrollAction, { action, selector });
-    }
-    async scrollToRight(selector) {
-        const action = 'scrollToRight';
-        await this.browser.execute(browser_scripts_1.scrollAction, { action, selector });
-    }
-    async fullPageScreenshot() {
-        // preserve scroll position in order to avoid side effects after screenshot taking
-        const scrollPosition = await this.getWindowScroll();
-        // Wait for the page to settle before taking a screenshot
-        await this.waitForJsTimers();
-        const screenshot = await (0, full_page_screenshot_1.default)(this.browser, this.forceScrollAndMerge);
-        // restore scroll position
-        await this.windowScrollTo(scrollPosition);
-        return screenshot;
-    }
+const screenshot_base_1 = __importDefault(require("./screenshot-base"));
+class ScreenshotPageObject extends screenshot_base_1.default {
     async captureBySelector(selector, options = {}) {
         await this.waitForVisible(selector);
         const { pixelRatio, top, left } = await this.getViewportSize();
@@ -73,26 +47,5 @@ class ScreenshotPageObject extends base_1.default {
         }
         return permutations.map((permutation) => ({ ...permutation, image }));
     }
-    async fitWindowHeightToContent() {
-        const originalWindowSize = await this.browser.getWindowSize();
-        const { viewportHeight, pageHeight } = await this.browser.execute(browser_scripts_1.getPageDimensions);
-        const windowUIHeight = originalWindowSize.height - viewportHeight;
-        await this.safeSetWindowSize(originalWindowSize.width, pageHeight + windowUIHeight);
-        return originalWindowSize;
-    }
-    /* istanbul ignore next -- setWindowSize is unsupported on some mobile browsers, not testable in CI */
-    async safeSetWindowSize(width, height) {
-        try {
-            await this.browser.setWindowSize(width, height);
-        }
-        catch (error) {
-            if (error instanceof Error && error.message.includes('Method has not yet been implemented')) {
-                console.log('setWindowSize is not supported on this device');
-            }
-            else {
-                throw error;
-            }
-        }
-    }
 }
 exports.default = ScreenshotPageObject;

package/page-objects/types.d.ts

@@ -24,4 +24,14 @@ export interface ScreenshotWithOffset extends ElementSize {
     image: PNG;
     offset: ElementOffset;
     pixelRatio?: number;
+    /** Optional raw base64 PNG for fast byte-equality comparison. */
+    rawBase64?: string;
+}
+/**
+ * A raw screenshot with base64 data and dimensions. No decoded image, no offset.
+ * Returned by RawScreenshotPageObject which uses takeElementScreenshot.
+ */
+export interface RawScreenshot extends ElementSize {
+    rawBase64: string;
+    pixelRatio?: number;
 }