flexysnap 0.2.4-alpha.1 → 0.2.6

package/README.md

@@ -44,6 +44,7 @@ const elementGroups = [
 ```
 
 - `strictPosition: false` — compare element size only, not exact position.
+- `strictSize: false` — for position-tolerant groups, compare size by ratio rather than absolute pixel difference.
 - `maskDigits: true` — replace digit runs with a placeholder before comparing text.
 - `textIgnoreClasses` — skip text found inside elements carrying these class names, at any ancestor level.
 
@@ -95,6 +96,7 @@ test('product page wireframe', async ({ page }) => {
   "timestamp": "2024-01-01T00:00:00.000Z",
   "scrollPosition": { "x": 0, "y": 0 },
   "screenshotScrollPosition": { "x": 0, "y": 0 },
+  "deviceScaleFactor": 1,
   "elementGroups": [
     {
       "selector": ".product-title",
@@ -127,11 +129,14 @@ Anything passed as `options.metadata` is merged into the top level of this objec
 ### Test utilities
 
 - `waitForCompleteLoad(page)` — wait for `domcontentloaded`, `load`, and a settle delay.
+- `gotoWithRetry(page, url)` — navigate to a URL, retrying once on failure, then wait for the page to finish loading.
 - `click(page, locator)` — resilient click that closes popups, re-hovers, scrolls into view, and retries.
 - `highlightedClick(page, locator)` — scroll a locator into the viewport and force-click it.
 - `hover(page, locator)` — hover a locator and remember it for re-hovering.
 - `rehover(page)` — re-hover the last hovered locator.
 - `fill(page, field, value)` — click and fill an input by name or locator.
+- `selectOption(page, field, value)` — click and select an option by name or locator.
+- `scrollToTopOfElement(page, target, offset?)` — scroll so a locator (or selector string) is positioned near the top of the viewport, minus an optional offset in pixels.
 - `setClosePopups(fn)` — register a function used to dismiss popups before interactions.
 - `setBaseUrl(url)` — set the base URL used for request cache-busting.
 - `logTimestamp(eventName)` — log an event with elapsed time since test start.
@@ -142,20 +147,22 @@ Anything passed as `options.metadata` is merged into the top level of this objec
   - `options.retryDelay` (default `1000`) — minimum milliseconds between stability samples.
   - `options.maxRetryCount` (default `10`) — maximum number of extraction attempts.
   - `options.metadata` (default `{}`) — extra fields merged into the written JSON.
+  - `options.closePopups` (default no-op) — function called before each element group extraction to dismiss popups.
 - `getRGBHistogramFromBuffer(buffer)` — compute a 48-bin RGB histogram (16 bins per channel, values normalized to percentages) from an image buffer.
 
 ### Wireframe comparison
 
-- `compareWireframes(baselineWireframe, currentWireframe)` — diff two wireframes and annotate the current one with `differences`.
-- `compareElements(baselineElement, currentElement, strictPosition?, maskDigits?)`
-- `compareTexts(baselineTexts, currentTexts, strictPosition?, maskDigits?)`
-- `compareBoundingBoxes(baselineRect, currentRect, tolerance?, strictPosition?)`
-- `createPairings(currentElements, baselineElements)` — nearest bounding-box matching between two element sets, returning `{ matchedPairs, unmatchedCurrent, unmatchedBaseline }`.
-- `histogramDiff(a, b)` — sum of absolute differences between two histograms.
+- `compareWireframes(baselineWireframe, currentWireframe)` — diff two wireframes and return the current wireframe annotated with `differences`. Element groups are matched by index and must appear in the same order and count in both wireframes. Within each group, elements are paired with the baseline using nearest bounding-box matching, then diffed for layout shifts, size mismatches, text mismatches, and image histogram differences. Elements missing from the current capture are appended to the current wireframe's element groups so they still appear in the output, marked as `missing_element` (or `missing_text`).
 
 ### Stability
 
-- `areWireframesStable(previousWireframeData, currentWireframeData)` — determine whether two consecutive captures are stable enough to trust.
+- `areWireframesStable(previousWireframeData, currentWireframeData)` — determine whether two consecutive captures are stable enough to trust, by checking for empty element groups, mismatched element counts, text content differences, and overall bounding-box size drift.
+
+### Output paths
+
+- `setWireframeOutputRoot(rootPath)` — set the root directory used to resolve relative output directories (defaults to `process.cwd()`).
+- `getWireframeOutputRoot()` — get the currently configured output root.
+- `resolveWireframeOutputDir(outputDir)` — resolve an output directory against the configured root; absolute paths are returned unchanged.
 
 ## How it works
 
@@ -243,4 +250,4 @@ Issues and pull requests are welcome. Please open an issue before submitting lar
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexysnap",
-  "version": "0.2.4-alpha.1",
+  "version": "0.2.6",
   "description": "Flexible visual snapshot testing for Playwright, built for e-commerce.",
   "keywords": [
     "playwright",
@@ -49,4 +49,4 @@
   "devDependencies": {
     "eslint": "^9.9.0"
   }
-}
+}

package/src/wireframeComparison.js

@@ -166,16 +166,8 @@ function compareTexts(baselineTexts, currentTexts, strictPosition = true, strict
 }
 
 function compareElements(baselineElement, currentElement, strictPosition = true, strictSize = true, maskDigits = false) {
-    currentElement.differences = compareBoundingBoxes(
-        baselineElement.boundingRect,
-        currentElement.boundingRect,
-        strictPosition,
-        strictSize
-    );
-
     if (baselineElement.histogram && currentElement.histogram) {
         const dh = histogramDiff(baselineElement.histogram, currentElement.histogram);
-        //expect.soft(dh, 'Histogram difference').toBeLessThanOrEqual(10);
         if (dh > 15) {
             currentElement.differences.push({
                 type: 'histogram_difference',
@@ -185,6 +177,13 @@ function compareElements(baselineElement, currentElement, strictPosition = true,
     
     if (baselineElement.texts.length > 0 || currentElement.texts.length > 0) {
         compareTexts(baselineElement.texts, currentElement.texts, strictPosition, strictSize, maskDigits);
+    } else {
+        currentElement.differences = compareBoundingBoxes(
+            baselineElement.boundingRect,
+            currentElement.boundingRect,
+            strictPosition,
+            strictSize
+        );
     }
 }
 
@@ -204,11 +203,6 @@ function compareWireframes(baselineWireframe, currentWireframe) {
         const strictPosition = currentElementGroup.strictPosition !== false;
         const strictSize = currentElementGroup.strictSize !== false;
         const maskDigits = currentElementGroup.maskDigits === true;
-
-        //TODO: REMOVE later
-        if (currentElementGroup.differences?.length === 0) {
-            currentElementGroup.differences = undefined
-        }
         
         const { matchedPairs, unmatchedCurrent, unmatchedBaseline } = createPairings(
             currentElementGroup.elements,

package/src/wireframeUtils.js

@@ -6,6 +6,7 @@ import { areWireframesStable } from './wireframeStability.js';
 import { resolveWireframeOutputDir } from './wireframeOutput.js';
 
 const FLEXYSNAP_ELEMENT_ID_ATTRIBUTE = 'data-flexysnap-id';
+const ELEMENT_GROUP_EXTRACTION_TIMEOUT_MS = 5000;
 
 async function getRGBHistogramFromBuffer(buffer) {
     const image = await loadImage(buffer);
@@ -39,6 +40,15 @@ function delay(milliseconds) {
     return new Promise(resolve => setTimeout(resolve, milliseconds));
 }
 
+function withTimeout(promise, milliseconds, timeoutMessage) {
+    let timeoutHandle;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutHandle = setTimeout(() => reject(new Error(timeoutMessage)), milliseconds);
+    });
+
+    return Promise.race([promise, timeoutPromise]).finally(() => clearTimeout(timeoutHandle));
+}
+
 async function getDeviceScaleFactor(page) {
     try {
         const scaleFactor = await page.evaluate(() => window.devicePixelRatio);
@@ -92,66 +102,62 @@ function scaleWireframeData(wireframeData, scaleFactor) {
     return wireframeData;
 }
 
-async function extractWireframe(page, elementGroups) {
-    const wireframeData = await page.evaluate(async ({elementGroups, elementIdAttribute}) => {
-
-        function createBoundingRect(element) {
-            const rect = element.getBoundingClientRect();
-            return {
-                top: Math.round(rect.top),
-                left: Math.round(rect.left),
-                bottom: Math.round(rect.bottom),
-                right: Math.round(rect.right)
-            };
-        }
-
-        function getTextNodeBoundingBox(textNode) {
-            const range = document.createRange();
-            range.selectNodeContents(textNode);
-            const rect = range.getBoundingClientRect();
-            return {
-                top: Math.round(rect.top),
-                left: Math.round(rect.left),
-                bottom: Math.round(rect.bottom),
-                right: Math.round(rect.right)
-            };
-        }
-
-        function isElementVisible(element) {
-            const style = window.getComputedStyle(element);
-            if (style.display === 'none' ||
-                style.visibility === 'hidden' ||
-                style.opacity === '0' ||
-                element.offsetWidth <= 0 ||
-                element.offsetHeight <= 0) {
-                return false;
-            }
-
-            const rect = element.getBoundingClientRect()
-
-            return rect.right >= 0 &&
-                rect.left < window.innerWidth &&
-                rect.bottom >= 0 &&
-                rect.top < window.innerHeight;
-        }
+function createEmptyElementGroupResult(elementGroup) {
+    return {
+        ...elementGroup,
+        strictPosition: elementGroup.strictPosition !== false,
+        strictSize: elementGroup.strictSize !== false,
+        maskDigits: elementGroup.maskDigits !== false,
+        elements: []
+    };
+}
 
+async function extractElementGroupData(page, elementGroup, groupIndex, elementIdAttribute) {
+    const extractionStartTime = Date.now();
 
-        for (let groupIndex = 0; groupIndex < elementGroups.length; groupIndex++) {
-            const elementGroup = elementGroups[groupIndex];
-            elementGroup.strictPosition = elementGroup.strictPosition !== false;
-            elementGroup.strictSize = elementGroup.strictSize !== false;
-            elementGroup.maskDigits = elementGroup.maskDigits !== false;
-            elementGroup.elements = [];
+    try {
+        const result = await withTimeout(
+            page.evaluate(({elementGroup, groupIndex, elementIdAttribute}) => {
+
+                function createBoundingRect(element) {
+                    const rect = element.getBoundingClientRect();
+                    return {
+                        top: Math.round(rect.top),
+                        left: Math.round(rect.left),
+                        bottom: Math.round(rect.bottom),
+                        right: Math.round(rect.right)
+                    };
+                }
 
-            let index = 0;
-            const matchedElements = document.querySelectorAll(elementGroup.selector);
+                function getTextNodeBoundingBox(textNode) {
+                    const range = document.createRange();
+                    range.selectNodeContents(textNode);
+                    const rect = range.getBoundingClientRect();
+                    return {
+                        top: Math.round(rect.top),
+                        left: Math.round(rect.left),
+                        bottom: Math.round(rect.bottom),
+                        right: Math.round(rect.right)
+                    };
+                }
 
-            for (const element of matchedElements) {
-                if (!isElementVisible(element))
-                    continue;
+                function isElementVisible(element) {
+                    const style = window.getComputedStyle(element);
+                    if (style.display === 'none' ||
+                        style.visibility === 'hidden' ||
+                        style.opacity === '0' ||
+                        element.offsetWidth <= 0 ||
+                        element.offsetHeight <= 0) {
+                        return false;
+                    }
 
+                    const rect = element.getBoundingClientRect()
 
-                const texts = [];
+                    return rect.right >= 0 &&
+                        rect.left < window.innerWidth &&
+                        rect.bottom >= 0 &&
+                        rect.top < window.innerHeight;
+                }
 
                 function getElementsWithDirectText(root, textIgnoreClasses) {
                     const results = [];
@@ -168,7 +174,6 @@ async function extractWireframe(page, elementGroups) {
 
                         if (textIgnoreClasses) {
                             let ignored = false;
-                            console.log(textIgnoreClasses);
                             let parent = walker.currentNode.parentElement;
                             while (parent != null && !ignored) {
                                 for (const className of parent.classList) {
@@ -192,52 +197,88 @@ async function extractWireframe(page, elementGroups) {
                     return results;
                 }
 
-                if (elementGroup.type === 'text') {
+                elementGroup.strictPosition = elementGroup.strictPosition !== false;
+                elementGroup.strictSize = elementGroup.strictSize !== false;
+                elementGroup.maskDigits = elementGroup.maskDigits !== false;
+                elementGroup.elements = [];
 
-                    const descendantArray = getElementsWithDirectText(element, elementGroup.textIgnoreClasses)
+                let index = 0;
+                const matchedElements = document.querySelectorAll(elementGroup.selector);
 
-                    for (const descendant of descendantArray) {
-                        if (!isElementVisible(descendant.parentElement))
-                            continue;
+                for (const element of matchedElements) {
+                    if (!isElementVisible(element))
+                        continue;
 
-                        const text = descendant.textContent.trim().replaceAll(/\s+/g, ' ')
-                        if (text.length === 0)
-                            continue;
+                    const texts = [];
 
-                        const isNested = descendantArray.some(other =>
-                            other !== descendant && other.contains(descendant)
-                        );
+                    if (elementGroup.type === 'text') {
 
-                        if (isNested)
-                            continue;
+                        const descendantArray = getElementsWithDirectText(element, elementGroup.textIgnoreClasses)
 
-                        texts.push({
-                            text: text,
-                            boundingRect: getTextNodeBoundingBox(descendant)
-                        });
+                        for (const descendant of descendantArray) {
+                            if (!isElementVisible(descendant.parentElement))
+                                continue;
+
+                            const text = descendant.textContent.trim().replaceAll(/\s+/g, ' ')
+                            if (text.length === 0)
+                                continue;
+
+                            const isNested = descendantArray.some(other =>
+                                other !== descendant && other.contains(descendant)
+                            );
+
+                            if (isNested)
+                                continue;
+
+                            texts.push({
+                                text: text,
+                                boundingRect: getTextNodeBoundingBox(descendant)
+                            });
+                        }
+                    }
+
+                    const elementData = {
+                        index: index,
+                        boundingRect: createBoundingRect(element),
+                        texts: texts,
+                        type: elementGroup.type
+                    };
+
+                    if (elementGroup.type === 'image') {
+                        const elementId = `fsnap-g${groupIndex}-e${index}`;
+                        element.setAttribute(elementIdAttribute, elementId);
+                        elementData.elementId = elementId;
                     }
-                }
 
-                const elementData = {
-                    index: index,
-                    boundingRect: createBoundingRect(element),
-                    texts: texts,
-                    type: elementGroup.type
-                };
-
-                if (elementGroup.type === 'image') {
-                    const elementId = `fsnap-g${groupIndex}-e${index}`;
-                    element.setAttribute(elementIdAttribute, elementId);
-                    elementData.elementId = elementId;
+                    elementGroup.elements.push(elementData);
+                    index += 1;
                 }
 
-                elementGroup.elements.push(elementData);
-                index += 1;
-            }
-        }
+                return elementGroup;
+            }, {elementGroup, groupIndex, elementIdAttribute}),
+            ELEMENT_GROUP_EXTRACTION_TIMEOUT_MS,
+            `Timed out extracting element group with selector "${elementGroup.selector}"`
+        );
+
+        const extractionDuration = Date.now() - extractionStartTime;
+        logTimestamp(`Extracted element group "${elementGroup.selector}" in ${extractionDuration/1000} seconds.`);
+
+        return result;
+    } catch (error) {
+        const extractionDuration = Date.now() - extractionStartTime;
+        logTimestamp(`Failed to extract element group "${elementGroup.selector}" after ${extractionDuration/1000} seconds: ${error.message}`);
+        return createEmptyElementGroupResult(elementGroup);
+    }
+}
 
-        return elementGroups;
-    }, {elementGroups, elementIdAttribute: FLEXYSNAP_ELEMENT_ID_ATTRIBUTE});
+async function extractWireframe(page, elementGroups, closePopups) {
+    const wireframeData = [];
+
+    for (let groupIndex = 0; groupIndex < elementGroups.length; groupIndex++) {
+        closePopups();
+        const elementGroupData = await extractElementGroupData(page, elementGroups[groupIndex], groupIndex, FLEXYSNAP_ELEMENT_ID_ATTRIBUTE);
+        wireframeData.push(elementGroupData);
+    }
 
     const scrollPosition = await page.evaluate(() => ({
         x: window.scrollX,
@@ -294,14 +335,14 @@ function cloneElementGroups(elementGroups) {
     return elementGroups.map(elementGroup => ({...elementGroup, elements: undefined}));
 }
 
-async function extractStableWireframe(page, elementGroups, retryDelay, maxRetryCount) {
+async function extractStableWireframe(page, elementGroups, retryDelay, maxRetryCount, closePopups) {
     let previousWireframeData = null;
     let currentWireframeData = null;
     let currentScrollPosition = null;
 
     for (let attempt = 0; attempt < maxRetryCount; attempt++) {
         const extractionStartTime = Date.now();
-        const extractionResult = await extractWireframe(page, cloneElementGroups(elementGroups));
+        const extractionResult = await extractWireframe(page, cloneElementGroups(elementGroups), closePopups);
         currentWireframeData = extractionResult.wireframeData;
         currentScrollPosition = extractionResult.scrollPosition;
         const extractionDuration = Date.now() - extractionStartTime;
@@ -327,10 +368,10 @@ async function extractStableWireframe(page, elementGroups, retryDelay, maxRetryC
 }
 
 async function expectWireframe(page, elementGroups, outputDir, outputFile, outputName, options = {}) {
-    const { retryDelay = 1000, maxRetryCount = 10, metadata = {} } = options;
+    const { retryDelay = 1000, maxRetryCount = 10, metadata = {}, closePopups = function() {} } = options;
 
     logTimestamp(`Starting wireframe capture for: ${outputFile}`);
-    const { wireframeData, scrollPosition } = await extractStableWireframe(page, elementGroups, retryDelay, maxRetryCount);
+    const { wireframeData, scrollPosition } = await extractStableWireframe(page, elementGroups, retryDelay, maxRetryCount, closePopups);
 
     const screenshotScrollPosition = await page.evaluate(() => ({
         x: window.scrollX,