flexysnap 0.1.0 → 0.1.2-alpha.1

package/README.md

@@ -10,7 +10,7 @@ Traditional pixel-diffing tools flag every layout shift as a failure, even a 2px
 - **Position tolerance** — element groups can be marked `strictPosition: false` to check size only, ignoring exact placement for content that legitimately moves.
 - **Stability detection** — wireframes are re-captured until the layout settles, so lazy-loaded images, animations, and reflow don't produce flaky baselines.
 - **Built on Playwright** — works with your existing Playwright config, fixtures, and test runner. No new browser automation layer to learn.
-- **Rich HTML reports** — generate an interactive report with baseline/current image sliders, annotated wireframe overlays, and categorized differences (text, image, layout).
+- **Annotated screenshots** — overlay the captured wireframe onto its screenshot to visualize what was checked and what differed.
 
 ## Installation
 
@@ -49,7 +49,7 @@ const elementGroups = [
 
 ```js
 import { test } from '@playwright/test';
-import { expectWireframe } from 'flexysnap/wireframeUtils.js';
+import { expectWireframe } from 'flexysnap';
 
 const elementGroups = [
   { selector: '.hero-banner', type: 'image' },
@@ -76,6 +76,40 @@ test('product page wireframe', async ({ page }) => {
 wireframes/test/<TEST_TYPE>/<config>/<DEVICE_TYPE>/<USER_TYPE>/
 ```
 
+## API
+
+`flexysnap` exports the following from its main entry point:
+
+### Test utilities
+
+- `waitForCompleteLoad(page)` — wait for `domcontentloaded`, `load`, and a settle delay.
+- `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.
+- `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.
+
+### 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.
+
+### Wireframe comparison
+
+- `compareWireframes(baselineWireframe, currentWireframe)` — diff two wireframes and annotate the current one with `differences`.
+- `compareElements(baselineElement, currentElement, strictPosition?)`
+- `compareTexts(baselineTexts, currentTexts, strictPosition?)`
+- `compareBoundingBoxes(baselineRect, currentRect, tolerance?, strictPosition?)`
+- `createPairings(currentElements, baselineElements)` — nearest bounding-box matching between two element sets.
+- `histogramDiff(a, b)` — sum of absolute differences between two histograms.
+
+### Stability
+
+- `areWireframesStable(previousWireframeData, currentWireframeData)` — determine whether two consecutive captures are stable enough to trust.
+
 ## 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.
@@ -89,27 +123,26 @@ Wireframe paths are namespaced by environment variables so the same tests can ru
 | Variable      | Example      | Purpose                          |
 |---------------|--------------|----------------------------------|
 | `TEST_TYPE`   | `smoke`      | Top-level test grouping          |
-| `TEST_CONFIG` | `production` | Configuration name               |
 | `DEVICE_TYPE` | `mobile`     | Device / viewport identifier     |
 | `USER_TYPE`   | `guest`      | User role identifier             |
 
-## Comparing against a baseline
-
-The comparison suite reads baseline and current wireframes and asserts they match:
+The output path for a captured wireframe is:
 
-```bash
-TEST_TYPE=smoke TEST_CONFIG=production DEVICE_TYPE=mobile USER_TYPE=guest \
-  npx playwright test compare-wireframes.spec.js
+```
+wireframes/test/<TEST_TYPE>/<configName>/<DEVICE_TYPE>/<USER_TYPE>/
 ```
 
-It reads from:
+where `configName` is passed directly to `expectWireframe`.
 
-```
-wireframes/baseline/<TEST_TYPE>/<TEST_CONFIG>/<DEVICE_TYPE>/<USER_TYPE>/
-wireframes/test/<TEST_TYPE>/<TEST_CONFIG>/<DEVICE_TYPE>/<USER_TYPE>/
-```
+## 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.
+
+```js
+import { compareWireframes } from 'flexysnap';
 
-Each matched wireframe is diffed and re-written with annotated `differences`, then every difference is asserted as a soft failure so the whole page is reported at once.
+const annotated = compareWireframes(baselineWireframe, currentWireframe);
+```
 
 ## Difference types
 
@@ -124,47 +157,34 @@ Each matched wireframe is diffed and re-written with annotated `differences`, th
 | `extra_element`        | Element present now but not in baseline            |
 | `missing_element`      | Element present in baseline but not now            |
 
-## Annotating screenshots
+## CLI
 
-Overlay the captured wireframe onto its screenshot to visualize what was checked and what differed:
+`flexysnap` ships a small CLI:
 
 ```bash
-# annotate a single pair
-node annotateWireframe.mjs wireframe.json screenshot.png
+# print usage
+flexysnap
 
-# annotate every matching .json/.png pair in a folder
-node annotateWireframe.mjs ./wireframes/test/smoke/production/mobile/guest
-```
+# regenerate baseline snapshots (not implemented yet)
+flexysnap update
 
-Boxes are color-coded: text (blue), image (green), box (amber), and error (red) for any element carrying differences. Dashed borders indicate position-tolerant groups. Output is written as `<name>_wireframe.png`.
+# annotate a single wireframe/screenshot pair
+flexysnap annotate wireframe.json screenshot.png
 
-## Generating an HTML report
-
-```bash
-node generate-report.js <baseline-folder> <current-folder> [output-file]
-```
-
-Example:
-
-```bash
-node generate-report.js \
-  wireframes/baseline/smoke/production/mobile/guest \
-  wireframes/test/smoke/production/mobile/guest \
-  report.html
+# annotate every matching .json/.png pair in a folder
+flexysnap annotate ./wireframes/test/smoke/product-config/mobile/guest
 ```
 
-The report includes:
+### Annotating screenshots
 
-- Summary statistics (elements checked, total / text / image / layout differences) with click-to-jump navigation.
-- A baseline↔current comparison slider (via cocoen) when both images are available.
-- A global toggle between **original** and **annotated** screenshots.
-- A per-wireframe list of detected differences, with empty sections auto-collapsed.
+Overlay the captured wireframe onto its screenshot to visualize what was checked and what differed. Boxes are color-coded: text (blue), image (green), box (amber), and error (red) for any element carrying differences. Dashed borders indicate position-tolerant groups. Output is written next to the screenshot as `<name>_wireframe.png`.
 
 ## Roadmap
 
+- [ ] Baseline update command (`flexysnap update`)
 - [ ] Region auto-detection for common e-commerce patterns (cart, checkout, PDP)
 - [ ] GitHub Actions annotation integration
-- [ ] Plugin-change tracking integrated into the HTML report
+- [ ] HTML report generation with comparison sliders
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flexysnap",
-  "version": "0.1.0",
+  "version": "0.1.2-alpha.1",
   "description": "Flexible visual snapshot testing for Playwright, built for e-commerce.",
   "keywords": [
     "playwright",
@@ -28,7 +28,7 @@
     ".": "./src/index.js"
   },
   "bin": {
-    "flexysnap": "./src/cli.js"
+    "flexysnap": "src/cli.js"
   },
   "files": [
     "src",
@@ -52,4 +52,4 @@
   "devDependencies": {
     "eslint": "^9.9.0"
   }
-}
+}

package/src/annotateWireframe.js

@@ -0,0 +1,137 @@
+import sharp from 'sharp';
+import fs from 'fs';
+import path from 'path';
+import { createCanvas } from 'canvas';
+
+async function annotateWireframeFile(wireframeFile, screenshotFile) {
+    if (!fs.existsSync(wireframeFile)) {
+        console.error(`Wireframe file not found: ${wireframeFile}`);
+        return;
+    }
+
+    if (!fs.existsSync(screenshotFile)) {
+        console.error(`Screenshot file not found: ${screenshotFile}`);
+        return;
+    }
+
+    const wireframeContent = fs.readFileSync(wireframeFile, 'utf-8');
+    const wireframe = JSON.parse(wireframeContent);
+
+    const metadata = await sharp(screenshotFile).metadata();
+    const width = metadata.width;
+    const height = metadata.height;
+
+    const canvas = createCanvas(width, height);
+    const ctx = canvas.getContext('2d');
+
+    const colors = {
+        box: { fill: 'rgba(220, 160, 40, 0.4)', stroke: '#E6A500' },
+        image: { fill: 'rgba(70, 180, 120, 0.4)', stroke: '#2EBC6F' },
+        text: { fill: 'rgba(50, 130, 190, 0.4)', stroke: '#0066CC' },
+        error: { fill: 'rgba(211, 47, 47, 0.4)', stroke: '#D32F2F' }
+    };
+
+    function hasErrors(obj) {
+        return obj.differences && Array.isArray(obj.differences) && obj.differences.length > 0;
+    }
+
+    function drawBoundingBox(rect, colorKey, dashed = false) {
+        const boxWidth = rect.right - rect.left;
+        const boxHeight = rect.bottom - rect.top;
+        const color = colors[colorKey];
+
+        ctx.fillStyle = color.fill;
+        ctx.fillRect(rect.left, rect.top, boxWidth, boxHeight);
+        ctx.strokeStyle = color.stroke;
+        ctx.lineWidth = 2;
+        ctx.setLineDash(dashed ? [6, 4] : []);
+        ctx.strokeRect(rect.left, rect.top, boxWidth, boxHeight);
+        ctx.setLineDash([]);
+    }
+
+    for (const elementGroup of wireframe.elementGroups) {
+        const dashed = elementGroup.strictPosition === false;
+
+        for (const element of elementGroup.elements) {
+            const rect = element.boundingRect;
+
+            if (element.type === 'box') {
+                const colorKey = hasErrors(element) ? 'error' : 'box';
+                drawBoundingBox(rect, colorKey, dashed);
+            } else if (element.type === 'image') {
+                const colorKey = hasErrors(element) ? 'error' : 'image';
+                drawBoundingBox(rect, colorKey, dashed);
+            } else if (element.type === 'text' && element.texts && element.texts.length > 0) {
+                for (const text of element.texts) {
+                    const colorKey = hasErrors(text) ? 'error' : 'text';
+                    drawBoundingBox(text.boundingRect, colorKey, dashed);
+                }
+            }
+        }
+    }
+
+    const overlayBuffer = canvas.toBuffer('image/png');
+
+    const outputDir = path.dirname(screenshotFile);
+    const basename = path.basename(screenshotFile, '.png');
+    const outputPath = path.join(outputDir, `${basename}_wireframe.png`);
+
+    await sharp(screenshotFile)
+        .grayscale()
+        .composite([{
+            input: overlayBuffer,
+            blend: 'over'
+        }])
+        .toFile(outputPath);
+
+    console.log(`Annotated wireframe saved to: ${outputPath}`);
+}
+
+async function processFolder(folderPath) {
+    if (!fs.existsSync(folderPath)) {
+        console.error(`Folder not found: ${folderPath}`);
+        process.exit(1);
+    }
+
+    const stats = fs.statSync(folderPath);
+    if (!stats.isDirectory()) {
+        console.error(`Path is not a directory: ${folderPath}`);
+        process.exit(1);
+    }
+
+    const files = fs.readdirSync(folderPath);
+    const basenames = new Set();
+
+    for (const file of files) {
+        const ext = path.extname(file).toLowerCase();
+        if (ext === '.json' || ext === '.png') {
+            const basename = path.basename(file, ext);
+            basenames.add(basename);
+        }
+    }
+
+    for (const basename of basenames) {
+        const jsonFile = path.join(folderPath, `${basename}.json`);
+        const pngFile = path.join(folderPath, `${basename}.png`);
+
+        if (fs.existsSync(jsonFile) && fs.existsSync(pngFile)) {
+            await annotateWireframeFile(jsonFile, pngFile);
+        }
+    }
+}
+
+export async function runAnnotate(args) {
+    if (args.length === 0) {
+        console.error('Usage: flexysnap annotate <wireframe.json> <screenshot.png>');
+        console.error('   or: flexysnap annotate <folder>');
+        process.exit(1);
+    }
+
+    if (args.length === 1) {
+        await processFolder(args[0]);
+    } else if (args.length >= 2) {
+        const wireframeFile = args[0];
+        const screenshotFile = args[1];
+        await annotateWireframeFile(wireframeFile, screenshotFile);
+    }
+}

package/src/cli.js

@@ -1,22 +1,33 @@
 #!/usr/bin/env node
 
-/**
- * flexysnap CLI — placeholder implementation.
- *
- * Usage:
- *   npx flexysnap update   Regenerate baseline snapshots
- */
+import { runAnnotate } from './annotateWireframe.js';
 
-const [, , command] = process.argv;
+const [, , command, ...args] = process.argv;
 
-switch (command) {
-    case 'update':
-        console.log('flexysnap: baseline update not implemented yet.');
-        break;
-    default:
-        console.log('flexysnap');
-        console.log('');
-        console.log('Usage:');
-        console.log('  flexysnap update   Regenerate baseline snapshots');
-        break;
-}
+function printUsage() {
+    console.log('flexysnap');
+    console.log('');
+    console.log('Usage:');
+    console.log('  flexysnap update                              Regenerate baseline snapshots');
+    console.log('  flexysnap annotate <wireframe.json> <screenshot.png>   Annotate a screenshot with wireframe data');
+    console.log('  flexysnap annotate <folder>                   Annotate all matching files in a folder');
+}
+
+async function main() {
+    switch (command) {
+        case 'update':
+            console.log('flexysnap: baseline update not implemented yet.');
+            break;
+        case 'annotate':
+            await runAnnotate(args);
+            break;
+        default:
+            printUsage();
+            break;
+    }
+}
+
+main().catch(err => {
+    console.error('Error:', err.message);
+    process.exit(1);
+});

package/src/index.js

@@ -1,26 +1,24 @@
-/**
- * flexysnap — flexible visual snapshot testing for Playwright.
- *
- * This is a placeholder entry point. Replace with the real
- * snapshot-comparison implementation.
- */
+export {
+    waitForCompleteLoad,
+    highlightedClick,
+    click,
+    hover,
+    fill,
+    rehover,
+    setClosePopups,
+    logTimestamp,
+    setBaseUrl
+} from './testUtils.js';
 
-/**
- * Capture and compare a snapshot for the given Playwright page.
- *
- * @param {import('@playwright/test').Page} page
- * @param {string} name - snapshot identifier, used for the stored baseline file
- * @param {object} [options]
- * @param {number} [options.tolerance=0.02] - allowed pixel-drift ratio (0-1)
- * @param {Record<string, 'strict'|'presence'|'ignore'>} [options.regions] - per-selector comparison policy
- */
-export async function expectSnapshot(page, name, options = {}) {
-    const { tolerance = 0.02, regions = {} } = options;
+export {
+    compareWireframes,
+    compareElements,
+    compareTexts,
+    compareBoundingBoxes,
+    createPairings,
+    histogramDiff
+} from './wireframeComparison.js';
 
-    // TODO: implement capture + diff logic (sharp/canvas-based comparison).
-    throw new Error(
-        `expectSnapshot("${name}") is not implemented yet. tolerance=${tolerance}, regions=${JSON.stringify(regions)}`
-    );
-}
+export { areWireframesStable } from './wireframeStability.js';
 
-export default { expectSnapshot };
+export { expectWireframe, getRGBHistogramFromBuffer } from './wireframeUtils.js';

package/src/testUtils.js

@@ -0,0 +1,166 @@
+import { test } from '@playwright/test';
+
+let closePopups = async function(page) {}
+
+function setClosePopups(f) {
+    closePopups = f;
+}
+
+let baseUrl = '';
+function setBaseUrl(url) {
+    baseUrl = url;
+}
+
+test.beforeEach(async ({ context }) => {
+    startTimer();
+    logTimestamp('Test execution started');
+    await context.route('**/*', route => {
+        const req = route.request();
+        const url = new URL(req.url());
+        const path = url.pathname.toLowerCase();
+        if (req.method() !== 'GET' || path.includes('/wp-content/') || !path.includes(baseUrl)) {
+            return route.continue();
+        }
+        url.searchParams.set('_cb', Date.now().toString());
+        const urlString = url.toString();
+        logTimestamp('Requesting ' + urlString);
+        route.continue({ url: urlString });
+    });
+});
+
+let testStartTime = null;
+function startTimer() {
+    testStartTime = new Date();
+
+	logTimestamp(`Test started at: ${testStartTime.toISOString()}`);
+
+    return testStartTime;
+}
+
+function logTimestamp(eventName) {
+    if (!testStartTime) {
+        startTimer();
+    }
+    
+    const currentTime = new Date();
+    const elapsedMs = currentTime - testStartTime;
+    const elapsedSec = (elapsedMs / 1000).toFixed(3);
+    
+    const logMessage = `[${currentTime.toISOString()}] ${eventName} - ${elapsedSec}s elapsed\n`;
+    console.log(logMessage.trim());
+    
+    return { currentTime, elapsedMs, elapsedSec };
+}
+
+async function waitForCompleteLoad(page) {
+    await page.waitForLoadState('domcontentloaded');
+    await page.waitForLoadState('load');
+    await page.waitForTimeout(500);
+}
+
+
+async function click(page, locator) {
+	await waitForCompleteLoad(page);
+    await closePopups(page);
+    await rehover(page);
+	const success = await highlightedClick(page, locator);
+	await waitForCompleteLoad(page);
+	await page.waitForTimeout(500);
+	await closePopups(page);
+    if (!success) {
+        await highlightedClick(page, locator);
+        await page.waitForTimeout(500);
+        await closePopups(page);
+    }
+}
+
+async function highlightedClick(page, locator) {
+    const isInViewport = await locator.evaluate((element) => {
+        const rect = element.getBoundingClientRect();
+        const windowHeight = window.innerHeight;
+        const windowWidth = window.innerWidth;
+        
+        return (
+            rect.top >= 0 &&
+            rect.left >= 0 &&
+            rect.bottom <= windowHeight &&
+            rect.right <= windowWidth
+       );
+    });
+    
+    if (!isInViewport) {
+        const elementPosition = await locator.evaluate((element) => {
+            const rect = element.getBoundingClientRect();
+            return {
+                top: rect.top + window.scrollY,
+                height: rect.height
+            };
+        });
+        
+        const viewportHeight = await page.evaluate(() => window.innerHeight);
+        const targetScrollY = elementPosition.top - (viewportHeight / 2) + (elementPosition.height / 2);
+        
+        const maxScrollY = await page.evaluate(() => document.body.scrollHeight - window.innerHeight);
+        const finalScrollY = Math.max(0, Math.min(targetScrollY, maxScrollY));
+        
+        logTimestamp(`Element not in viewport, scrolling to position: ${finalScrollY}`);
+        await page.evaluate((scrollY) => window.scrollTo(0, scrollY), finalScrollY);
+        await page.waitForTimeout(500);
+    } 
+    try {
+        await closePopups(page);
+        await locator.click({ force: true });
+        logTimestamp('clicking ' + locator);
+        return true;
+    } catch (error) {
+        logTimestamp(`Error clicking on locator: ${locator} ${error.message}`);
+        return false;
+    }
+}
+
+let hoveredLocator = null;
+
+async function hover(page, locator) {
+    hoveredLocator = locator;
+    
+    try {
+        await locator.hover();
+        logTimestamp('hovering ' + locator);
+        return true;
+    } catch (error) {
+        logTimestamp(`Error hovering on locator: ${locator} ${error.message}`);
+        return false;
+    }
+}
+
+async function rehover(page) {
+    if (hoveredLocator) {
+        await hover(page, hoveredLocator);
+        hoveredLocator = null;
+    }
+}
+
+async function fill(page, field, value) {
+    let locator;
+    if (typeof field === 'string') {
+        const selector = `input[name="${field}"]`;
+        locator = page.locator(selector);
+    } else {
+        locator = field;
+    }
+    await click(page, locator);
+    await locator.fill(value);
+    
+}
+
+module.exports = {
+    waitForCompleteLoad,
+    highlightedClick,
+    click,
+    hover,
+    fill,
+    rehover,
+    setClosePopups,
+    logTimestamp,
+    setBaseUrl
+};

package/src/wireframeComparison.js

@@ -0,0 +1,225 @@
+import { expect } from '@playwright/test';
+
+function histogramDiff(a, b) {
+    return a.reduce((sum, val, i) => sum + Math.abs(val - b[i]), 0);
+}
+
+function calculateBoundingBoxDistance(rect1, rect2) {
+    return Math.max(Math.abs(rect1.left - rect2.left),
+        Math.abs(rect1.right - rect2.right),
+        Math.abs(rect1.top - rect2.top),
+        Math.abs(rect1.bottom - rect2.bottom));
+}
+
+function createPairings(currentElements, baselineElements) {
+    const pairings = [];
+    
+    for (let currentIndex = 0; currentIndex < currentElements.length; currentIndex++) {
+        for (let baselineIndex = 0; baselineIndex < baselineElements.length; baselineIndex++) {
+            const distance = calculateBoundingBoxDistance(
+                currentElements[currentIndex].boundingRect,
+                baselineElements[baselineIndex].boundingRect
+            );
+            
+            pairings.push({
+                currentIndex,
+                baselineIndex,
+                distance
+            });
+        }
+    }
+
+    pairings.sort((a, b) => a.distance - b.distance);
+
+    const usedCurrentIndices = new Set();
+    const usedBaselineIndices = new Set();
+    const matchedPairs = [];
+    
+    for (const pairing of pairings) {
+        if (!usedCurrentIndices.has(pairing.currentIndex) && !usedBaselineIndices.has(pairing.baselineIndex)) {
+            usedCurrentIndices.add(pairing.currentIndex);
+            usedBaselineIndices.add(pairing.baselineIndex);
+            matchedPairs.push(pairing);
+        }
+    }
+    
+    const unmatchedCurrent = [];
+    for (let i = 0; i < currentElements.length; i++) {
+        if (!usedCurrentIndices.has(i)) {
+            unmatchedCurrent.push(i);
+        }
+    }
+    
+    const unmatchedBaseline = [];
+    for (let i = 0; i < baselineElements.length; i++) {
+        if (!usedBaselineIndices.has(i)) {
+            unmatchedBaseline.push(i);
+        }
+    }
+    
+    return {
+        matchedPairs,
+        unmatchedCurrent,
+        unmatchedBaseline
+    };
+}
+
+function compareBoundingBoxes(baselineRect, currentRect, tolerance = 10, strictPosition = true) {
+    const differences = [];
+
+    if (strictPosition) {
+        const boundingBoxDifference = calculateBoundingBoxDistance(baselineRect, currentRect)
+        //expect.soft(boundingBoxDifference).toBeLessThanOrEqual(tolerance)
+        if (boundingBoxDifference > tolerance) {
+            differences.push({
+                type: "layout_shift",
+                difference: boundingBoxDifference
+            });
+        }
+    } else {
+        const baselineWidth = baselineRect.right - baselineRect.left;
+        const baselineHeight = baselineRect.bottom - baselineRect.top;
+        const currentWidth = currentRect.right - currentRect.left;
+        const currentHeight = currentRect.bottom - currentRect.top;
+        const sizeDiff = Math.max(
+            Math.abs(baselineWidth - currentWidth),
+            Math.abs(baselineHeight - currentHeight)
+        );
+        if (sizeDiff > tolerance) {
+            differences.push({
+                type: "size_mismatch",
+                difference: sizeDiff
+            });
+        }
+    }
+    
+    return differences;
+}
+
+function compareTexts(baselineTexts, currentTexts, strictPosition = true) {
+    const { matchedPairs, unmatchedCurrent, unmatchedBaseline } = createPairings(currentTexts, baselineTexts);
+    
+    for (const pairing of matchedPairs) {
+        const baselineText = baselineTexts[pairing.baselineIndex];
+        const currentText = currentTexts[pairing.currentIndex];
+        currentText.differences = [];
+
+        if (baselineText.text !== currentText.text) {
+            //expect.soft(currentText.text).toEqual(baselineText.text);
+            currentText.differences.push({
+                type: 'text_mismatch',
+                baseline: baselineText.text,
+                current: currentText.text,
+            });
+        } else {
+            const boundingBoxDifferences = compareBoundingBoxes(
+                baselineText.boundingRect,
+                currentText.boundingRect,
+                10,
+                strictPosition
+            );
+            currentText.differences = currentText.differences.concat(boundingBoxDifferences);
+        }
+    }
+
+    for (const currentIndex of unmatchedCurrent) {
+        const currentText = currentTexts[currentIndex];
+        currentText.differences = [{
+            type: 'extra_text',
+        }];
+    }
+
+    for (const baselineIndex of unmatchedBaseline) {
+        const baselineText = baselineTexts[baselineIndex];
+        currentTexts.push(baselineText);
+        baselineText.differences = [{
+            type: 'missing_text',
+        }];
+    }
+
+    for (const currentText of currentTexts) {
+        if (currentText.differences?.length === 0) {
+            currentText.differences = undefined
+        }
+    }
+}
+
+function compareElements(baselineElement, currentElement, strictPosition = true) {
+    currentElement.differences = compareBoundingBoxes(
+        baselineElement.boundingRect,
+        currentElement.boundingRect,
+        10,
+        strictPosition
+    );
+
+    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',
+            });
+        }
+    }
+    
+    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);
+    }
+}
+
+function compareWireframes(baselineWireframe, currentWireframe) {
+    const maxSelectorCount = Math.max(
+        baselineWireframe.elementGroups.length,
+        currentWireframe.elementGroups.length
+    );
+    expect(currentWireframe.elementGroups.length, 'Number of element groups in the layout should be the same.').toEqual(baselineWireframe.elementGroups.length);
+    
+    for (let i = 0; i < maxSelectorCount; i++) {
+        const baselineElementGroup = baselineWireframe.elementGroups[i];
+        const currentElementGroup = currentWireframe.elementGroups[i];
+
+        expect(baselineElementGroup.selector).toEqual(currentElementGroup.selector);
+
+        const strictPosition = currentElementGroup.strictPosition !== false;
+
+        //TODO: REMOVE later
+        if (currentElementGroup.differences?.length === 0) {
+            currentElementGroup.differences = undefined
+        }
+        
+        const { matchedPairs, unmatchedCurrent, unmatchedBaseline } = createPairings(
+            currentElementGroup.elements,
+            baselineElementGroup.elements
+        );
+
+        for (const pairing of matchedPairs) {
+            const baselineElement = baselineElementGroup.elements[pairing.baselineIndex];
+            const currentElement = currentElementGroup.elements[pairing.currentIndex];
+            compareElements(baselineElement, currentElement, strictPosition);
+            if (currentElement.differences?.length === 0) {
+                currentElement.differences = undefined
+            }
+        }
+        
+        for (const currentIndex of unmatchedCurrent) {
+            const currentElement = currentElementGroup.elements[currentIndex];
+            currentElement.differences = [{
+                type: 'extra_element',
+            }];
+        }
+        
+        for (const baselineIndex of unmatchedBaseline) {
+            const baselineElement = baselineElementGroup.elements[baselineIndex];
+            currentElementGroup.elements.push(baselineElement);
+            baselineElement.differences = [{
+                type: 'missing_element',
+            }];
+        }
+    }
+
+    return currentWireframe;
+}
+
+export { compareWireframes, compareElements, compareTexts, compareBoundingBoxes, createPairings, histogramDiff };

package/src/wireframeStability.js

@@ -0,0 +1,157 @@
+
+import { logTimestamp } from './testUtils.js';
+
+function collectTexts(wireframeData) {
+    const texts = [];
+    for (const elementGroup of wireframeData) {
+        for (const element of elementGroup.elements || []) {
+            for (const textEntry of element.texts || []) {
+                texts.push(textEntry.text);
+            }
+        }
+    }
+    return texts;
+}
+
+function countTextDifferences(previousWireframeData, currentWireframeData) {
+    const previousTexts = collectTexts(previousWireframeData);
+    const currentTexts = collectTexts(currentWireframeData);
+
+    const previousCounts = new Map();
+    for (const text of previousTexts) {
+        previousCounts.set(text, (previousCounts.get(text) || 0) + 1);
+    }
+
+    const currentCounts = new Map();
+    for (const text of currentTexts) {
+        currentCounts.set(text, (currentCounts.get(text) || 0) + 1);
+    }
+
+    const allTexts = new Set([...previousCounts.keys(), ...currentCounts.keys()]);
+
+    let differenceCount = 0;
+    for (const text of allTexts) {
+        const previousCount = previousCounts.get(text) || 0;
+        const currentCount = currentCounts.get(text) || 0;
+        differenceCount += Math.abs(previousCount - currentCount);
+    }
+
+    return differenceCount;
+}
+
+function findGroupsWithDifferentElementCount(previousWireframeData, currentWireframeData) {
+    const groupsWithDifference = [];
+
+    const groupCount = Math.max(previousWireframeData.length, currentWireframeData.length);
+    for (let groupIndex = 0; groupIndex < groupCount; groupIndex++) {
+        const previousGroup = previousWireframeData[groupIndex];
+        const currentGroup = currentWireframeData[groupIndex];
+
+        const previousElementCount = (previousGroup && previousGroup.elements) ? previousGroup.elements.length : 0;
+        const currentElementCount = (currentGroup && currentGroup.elements) ? currentGroup.elements.length : 0;
+
+        if (previousElementCount !== currentElementCount) {
+            const groupSelector = (currentGroup && currentGroup.selector) ||
+                (previousGroup && previousGroup.selector) ||
+                `index ${groupIndex}`;
+            groupsWithDifference.push({
+                groupIndex: groupIndex,
+                selector: groupSelector,
+                previousElementCount: previousElementCount,
+                currentElementCount: currentElementCount
+            });
+        }
+    }
+
+    return groupsWithDifference;
+}
+
+function findEmptyGroups(wireframeData) {
+    const emptyGroups = [];
+
+    for (let groupIndex = 0; groupIndex < wireframeData.length; groupIndex++) {
+        const group = wireframeData[groupIndex];
+        const elementCount = (group && group.elements) ? group.elements.length : 0;
+
+        if (elementCount < 1) {
+            const groupSelector = (group && group.selector) || `index ${groupIndex}`;
+            emptyGroups.push({
+                groupIndex: groupIndex,
+                selector: groupSelector
+            });
+        }
+    }
+
+    return emptyGroups;
+}
+
+function getBoundingRectSize(boundingRect) {
+    const width = boundingRect.right - boundingRect.left;
+    const height = boundingRect.bottom - boundingRect.top;
+    return width * height;
+}
+
+function sumBoundingBoxSizeDifference(previousWireframeData, currentWireframeData) {
+    let totalSizeDifference = 0;
+
+    for (let groupIndex = 0; groupIndex < previousWireframeData.length; groupIndex++) {
+        const previousElements = previousWireframeData[groupIndex].elements || [];
+        const currentElements = currentWireframeData[groupIndex].elements || [];
+
+        for (let elementIndex = 0; elementIndex < previousElements.length; elementIndex++) {
+            const previousSize = getBoundingRectSize(previousElements[elementIndex].boundingRect);
+            const currentSize = getBoundingRectSize(currentElements[elementIndex].boundingRect);
+            totalSizeDifference += Math.abs(previousSize - currentSize);
+        }
+    }
+
+    return totalSizeDifference;
+}
+
+function sumBoundingBoxSize(wireframeData) {
+    let totalSize = 0;
+
+    for (const elementGroup of wireframeData) {
+        for (const element of elementGroup.elements || []) {
+            totalSize += getBoundingRectSize(element.boundingRect);
+        }
+    }
+
+    return totalSize;
+}
+
+function areWireframesStable(previousWireframeData, currentWireframeData) {
+    const emptyGroups = findEmptyGroups(currentWireframeData);
+
+    if (emptyGroups.length > 0) {
+        for (const group of emptyGroups) {
+            logTimestamp(`Wireframe group '${group.selector}' has no elements.`);
+        }
+        return false;
+    }
+
+    const groupsWithDifferentElementCount = findGroupsWithDifferentElementCount(previousWireframeData, currentWireframeData);
+
+    if (groupsWithDifferentElementCount.length > 0) {
+        for (const group of groupsWithDifferentElementCount) {
+            logTimestamp(`Wireframe element count mismatch in group '${group.selector}' - previous: ${group.previousElementCount} current: ${group.currentElementCount}.`);
+        }
+        return false;
+    }
+
+    const textDifferences = countTextDifferences(previousWireframeData, currentWireframeData);
+
+    if (textDifferences !== 0) {
+        logTimestamp(`Wireframe text differences: ${textDifferences}`)
+        return false;
+    }
+
+    const sizeDifference = sumBoundingBoxSizeDifference(previousWireframeData, currentWireframeData);
+    const previousTotalSize = sumBoundingBoxSize(previousWireframeData);
+    const allowedSizeDifference = previousTotalSize * 0.03;
+
+    logTimestamp(`Wireframe bounding box size difference: ${sizeDifference} (allowed: ${allowedSizeDifference}).`)
+    return sizeDifference <= allowedSizeDifference;
+}
+
+export { areWireframesStable };

package/src/wireframeUtils.js

@@ -0,0 +1,268 @@
+import fs from 'fs';
+import path from 'path';
+import { logTimestamp } from './testUtils.js';
+import sharp from 'sharp';
+import { areWireframesStable } from './wireframeStability.js';
+
+async function getRGBHistogramFromBuffer(buffer) {
+    const {data, info} = await sharp(buffer)
+        .raw()
+        .toBuffer({resolveWithObject: true});
+
+    const histogram = new Array(48).fill(0);
+    const pixelCount = info.width * info.height;
+
+    for (let i = 0; i < data.length; i += info.channels) {
+        histogram[Math.floor(data[i] / 16)]++;
+        histogram[Math.floor(data[i + 1] / 16) + 16]++;
+        histogram[Math.floor(data[i + 2] / 16) + 32]++;
+    }
+
+    for (let i = 0; i < 48; i++) {
+        histogram[i] = Math.round((histogram[i] / pixelCount) * 100);
+    }
+
+    return histogram;
+}
+
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+
+async function extractWireframe(page, elementGroups) {
+    const wireframeData = await page.evaluate(async ({elementGroups}) => {
+
+        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;
+        }
+
+
+        for (const elementGroup of elementGroups) {
+            elementGroup.strictPosition = elementGroup.strictPosition !== false;
+            elementGroup.elements = [];
+
+            let index = 0;
+            const matchedElements = document.querySelectorAll(elementGroup.selector);
+
+            for (const element of matchedElements) {
+                if (!isElementVisible(element))
+                    continue;
+
+
+                const texts = [];
+
+                function getElementsWithDirectText(root, textIgnoreClasses) {
+                    const results = [];
+                    const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, {
+                        acceptNode: node =>
+                            node.nodeValue.trim()
+                                ? NodeFilter.FILTER_ACCEPT
+                                : NodeFilter.FILTER_REJECT
+                    });
+
+                    while (walker.nextNode()) {
+                        if (walker.currentNode.parentElement.classList.contains('screen-reader-text'))
+                            continue;
+
+                        if (textIgnoreClasses) {
+                            let ignored = false;
+                            console.log(textIgnoreClasses);
+                            let parent = walker.currentNode.parentElement;
+                            while (parent != null && !ignored) {
+                                for (const className of parent.classList) {
+                                    if (textIgnoreClasses.includes(className)) {
+                                        ignored = true;
+                                        break;
+                                    }
+                                }
+                                parent = parent.parentElement;
+                            }
+                            if (ignored)
+                                continue;
+                        }
+
+                        if (['select', 'option', 'input'].includes(walker.currentNode.parentElement.tagName))
+                            continue;
+
+                        if (!results.includes(walker.currentNode)) results.push(walker.currentNode);
+                    }
+
+                    return results;
+                }
+
+                if (elementGroup.type === 'text') {
+
+                    const descendantArray = getElementsWithDirectText(element, elementGroup.textIgnoreClasses)
+
+                    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)
+                        });
+                    }
+                }
+
+                elementGroup.elements.push({
+                    index: index,
+                    boundingRect: createBoundingRect(element),
+                    texts: texts,
+                    type: elementGroup.type
+                });
+                index += 1;
+            }
+        }
+
+        return elementGroups;
+    }, {elementGroups});
+
+    const scrollPosition = await page.evaluate(() => ({
+        x: window.scrollX,
+        y: window.scrollY
+    }));
+
+    for (const elementGroup of wireframeData) {
+        for (const element of elementGroup.elements) {
+            if (element.type === 'image') {
+                const locator = page.locator(elementGroup.selector).nth(element.index);
+                await locator.waitFor({state: 'visible'});
+
+                try {
+
+                    await page.waitForFunction((el) => {
+                        const images = Array.from(el.querySelectorAll('img'));
+                        if (images.length === 0) return true;
+                        return images.every(img => img.complete && img.naturalWidth > 0);
+                    }, await locator.elementHandle(), {timeout: 3000});
+                } catch {
+                    logTimestamp('could not load images for ' + elementGroup.selector)
+                }
+                try {
+                    const screenshot = await locator.screenshot({timeout: 3000});
+                    element.histogram = await getRGBHistogramFromBuffer(screenshot);
+                } catch {
+                    element.type = 'box'
+                }
+            }
+        }
+    }
+
+    await page.evaluate(({scrollPosition}) => {
+        window.scrollTo(scrollPosition.x, scrollPosition.y);
+    }, {scrollPosition});
+    return wireframeData;
+}
+
+function cloneElementGroups(elementGroups) {
+    return elementGroups.map(elementGroup => ({...elementGroup, elements: undefined}));
+}
+
+async function extractStableWireframe(page, elementGroups, retryDelay, maxRetryCount) {
+    let previousWireframeData = null;
+    let currentWireframeData = null;
+
+    for (let attempt = 0; attempt < maxRetryCount; attempt++) {
+        const extractionStartTime = Date.now();
+        currentWireframeData = await extractWireframe(page, cloneElementGroups(elementGroups));
+        const extractionDuration = Date.now() - extractionStartTime;
+        logTimestamp(`Wireframe candidate captured after ${extractionDuration/1000} seconds.`)
+
+        if (previousWireframeData !== null &&
+            areWireframesStable(previousWireframeData, currentWireframeData)) {
+            logTimestamp(`Wireframe stabilized after ${attempt + 1} extraction(s)`);
+            return currentWireframeData;
+        }
+
+        previousWireframeData = currentWireframeData;
+
+        if (attempt < maxRetryCount - 1) {
+            const remainingDelay = Math.max(0, retryDelay - extractionDuration);
+            if (remainingDelay > 0)
+                await delay(remainingDelay);
+        }
+    }
+
+    logTimestamp(`Wireframe did not stabilize within ${maxRetryCount} extraction(s)`);
+    return currentWireframeData;
+}
+
+async function expectWireframe(page, elementGroups, configName, outputFile, outputName, retryDelay = 1000, maxRetryCount = 10) {
+        logTimestamp(`Starting wireframe capture for: ${outputFile}`);
+    const wireframeData = await extractStableWireframe(page, elementGroups, retryDelay, maxRetryCount);
+
+    const userType = process.env.USER_TYPE;
+    const deviceType = process.env.DEVICE_TYPE;
+    const testType = process.env.TEST_TYPE;
+
+    const wireframeOutput = {
+        name: outputName,
+        timestamp: new Date().toISOString(),
+        deviceType: process.env.DEVICE_TYPE,
+        userType: process.env.USER_TYPE,
+        elementGroups: wireframeData
+    };
+
+    const fileName = `${outputFile}.json`;
+    const filePath = path.join(process.cwd(), 'wireframes', 'test', testType, configName, deviceType, userType, fileName);
+    const fileDir = path.dirname(filePath);
+    fs.mkdirSync(fileDir, {recursive: true});
+    fs.writeFileSync(filePath, JSON.stringify(wireframeOutput, null, 2));
+    logTimestamp(`Wireframe captured and saved to: ${fileName}`);
+
+    const screenshotPath = path.join(fileDir, `${outputFile}.png`);
+    await page.screenshot({ path: screenshotPath });
+    logTimestamp(`Wireframe screenshot saved to: ${screenshotPath}`);
+
+    return {wireframeOutput, screenshotPath};
+}
+
+export { expectWireframe, getRGBHistogramFromBuffer };