flexysnap 0.1.4-alpha.1 → 0.2.0-alpha.1

package/README.md

@@ -8,7 +8,9 @@ Traditional pixel-diffing tools flag every layout shift as a failure, even a 2px
 
 - **Structural diffing** — captures element bounding boxes, text nodes, and image histograms instead of raw pixels, so sub-pixel font rendering and anti-aliasing never fail your suite.
 - **Position tolerance** — element groups can be marked `strictPosition: false` to check size only, ignoring exact placement for content that legitimately moves.
+- **Digit masking** — element groups can be marked `maskDigits: true` so counters, prices, and timers don't fail on numeric churn.
 - **Stability detection** — wireframes are re-captured until the layout settles, so lazy-loaded images, animations, and reflow don't produce flaky baselines.
+- **Scroll-safe capture** — the scroll position at extraction time is recorded and restored, and stored alongside the screenshot.
 - **Built on Playwright** — works with your existing Playwright config, fixtures, and test runner. No new browser automation layer to learn.
 - **Annotated screenshots** — overlay the captured wireframe onto its screenshot to visualize what was checked and what differed.
 
@@ -36,12 +38,16 @@ const elementGroups = [
   { selector: '.hero-banner', type: 'image' },
   { selector: '.product-title', type: 'text' },
   { selector: '.cross-sell-carousel', type: 'box', strictPosition: false },
-  { selector: '.price', type: 'text', textIgnoreClasses: ['screen-reader-text'] }
+  { selector: '.price', type: 'text', maskDigits: true },
+  { selector: '.stock-status', type: 'text', textIgnoreClasses: ['screen-reader-text'] }
 ];
 ```
 
 - `strictPosition: false` — compare element size only, not exact position.
-- `textIgnoreClasses` — skip text found inside elements carrying these class names.
+- `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.
+
+Only visible elements are captured: elements that are `display: none`, `visibility: hidden`, fully transparent, zero-sized, or entirely outside the viewport are skipped.
 
 ## Quick start
 
