comparadise-utils 0.0.9 → 0.0.11

package/dist/files.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Creates a file path that is relative to the root
+ * @param {string} type - Value to append to fileName
+ * @param {string} path - (optional) FileName which corresponds to a module Id
+ * returns a string of just the prefix or the fileName prepended by the prefix
+ */
+export declare function createImageFileName(path: string, type: string): string;

package/dist/files.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createImageFileName = void 0;
+/**
+ * Creates a file path that is relative to the root
+ * @param {string} type - Value to append to fileName
+ * @param {string} path - (optional) FileName which corresponds to a module Id
+ * returns a string of just the prefix or the fileName prepended by the prefix
+ */
+function createImageFileName(path, type) {
+    let newPath = path;
+    if (path.startsWith('/')) {
+        newPath = `.${path}`;
+    }
+    return `${newPath}/${type}.png`;
+}
+exports.createImageFileName = createImageFileName;

package/dist/images.d.ts

@@ -1,4 +1,10 @@
 import { PNG } from 'pngjs';
+/**
+ * Compares a base and new image and returns the pixel difference
+ * and diff PNG for writing the diff image to.
+ * @param {string} basePath - Full file path to base image
+ * @param {string} actualPath - Full file path to new image
+ */
 export declare function getDiffPixels(basePath: string, actualPath: string): {
     diffPixels: number;
     diff: PNG;

package/dist/images.js

@@ -33,11 +33,19 @@ const pixelmatch_1 = __importDefault(require("pixelmatch"));
 const PIXELMATCH_OPTIONS = {
     threshold: 0.3
 };
+/**
+ * Helper function to create reusable image resizer
+ */
 const createImageResizer = (width, height) => (source) => {
     const resized = new pngjs_1.PNG({ width, height, fill: true });
     pngjs_1.PNG.bitblt(source, resized, 0, 0, source.width, source.height, 0, 0);
     return resized;
 };
+/**
+ * Fills new area added after resize with transparent black color.
+ * I like idea of checker board pattern, but it seems to be too complicated
+ * to implement considering how low-level pngjs API is.
+ */
 const fillSizeDifference = (width, height) => (image) => {
     const inArea = (x, y) => y > height || x > width;
     for (let y = 0; y < image.height; y++) {
@@ -53,6 +61,10 @@ const fillSizeDifference = (width, height) => (image) => {
     }
     return image;
 };
+/**
+ * Aligns images sizes to biggest common value
+ * and fills new pixels with transparent pixels
+ */
 function alignImagesToSameSize(firstImage, secondImage) {
     // Keep original sizes to fill extended area later
     const firstImageWidth = firstImage.width;
@@ -70,6 +82,12 @@ function alignImagesToSameSize(firstImage, secondImage) {
         fillSizeDifference(secondImageWidth, secondImageHeight)(resizedSecond)
     ];
 }
+/**
+ * Compares a base and new image and returns the pixel difference
+ * and diff PNG for writing the diff image to.
+ * @param {string} basePath - Full file path to base image
+ * @param {string} actualPath - Full file path to new image
+ */
 function getDiffPixels(basePath, actualPath) {
     const rawBase = pngjs_1.PNG.sync.read(fs.readFileSync(basePath));
     const rawActual = pngjs_1.PNG.sync.read(fs.readFileSync(actualPath));

package/dist/index.d.ts

@@ -1,2 +1,9 @@
 /// <reference types="cypress" />
 export declare function setupVisualTests(on: Cypress.PluginEvents, config: Cypress.PluginConfigOptions): Cypress.PluginConfigOptions;
+declare global {
+    namespace Cypress {
+        interface Chainable {
+            matchScreenshot(args?: MatchScreenshotArgs): Chainable;
+        }
+    }
+}

package/dist/index.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.setupVisualTests = void 0;
 const screenshots_1 = require("./screenshots");
 function setupVisualTests(on, config) {
+    on('after:screenshot', screenshots_1.onAfterScreenshot);
     on('task', {
         baseExists: screenshots_1.baseExists,
         compareScreenshots: screenshots_1.compareScreenshots,
+        createNewScreenshot: screenshots_1.createNewScreenshot,
         log: (message) => {
             console.log(message);
             return null;

package/dist/match-screenshot.d.ts

@@ -1,13 +1,15 @@
 /// <reference types="cypress" />
-export type MatchScreenshotArgs = {
+declare const PREFIX_DIFFERENTIATOR = "___";
+declare const SUFFIX_TEST_IDENTIFIER = ".spec.ts";
+declare const SCREENSHOTS_FOLDER_NAME = "screenshots";
+declare function forceFont(): false | HTMLStyleElement;
+declare function getTestFolderPathFromScripts(rawName?: string): {
+    name: string;
+    screenshotsFolder: string;
+};
+interface MatchScreenshotArgs {
     rawName?: string;
     options?: Partial<Cypress.ScreenshotOptions>;
-};
-export declare function matchScreenshot(subject: Cypress.JQueryWithSelector | Window | Document | void, args?: MatchScreenshotArgs): void;
-declare global {
-    namespace Cypress {
-        interface Chainable {
-            matchScreenshot(args?: MatchScreenshotArgs): Chainable;
-        }
-    }
 }
+declare function verifyImages(): void;
+declare function matchScreenshot(subject: Cypress.JQueryWithSelector | Window | Document | void, args?: MatchScreenshotArgs): void;

package/dist/match-screenshot.js

@@ -1,6 +1,32 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchScreenshot = void 0;
+const PREFIX_DIFFERENTIATOR = '___';
+const SUFFIX_TEST_IDENTIFIER = '.spec.ts';
+const SCREENSHOTS_FOLDER_NAME = 'screenshots';
+function forceFont() {
+    const iframe = window.parent.document.querySelector('iframe');
+    const contentDocument = iframe && iframe.contentDocument;
+    if (contentDocument) {
+        const style = contentDocument.createElement('style');
+        style.type = 'text/css';
+        style.appendChild(contentDocument.createTextNode('* { font-family: Arial !important; }'));
+        contentDocument.head.appendChild(style);
+        return style;
+    }
+    return false;
+}
+function getTestFolderPathFromScripts(rawName) {
+    const relativeTestPath = Cypress.spec.relative;
+    if (!relativeTestPath) {
+        throw new Error('❌ Could not find matching script in the Cypress DOM to infer the test folder path');
+    }
+    const testName = relativeTestPath.substring(relativeTestPath.lastIndexOf('/') + 1, relativeTestPath.lastIndexOf(SUFFIX_TEST_IDENTIFIER));
+    const name = rawName || testName;
+    const screenshotsFolder = `${SCREENSHOTS_FOLDER_NAME}/${relativeTestPath.substring(0, relativeTestPath.lastIndexOf(testName))}${name}`;
+    return {
+        name,
+        screenshotsFolder
+    };
+}
 function verifyImages() {
     if (Cypress.$('img:visible').length > 0) {
         cy.document()
@@ -16,49 +42,34 @@ function verifyImages() {
         });
     }
 }
-function forceFont() {
-    const iframe = window.parent.document.querySelector('iframe');
-    const contentDocument = iframe && iframe.contentDocument;
-    if (contentDocument) {
-        const style = contentDocument.createElement('style');
-        style.type = 'text/css';
-        style.appendChild(contentDocument.createTextNode('* { font-family: Arial !important; }'));
-        contentDocument.head.appendChild(style);
-    }
-}
 function matchScreenshot(subject, args) {
-    const { rawName, options = {} } = args || {};
+    const { rawName, options = {} } = args ?? {};
+    // Set up screen
     forceFont();
+    // Making sure each image is visible before taking screenshots
     verifyImages();
-    const screenshotsFolder = 'cypress/screenshots';
-    const testPath = Cypress.spec.relative;
-    const lastSlashIndex = testPath.lastIndexOf('/');
-    const testPathWithoutFileName = testPath.substring(0, lastSlashIndex);
-    const testFileName = testPath.substring(lastSlashIndex + 1);
-    const testFileNameWithoutExtension = testFileName.split('.')[0];
-    const testName = rawName || testFileNameWithoutExtension;
-    const screenshotPath = `${screenshotsFolder}/${testPathWithoutFileName}/${testName}`;
-    cy.task('baseExists', screenshotPath).then(hasBase => {
-        if (typeof hasBase !== 'boolean')
-            throw new Error('Result of baseExists task was not a boolean.');
+    const { name, screenshotsFolder } = getTestFolderPathFromScripts(rawName);
+    cy.task('baseExists', screenshotsFolder).then(hasBase => {
+        const type = 'new';
         const target = subject ? cy.wrap(subject) : cy;
-        // Cypress prepends the configured screenshotsFolder automatically here, so we must omit it
-        target.screenshot(`${testPathWithoutFileName}/${testName}/new`, { ...options, overwrite: true });
+        // For easy slicing of path ignoring the root screenshot folder
+        target.screenshot(`${PREFIX_DIFFERENTIATOR}${screenshotsFolder}/${type}`, options);
         if (!hasBase) {
-            cy.task('log', `❌ A new base image was created at ${screenshotPath}. Add this as a new base image via Comparadise!`);
+            cy.task('createNewScreenshot', screenshotsFolder).then(() => {
+                cy.task('log', `✅ A new base image was created for ${name}. Create this as a new base image via Comparadise!`);
+            });
             return;
         }
-        cy.task('compareScreenshots', screenshotPath).then(diffPixels => {
-            if (typeof diffPixels !== 'number')
-                throw new Error('Result of compareScreenshots task was not a number.');
+        cy.task('compareScreenshots', screenshotsFolder).then(diffPixels => {
             if (diffPixels === 0) {
-                cy.log('✅ Actual image was the same as base.');
-            }
-            else {
-                cy.task('log', `❌ Actual image of differed by ${diffPixels} pixels.`);
+                cy.log(`✅ Actual image of ${name} was the same as base`);
+                return null;
             }
+            const screenshotUrl = Cypress.env('BUILD_URL') ? `${Cypress.env('BUILD_URL')}artifact/${screenshotsFolder}` : screenshotsFolder;
+            cy.task('log', `❌ Actual image of ${name} differed by ${diffPixels} pixels.
+             See the diff image for more details >>  ${screenshotUrl}/diff.png`);
         });
+        return null;
     });
 }
-exports.matchScreenshot = matchScreenshot;
 Cypress.Commands.add('matchScreenshot', { prevSubject: ['optional', 'element', 'window', 'document'] }, matchScreenshot);

package/dist/screenshots.d.ts

@@ -1,2 +1,20 @@
-export declare function baseExists(screenshotFolder: string): boolean;
+/// <reference types="cypress" />
+/**
+ * Checks if a base image exists
+ * @param path - Folder path where you can find the base.png image
+ * @returns true if path/base.png exists, false if not.
+ */
+export declare function baseExists(path: string): boolean;
+export declare function createNewScreenshot(screenshotFolder: string): null;
+/**
+ * Runs a visual regression test.
+ * @param screenshotFolder - Full screenshots folder where the base/new/diff
+ *                           images will be compared and written to.
+ */
 export declare function compareScreenshots(screenshotFolder: string): number;
+/**
+ * Renames all root cypress screenshots to where the test was actually run.
+ * Should NOT be used standalone. Works with the matchScreenshot task.
+ * @param {Cypress.ScreenshotDetails} details
+ */
+export declare function onAfterScreenshot(details: Cypress.ScreenshotDetails): Promise<Cypress.AfterScreenshotReturnObject>;

package/dist/screenshots.js

@@ -23,29 +23,49 @@ var __importStar = (this && this.__importStar) || function (mod) {
     return result;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.compareScreenshots = exports.baseExists = void 0;
+exports.onAfterScreenshot = exports.compareScreenshots = exports.createNewScreenshot = exports.baseExists = void 0;
 const fs = __importStar(require("fs"));
-const path_1 = require("path");
 const pngjs_1 = require("pngjs");
 const images_1 = require("./images");
-function baseExists(screenshotFolder) {
-    const fileName = (0, path_1.join)(screenshotFolder, 'base.png');
+const files_1 = require("./files");
+/**
+ * Checks if a base image exists
+ * @param path - Folder path where you can find the base.png image
+ * @returns true if path/base.png exists, false if not.
+ */
+function baseExists(path) {
+    const fileName = (0, files_1.createImageFileName)(path, 'base');
     const exists = fs.existsSync(fileName);
     if (!exists) {
-        console.log(`Base image does not exist at ${fileName}. This means a new one will be created. If your base should exist, something went wrong.`);
+        console.log('Base image does not exist. This means a new one will be created. If your base should exist, something went wrong.');
     }
     return exists;
 }
 exports.baseExists = baseExists;
+function createNewScreenshot(screenshotFolder) {
+    const newImage = pngjs_1.PNG.sync.read(fs.readFileSync((0, files_1.createImageFileName)(screenshotFolder, 'new')));
+    fs.writeFile((0, files_1.createImageFileName)(screenshotFolder, 'new'), pngjs_1.PNG.sync.write(newImage), err => {
+        if (err) {
+            console.error('❌Unable to create new.png', err);
+        }
+    });
+    return null;
+}
+exports.createNewScreenshot = createNewScreenshot;
+/**
+ * Runs a visual regression test.
+ * @param screenshotFolder - Full screenshots folder where the base/new/diff
+ *                           images will be compared and written to.
+ */
 function compareScreenshots(screenshotFolder) {
-    const basePath = (0, path_1.join)(screenshotFolder, 'base.png');
-    const actualPath = (0, path_1.join)(screenshotFolder, 'new.png');
+    const basePath = (0, files_1.createImageFileName)(screenshotFolder, 'base');
+    const actualPath = (0, files_1.createImageFileName)(screenshotFolder, 'new');
     const { diffPixels, diff } = (0, images_1.getDiffPixels)(basePath, actualPath);
     if (diffPixels) {
         // Create diff.png next to base and new for review
-        fs.writeFile((0, path_1.join)(screenshotFolder, 'diff.png'), pngjs_1.PNG.sync.write(diff), err => {
+        fs.writeFile((0, files_1.createImageFileName)(screenshotFolder, 'diff'), pngjs_1.PNG.sync.write(diff), err => {
             if (err) {
-                console.error('❌ Diff exists but unable to create diff.png', err);
+                console.error('❌Diff exists but unable to create diff.png', err);
             }
         });
     }
@@ -53,10 +73,49 @@ function compareScreenshots(screenshotFolder) {
         // Delete created new.png. Not needed if there's no diff
         fs.unlink(actualPath, err => {
             if (err) {
-                console.error('❌ No diff but unable to delete actualPath}', err);
+                console.error('❌No diff but unable to deleteactualPath}', err);
             }
         });
     }
     return diffPixels;
 }
 exports.compareScreenshots = compareScreenshots;
+/**
+ * Renames all root cypress screenshots to where the test was actually run.
+ * Should NOT be used standalone. Works with the matchScreenshot task.
+ * @param {Cypress.ScreenshotDetails} details
+ */
+function onAfterScreenshot(details) {
+    console.log('🧸 Screenshot was saved to:', details.path);
+    if (!details.path.match('cypress')) {
+        return Promise.resolve({});
+    }
+    const getNewPath = (path) => {
+        let newPath = path.slice(path.lastIndexOf('___') + 3);
+        console.log(newPath);
+        if (newPath.startsWith('/')) {
+            newPath = `.${newPath}`;
+        }
+        return newPath;
+    };
+    const newPath = getNewPath(details.path);
+    const newPathDir = newPath.substring(0, newPath.lastIndexOf('/'));
+    try {
+        fs.mkdirSync(newPathDir, { recursive: true });
+        console.log('🧸 No screenshot folder found in the package. Created new screenshot folder:', newPathDir);
+    }
+    catch (err) {
+        console.error('❌ Error creating new screenshot folder:', newPathDir, err);
+    }
+    return new Promise((resolve, reject) => {
+        fs.rename(details.path, newPath, err => {
+            if (err) {
+                reject(err);
+            }
+            // because we renamed/moved the image, resolve with the new path
+            // so it is accurate in the test results
+            resolve({ path: newPath });
+        });
+    });
+}
+exports.onAfterScreenshot = onAfterScreenshot;

package/package.json

@@ -29,5 +29,5 @@
     "build": "tsc",
     "postbuild": "echo \"require('./dist/match-screenshot');\" > commands.js"
   },
-  "version": "0.0.9"
+  "version": "0.0.11"
 }

package/dist/on-after-screenshot.d.ts

@@ -1,2 +0,0 @@
-/// <reference types="cypress" />
-export declare function onAfterScreenshot(details: Cypress.ScreenshotDetails): Promise<Cypress.AfterScreenshotReturnObject>;

package/dist/on-after-screenshot.js

@@ -1,51 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.onAfterScreenshot = void 0;
-const fs = __importStar(require("fs"));
-function onAfterScreenshot(details) {
-    console.log('🧸 Screenshot was saved to:', details.path);
-    if (!details.path.match('visual')) {
-        return Promise.resolve({});
-    }
-    const newPath = details.path.substring(details.path.lastIndexOf('cypress/screenshots'));
-    const newPathDir = newPath.substring(0, newPath.lastIndexOf('/'));
-    try {
-        fs.mkdirSync(newPathDir, { recursive: true });
-        console.log('🧸 No screenshot folder found in the package. Created new screenshot folder:', newPathDir);
-    }
-    catch (err) {
-        console.error('❌ Error creating new screenshot folder:', newPathDir, err);
-    }
-    return new Promise((resolve, reject) => {
-        fs.rename(details.path, newPath, err => {
-            if (err) {
-                reject(err);
-            }
-            resolve({ path: newPath });
-        });
-    });
-}
-exports.onAfterScreenshot = onAfterScreenshot;