flexysnap 0.1.3-alpha.1 → 0.1.4-alpha.1

package/package.json

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

package/src/annotateWireframe.js

@@ -16,6 +16,16 @@ function applyGrayscale(ctx, width, height) {
     ctx.putImageData(imageData, 0, 0);
 }
 
+function getScrollOffset(wireframe) {
+    const extractionScrollPosition = wireframe.scrollPosition || { x: 0, y: 0 };
+    const screenshotScrollPosition = wireframe.screenshotScrollPosition || extractionScrollPosition;
+
+    return {
+        offsetX: extractionScrollPosition.x - screenshotScrollPosition.x,
+        offsetY: extractionScrollPosition.y - screenshotScrollPosition.y
+    };
+}
+
 async function annotateWireframeFile(wireframeFile, screenshotFile) {
     if (!fs.existsSync(wireframeFile)) {
         console.error(`Wireframe file not found: ${wireframeFile}`);
@@ -40,6 +50,12 @@ async function annotateWireframeFile(wireframeFile, screenshotFile) {
     ctx.drawImage(screenshot, 0, 0);
     applyGrayscale(ctx, width, height);
 
+    const { offsetX, offsetY } = getScrollOffset(wireframe);
+
+    if (offsetX !== 0 || offsetY !== 0) {
+        console.log(`Compensating for scroll drift between extraction and screenshot: offsetX=${offsetX}, offsetY=${offsetY}`);
+    }
+
     const colors = {
         box: { fill: 'rgba(220, 160, 40, 0.4)', stroke: '#E6A500' },
         image: { fill: 'rgba(70, 180, 120, 0.4)', stroke: '#2EBC6F' },
@@ -52,16 +68,23 @@ async function annotateWireframeFile(wireframeFile, screenshotFile) {
     }
 
     function drawBoundingBox(rect, colorKey, dashed = false) {
-        const boxWidth = rect.right - rect.left;
-        const boxHeight = rect.bottom - rect.top;
+        const adjustedRect = {
+            left: rect.left + offsetX,
+            right: rect.right + offsetX,
+            top: rect.top + offsetY,
+            bottom: rect.bottom + offsetY
+        };
+
+        const boxWidth = adjustedRect.right - adjustedRect.left;
+        const boxHeight = adjustedRect.bottom - adjustedRect.top;
         const color = colors[colorKey];
 
         ctx.fillStyle = color.fill;
-        ctx.fillRect(rect.left, rect.top, boxWidth, boxHeight);
+        ctx.fillRect(adjustedRect.left, adjustedRect.top, boxWidth, boxHeight);
         ctx.strokeStyle = color.stroke;
         ctx.lineWidth = 2;
         ctx.setLineDash(dashed ? [6, 4] : []);
-        ctx.strokeRect(rect.left, rect.top, boxWidth, boxHeight);
+        ctx.strokeRect(adjustedRect.left, adjustedRect.top, boxWidth, boxHeight);
         ctx.setLineDash([]);
     }
 

package/src/index.js

@@ -23,4 +23,10 @@ export {
 
 export { areWireframesStable } from './wireframeStability.js';
 
-export { expectWireframe, getRGBHistogramFromBuffer } from './wireframeUtils.js';
+export { expectWireframe, getRGBHistogramFromBuffer } from './wireframeUtils.js';
+
+export {
+    setWireframeOutputRoot,
+    getWireframeOutputRoot,
+    resolveWireframeOutputDir
+} from './wireframeOutput.js';

package/src/wireframeOutput.js

@@ -0,0 +1,29 @@
+import path from 'path';
+
+let outputRoot = process.cwd();
+
+function setWireframeOutputRoot(rootPath) {
+    outputRoot = rootPath || process.cwd();
+}
+
+function getWireframeOutputRoot() {
+    return outputRoot;
+}
+
+function resolveWireframeOutputDir(outputDir) {
+    if (!outputDir || typeof outputDir !== 'string') {
+        throw new Error('resolveWireframeOutputDir requires a non-empty string outputDir.');
+    }
+
+    if (path.isAbsolute(outputDir)) {
+        return outputDir;
+    }
+
+    return path.join(outputRoot, outputDir);
+}
+
+export {
+    setWireframeOutputRoot,
+    getWireframeOutputRoot,
+    resolveWireframeOutputDir
+};

package/src/wireframeUtils.js

@@ -3,6 +3,9 @@ import path from 'path';
 import { logTimestamp } from './testUtils.js';
 import { loadImage, createCanvas } from 'canvas';
 import { areWireframesStable } from './wireframeStability.js';
+import { resolveWireframeOutputDir } from './wireframeOutput.js';
+
+const FLEXYSNAP_ELEMENT_ID_ATTRIBUTE = 'data-flexysnap-id';
 
 async function getRGBHistogramFromBuffer(buffer) {
     const image = await loadImage(buffer);
@@ -37,7 +40,7 @@ function delay(milliseconds) {
 }
 
 async function extractWireframe(page, elementGroups) {
-    const wireframeData = await page.evaluate(async ({elementGroups}) => {
+    const wireframeData = await page.evaluate(async ({elementGroups, elementIdAttribute}) => {
 
         function createBoundingRect(element) {
             const rect = element.getBoundingClientRect();
@@ -80,7 +83,8 @@ async function extractWireframe(page, elementGroups) {
         }
 
 
-        for (const elementGroup of elementGroups) {
+        for (let groupIndex = 0; groupIndex < elementGroups.length; groupIndex++) {
+            const elementGroup = elementGroups[groupIndex];
             elementGroup.strictPosition = elementGroup.strictPosition !== false;
             elementGroup.elements = [];
 
@@ -159,18 +163,26 @@ async function extractWireframe(page, elementGroups) {
                     }
                 }
 
-                elementGroup.elements.push({
+                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;
             }
         }
 
         return elementGroups;
-    }, {elementGroups});
+    }, {elementGroups, elementIdAttribute: FLEXYSNAP_ELEMENT_ID_ATTRIBUTE});
 
     const scrollPosition = await page.evaluate(() => ({
         x: window.scrollX,
@@ -179,8 +191,8 @@ async function extractWireframe(page, elementGroups) {
 
     for (const elementGroup of wireframeData) {
         for (const element of elementGroup.elements) {
-            if (element.type === 'image') {
-                const locator = page.locator(elementGroup.selector).nth(element.index);
+            if (element.type === 'image' && element.elementId) {
+                const locator = page.locator(`[${FLEXYSNAP_ELEMENT_ID_ATTRIBUTE}="${element.elementId}"]`);
                 await locator.waitFor({state: 'visible'});
 
                 try {
@@ -199,14 +211,28 @@ async function extractWireframe(page, elementGroups) {
                 } catch {
                     element.type = 'box'
                 }
+
+                delete element.elementId;
             }
         }
     }
 
-    await page.evaluate(({scrollPosition}) => {
-        window.scrollTo(scrollPosition.x, scrollPosition.y);
-    }, {scrollPosition});
-    return wireframeData;
+    await page.evaluate(({scrollPosition, elementIdAttribute}) => {
+        for (const el of document.querySelectorAll(`[${elementIdAttribute}]`)) {
+            el.removeAttribute(elementIdAttribute);
+        }
+        window.scrollTo({top: scrollPosition.y, left: scrollPosition.x, behavior: 'instant'});
+    }, {scrollPosition, elementIdAttribute: FLEXYSNAP_ELEMENT_ID_ATTRIBUTE});
+
+    try {
+        await page.waitForFunction((expectedScrollPosition) => {
+            return window.scrollX === expectedScrollPosition.x && window.scrollY === expectedScrollPosition.y;
+        }, scrollPosition, {timeout: 2000});
+    } catch {
+        logTimestamp('Scroll position did not settle back to the extraction position.');
+    }
+
+    return {wireframeData, scrollPosition};
 }
 
 function cloneElementGroups(elementGroups) {
@@ -216,17 +242,20 @@ function cloneElementGroups(elementGroups) {
 async function extractStableWireframe(page, elementGroups, retryDelay, maxRetryCount) {
     let previousWireframeData = null;
     let currentWireframeData = null;
+    let currentScrollPosition = null;
 
     for (let attempt = 0; attempt < maxRetryCount; attempt++) {
         const extractionStartTime = Date.now();
-        currentWireframeData = await extractWireframe(page, cloneElementGroups(elementGroups));
+        const extractionResult = await extractWireframe(page, cloneElementGroups(elementGroups));
+        currentWireframeData = extractionResult.wireframeData;
+        currentScrollPosition = extractionResult.scrollPosition;
         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;
+            return {wireframeData: currentWireframeData, scrollPosition: currentScrollPosition};
         }
 
         previousWireframeData = currentWireframeData;
@@ -239,37 +268,42 @@ async function extractStableWireframe(page, elementGroups, retryDelay, maxRetryC
     }
 
     logTimestamp(`Wireframe did not stabilize within ${maxRetryCount} extraction(s)`);
-    return currentWireframeData;
+    return {wireframeData: currentWireframeData, scrollPosition: currentScrollPosition};
 }
 
-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);
+async function expectWireframe(page, elementGroups, outputDir, outputFile, outputName, options = {}) {
+    const { retryDelay = 1000, maxRetryCount = 10, metadata = {} } = options;
+
+    logTimestamp(`Starting wireframe capture for: ${outputFile}`);
+    const { wireframeData, scrollPosition } = 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 screenshotScrollPosition = await page.evaluate(() => ({
+        x: window.scrollX,
+        y: window.scrollY
+    }));
 
     const wireframeOutput = {
         name: outputName,
         timestamp: new Date().toISOString(),
-        deviceType: process.env.DEVICE_TYPE,
-        userType: process.env.USER_TYPE,
-        elementGroups: wireframeData
+        scrollPosition,
+        screenshotScrollPosition,
+        elementGroups: wireframeData,
+        ...metadata
     };
 
+    const resolvedDir = resolveWireframeOutputDir(outputDir);
+    fs.mkdirSync(resolvedDir, {recursive: true});
+
     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});
+    const filePath = path.join(resolvedDir, fileName);
     fs.writeFileSync(filePath, JSON.stringify(wireframeOutput, null, 2));
     logTimestamp(`Wireframe captured and saved to: ${fileName}`);
 
-    const screenshotPath = path.join(fileDir, `${outputFile}.png`);
+    const screenshotPath = path.join(resolvedDir, `${outputFile}.png`);
     await page.screenshot({ path: screenshotPath });
     logTimestamp(`Wireframe screenshot saved to: ${screenshotPath}`);
 
-    return {wireframeOutput, screenshotPath};
+    return {wireframeOutput, screenshotPath, outputDir: resolvedDir};
 }
 
 export { expectWireframe, getRGBHistogramFromBuffer };