@@ -63,19 +69,57 @@ test('product page wireframe', async ({ page }) => {
   await expectWireframe(
     page,
     elementGroups,
-    'product-config',   // config name
+    'product-config',   // output directory
     'product-page',     // output file basename
-    'Product Page'      // human-readable name
+    'Product Page',     // human-readable name
+    { retryDelay: 1000, maxRetryCount: 10, metadata: { url: page.url() } }
   );
 });
 ```
 
-`expectWireframe` captures a stable wireframe (re-sampling until the layout settles), writes a JSON wireframe and a PNG screenshot into:
+`expectWireframe` captures a stable wireframe (re-sampling until the layout settles), then writes `<outputFile>.json` and `<outputFile>.png` into the resolved output directory. It returns:
 
+```js
+{
+  wireframeOutput,  // the JSON object that was written
+  screenshotPath,   // absolute path of the PNG
+  outputDir         // resolved output directory
+}
 ```
-wireframes/test/<TEST_TYPE>/<config>/<DEVICE_TYPE>/<USER_TYPE>/
+
+### Wireframe JSON shape
+
+```json
+{
+  "name": "Product Page",
+  "timestamp": "2024-01-01T00:00:00.000Z",
+  "scrollPosition": { "x": 0, "y": 0 },
+  "screenshotScrollPosition": { "x": 0, "y": 0 },
+  "elementGroups": [
+    {
+      "selector": ".product-title",
+      "type": "text",
+      "strictPosition": true,
+      "elements": [
+        {
+          "index": 0,
+          "type": "text",
+          "boundingRect": { "top": 120, "left": 32, "bottom": 148, "right": 420 },
+          "texts": [
+            {
+              "text": "Example Item",
+              "boundingRect": { "top": 120, "left": 32, "bottom": 148, "right": 260 }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}
 ```
 
+Anything passed as `options.metadata` is merged into the top level of this object.
+
 ## API
 
 `flexysnap` exports the following from its main entry point:
@@ -94,16 +138,19 @@ wireframes/test/<TEST_TYPE>/<config>/<DEVICE_TYPE>/<USER_TYPE>/
 
 ### Wireframe capture
 
-- `expectWireframe(page, elementGroups, configName, outputFile, outputName, retryDelay?, maxRetryCount?)` — capture a stable wireframe and write JSON + screenshot.
-- `getRGBHistogramFromBuffer(buffer)` — compute a 48-bin RGB histogram from an image buffer.
+- `expectWireframe(page, elementGroups, outputDir, outputFile, outputName, options?)` — capture a stable wireframe and write JSON + screenshot.
+  - `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.
+- `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?)`
-- `compareTexts(baselineTexts, currentTexts, strictPosition?)`
+- `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.
+- `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.
 
 ### Stability
@@ -112,13 +159,15 @@ wireframes/test/<TEST_TYPE>/<config>/<DEVICE_TYPE>/<USER_TYPE>/
 
 ## How it works
 
-1. **Wireframe extraction** — `flexysnap` walks the DOM in the browser, collecting bounding boxes for each matched element, text nodes for `text` groups, and RGB histograms (via `sharp`) for `image` groups.
-2. **Stability loop** — the wireframe is captured repeatedly until consecutive captures are stable (element counts match, text is unchanged, and total bounding-box area drift stays under 3%). This defeats lazy loading and animation flakiness.
+1. **Wireframe extraction** — `flexysnap` walks the DOM in the browser, collecting bounding boxes for each matched visible element and text nodes for `text` groups. For `image` groups it tags the element, waits for its images to finish loading, screenshots it, and computes an RGB histogram with `canvas`. Tagging attributes are removed and the original scroll position is restored afterwards.
+2. **Stability loop** — the wireframe is captured repeatedly until consecutive captures are stable. Each attempt waits out the remainder of `retryDelay`, so slow pages aren't penalized twice. This defeats lazy loading and animation flakiness.
 3. **Baseline comparison** — element groups from the current run are paired with the baseline using nearest bounding-box matching. Each pair is diffed for layout shifts, text mismatches, and histogram (image) differences. Unmatched elements are reported as extra or missing.
 
-## Environment variables
+Comparison tolerances: bounding boxes allow up to 10px of drift on any edge, and image histograms allow a total absolute difference of 15.
+
+## Output paths
 
-Wireframe paths are namespaced by environment variables so the same tests can run across devices and user roles:
+The `outputDir` argument is resolved by `resolveWireframeOutputDir`, which namespaces wireframes by environment variables so the same tests can run across devices and user roles:
 
 | Variable      | Example      | Purpose                          |
 |---------------|--------------|----------------------------------|
@@ -126,24 +175,26 @@ Wireframe paths are namespaced by environment variables so the same tests can ru
 | `DEVICE_TYPE` | `mobile`     | Device / viewport identifier     |
 | `USER_TYPE`   | `guest`      | User role identifier             |
 
-The output path for a captured wireframe is:
-
 ```
-wireframes/test/<TEST_TYPE>/<configName>/<DEVICE_TYPE>/<USER_TYPE>/
+wireframes/test/<TEST_TYPE>/<outputDir>/<DEVICE_TYPE>/<USER_TYPE>/
 ```
 
-where `configName` is passed directly to `expectWireframe`.
-
 ## Comparing against a baseline
 
-Use `compareWireframes` in your own Playwright spec to diff a captured wireframe against a stored baseline. It pairs each element group's elements with the baseline using nearest bounding-box matching, then annotates the current wireframe's elements and texts with a `differences` array.
+Use `compareWireframes` in your own Playwright spec to diff a captured wireframe against a stored baseline. It pairs each element group's elements with the baseline using nearest bounding-box matching, then annotates the current wireframe's elements and texts with a `differences` array. Elements and texts without differences are left with `differences` undefined, so an unchanged page produces a clean wireframe.
 
 ```js
+import fs from 'fs';
 import { compareWireframes } from 'flexysnap';
 
+const baselineWireframe = JSON.parse(fs.readFileSync('baseline/product-page.json', 'utf8'));
+const currentWireframe = JSON.parse(fs.readFileSync('current/product-page.json', 'utf8'));
+
 const annotated = compareWireframes(baselineWireframe, currentWireframe);
 ```
 
+Elements missing from the current capture are appended to the current element group so they still appear in annotated output, marked as `missing_element` (or `missing_text`).
+
 ## Difference types
 
 | Type                   | Meaning                                            |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexysnap",
-  "version": "0.1.4-alpha.1",
+  "version": "0.2.0-alpha.1",
   "description": "Flexible visual snapshot testing for Playwright, built for e-commerce.",
   "keywords": [
     "playwright",

package/src/index.js

@@ -1,5 +1,6 @@
 export {
     waitForCompleteLoad,
+    gotoWithRetry,
     highlightedClick,
     click,
     hover,

package/src/testUtils.js

@@ -2,6 +2,18 @@ import { test } from '@playwright/test';
 
 let closePopups = async function(page) {}
 
+async function gotoWithRetry(page, url) {
+	try {
+		logTimestamp('Loading ' + url);
+		await page.goto(url, { timeout: 30_000, waitUntil: "domcontentloaded" });
+	} catch (firstError) {
+		logTimestamp('Retry loading ' + url);
+		await page.goto(url, { timeout: 30_000, waitUntil: "domcontentloaded" });
+	}
+	await waitForCompleteLoad(page)
+}
+
+
 function setClosePopups(f) {
     closePopups = f;
 }
@@ -188,6 +200,7 @@ async function selectOption(page, field, value) {
 
 export {
     waitForCompleteLoad,
+    gotoWithRetry,
     highlightedClick,
     click,
     hover,

package/src/wireframeComparison.js

@@ -96,7 +96,11 @@ function compareBoundingBoxes(baselineRect, currentRect, tolerance = 10, strictP
     return differences;
 }
 
-function compareTexts(baselineTexts, currentTexts, strictPosition = true) {
+function replaceDigitsWithPlaceholder(text) {
+    return text.replace(/\d+/g, '[digits]');
+}
+
+function compareTexts(baselineTexts, currentTexts, strictPosition = true, maskDigits = false) {
     const { matchedPairs, unmatchedCurrent, unmatchedBaseline } = createPairings(currentTexts, baselineTexts);
     
     for (const pairing of matchedPairs) {
@@ -104,6 +108,14 @@ function compareTexts(baselineTexts, currentTexts, strictPosition = true) {
         const currentText = currentTexts[pairing.currentIndex];
         currentText.differences = [];
 
+
+        let textsEqual = false
+        if (maskDigits) {
+            textsEqual = replaceDigitsWithPlaceholder(baselineText.text) !== replaceDigitsWithPlaceholder(currentText.text);
+        } else {
+            textsEqual = baselineText.text !== currentText.text;
+        }
+
         if (baselineText.text !== currentText.text) {
             //expect.soft(currentText.text).toEqual(baselineText.text);
             currentText.differences.push({
@@ -144,7 +156,7 @@ function compareTexts(baselineTexts, currentTexts, strictPosition = true) {
     }
 }
 
-function compareElements(baselineElement, currentElement, strictPosition = true) {
+function compareElements(baselineElement, currentElement, strictPosition = true, maskDigits = false) {
     currentElement.differences = compareBoundingBoxes(
         baselineElement.boundingRect,
         currentElement.boundingRect,
@@ -163,9 +175,7 @@ function compareElements(baselineElement, currentElement, strictPosition = true)
     }
     
     if (baselineElement.texts.length > 0 || currentElement.texts.length > 0) {
-        //expect.soft(baselineElement.texts.length, "Number of texts in element should be equal").toEqual(currentElement.texts.length);
-        
-        compareTexts(baselineElement.texts, currentElement.texts, strictPosition);
+        compareTexts(baselineElement.texts, currentElement.texts, strictPosition, maskDigits);
     }
 }
 
@@ -183,6 +193,7 @@ function compareWireframes(baselineWireframe, currentWireframe) {
         expect(baselineElementGroup.selector).toEqual(currentElementGroup.selector);
 
         const strictPosition = currentElementGroup.strictPosition !== false;
+        const maskDigits = currentElementGroup.maskDigits === true;
 
         //TODO: REMOVE later
         if (currentElementGroup.differences?.length === 0) {
@@ -197,7 +208,7 @@ function compareWireframes(baselineWireframe, currentWireframe) {
         for (const pairing of matchedPairs) {
             const baselineElement = baselineElementGroup.elements[pairing.baselineIndex];
             const currentElement = currentElementGroup.elements[pairing.currentIndex];
-            compareElements(baselineElement, currentElement, strictPosition);
+            compareElements(baselineElement, currentElement, strictPosition, maskDigits);
             if (currentElement.differences?.length === 0) {
                 currentElement.differences = undefined
             }

package/src/wireframeUtils.js

@@ -86,6 +86,7 @@ async function extractWireframe(page, elementGroups) {
         for (let groupIndex = 0; groupIndex < elementGroups.length; groupIndex++) {
             const elementGroup = elementGroups[groupIndex];
             elementGroup.strictPosition = elementGroup.strictPosition !== false;
+            elementGroup.maskDigits = elementGroup.maskDigits === false;
             elementGroup.elements = [];
 
             let index = 0;