feat: auto clean unused files (FRSOURCE#124)

add metadata to images generated by the plugin
recreate fixture screenshots (add metadata)
add documentation info

closes FRSOURCE#118
BREAKING CHANGE: To use autocleanup feature you need to update all of the screenshots, best do it by running your test suite with cypress env 'pluginVisualRegressionUpdateImages' set to true.

Author: FRSgit

README.md

@@ -141,7 +141,16 @@ cy.matchImage();
 
 ## Example
 
-Still got troubles with installation? Have a look at [example directory of this repo](./example) to see how this plugin can be used in e2e or component-testing Cypress within your project.
+Still got troubles with installation? Have a look at [example directory of this repo](./example) to see how this plugin can be used in e2e or component-testing Cypress environment within your project.
+
+## Automatic clean up of unused images
+
+It's useful to remove screenshots generated by the visual regression plugin that are not used by any test anymore.
+Enable this feature via env variable and enjoy freed up storage space 🚀:
+
+```bash
+npx cypress run --env "pluginVisualRegressionCleanupUnusedImages=true"
+```
 
 ## Configuration
 

__tests__/fixtures/prepare-screenshot-for-cleanup.spec.cy.js

@@ -0,0 +1,6 @@
+describe('Cleanup test', () => {
+  it('Create screenshot to be removed', () => {
+    cy.visit('/');
+    cy.get('[data-testid="description"]').matchImage();
+  });
+});

__tests__/fixtures/screenshot.actual.png

@@ -145,6 +145,8 @@ __metadata:
   resolution: "@frsource/cypress-plugin-visual-regression-diff@portal:..::locator=example%40workspace%3A."
   dependencies:
     "@frsource/base64": 1.0.3
+    glob: ^8.0.3
+    meta-png: ^1.0.3
     move-file: 2.1.0
     pixelmatch: 5.3.0
     pngjs: 6.0.0
@@ -3380,7 +3382,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"glob@npm:^8.0.1":
+"glob@npm:^8.0.1, glob@npm:^8.0.3":
   version: 8.0.3
   resolution: "glob@npm:8.0.3"
   dependencies:
@@ -4502,6 +4504,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"meta-png@npm:^1.0.3":
+  version: 1.0.3
+  resolution: "meta-png@npm:1.0.3"
+  checksum: cc7e1e0950b149273eb127622d8079725855ca14fb5e0175a4f1a7946d7f4a1c92e78de9f44eb1b9fa339c60f43b099c5135dc06b218cf77879fbd0a7f6ecddb
+  languageName: node
+  linkType: hard
+
 "methods@npm:~1.1.2":
   version: 1.1.2
   resolution: "methods@npm:1.1.2"

__tests__/fixtures/screenshot.diff.png

@@ -68,6 +68,7 @@
     "@semantic-release/git": "10.0.1",
     "@semantic-release/npm": "9.0.1",
     "@semantic-release/release-notes-generator": "10.0.3",
+    "@types/glob": "^8.0.0",
     "@types/pixelmatch": "5.2.4",
     "@types/pngjs": "6.0.1",
     "@types/sharp": "0.31.0",
@@ -106,6 +107,8 @@
   ],
   "dependencies": {
     "@frsource/base64": "1.0.3",
+    "glob": "^8.0.3",
+    "meta-png": "^1.0.3",
     "move-file": "2.1.0",
     "pixelmatch": "5.3.0",
     "pngjs": "6.0.0",

__tests__/fixtures/screenshot.png

@@ -42,8 +42,6 @@ declare global {
   }
 }
 
-const nameCacheCounter: Record<string, number> = {};
-
 const constructCypressError = (log: Cypress.Log, err: Error) => {
   // only way to throw & log the message properly in Cypress
   // https://github.com/cypress-io/cypress/blob/5f94cad3cb4126e0567290b957050c33e3a78e3c/packages/driver/src/cypress/error_utils.ts#L214-L216
@@ -93,10 +91,7 @@ Cypress.Commands.add(
   { prevSubject: "optional" },
   (subject, options = {}) => {
     const $el = subject as JQuery<HTMLElement> | undefined;
-    let title = options.title || Cypress.currentTest.titlePath.join(" ");
-    if (typeof nameCacheCounter[title] === "undefined")
-      nameCacheCounter[title] = -1;
-    title += ` #${++nameCacheCounter[title]}`;
+    let title: string;
 
     const {
       scaleFactor,
@@ -110,17 +105,19 @@ Cypress.Commands.add(
 
     return cy
       .then(() =>
-        cy.task(
-          TASK.getScreenshotPath,
+        cy.task<{ screenshotPath: string; title: string }>(
+          TASK.getScreenshotPathInfo,
           {
-            title,
+            titleFromOptions:
+              options.title || Cypress.currentTest.titlePath.join(" "),
             imagesDir,
             specPath: Cypress.spec.relative,
           },
           { log: false }
         )
       )
-      .then((screenshotPath) => {
+      .then(({ screenshotPath, title: titleFromTask }) => {
+        title = titleFromTask;
         let imgPath: string;
         return ($el ? cy.wrap($el) : cy)
           .screenshot(screenshotPath as string, {

example/yarn.lock

@@ -1,3 +1,4 @@
+/* c8 ignore start */
 const PLUGIN_NAME = "cp-visual-regression-diff";
 export const LINK_PREFIX = `#${PLUGIN_NAME}-`;
 export const OVERLAY_CLASS = `${PLUGIN_NAME}-overlay`;
@@ -9,9 +10,13 @@ export enum FILE_SUFFIX {
 }
 
 export const TASK = {
-  getScreenshotPath: `${PLUGIN_NAME}-getScreenshotPath`,
+  getScreenshotPathInfo: `${PLUGIN_NAME}-getScreenshotPathInfo`,
   compareImages: `${PLUGIN_NAME}-compareImages`,
   approveImage: `${PLUGIN_NAME}-approveImage`,
+  cleanupImages: `${PLUGIN_NAME}-cleanupImages`,
   doesFileExist: `${PLUGIN_NAME}-doesFileExist`,
   /* c8 ignore next */
 };
+
+export const METADATA_KEY = "FRSOURCE_CPVRD_V";
+/* c8 ignore stop */

package.json

@@ -1,6 +1,27 @@
+import path from "path";
 import fs from "fs";
 import { PNG, PNGWithMetadata } from "pngjs";
 import sharp from "sharp";
+import { addMetadata, getMetadata } from "meta-png";
+import glob from "glob";
+import { version } from "../package.json";
+import { wasScreenshotUsed } from "./screenshotPath.utils";
+import { METADATA_KEY } from "./constants";
+
+export const addPNGMetadata = (png: Buffer) =>
+  addMetadata(png, METADATA_KEY, version /* c8 ignore next */);
+export const getPNGMetadata = (png: Buffer) =>
+  getMetadata(png, METADATA_KEY /* c8 ignore next */);
+export const isImageCurrentVersion = (png: Buffer) =>
+  getPNGMetadata(png) === version;
+export const isImageGeneratedByPlugin = (png: Buffer) =>
+  !!getPNGMetadata(png /* c8 ignore next */);
+
+export const writePNG = (name: string, png: PNG | Buffer) =>
+  fs.writeFileSync(
+    name,
+    addPNGMetadata(png instanceof PNG ? PNG.sync.write(png) : png)
+  );
 
 const inArea = (x: number, y: number, height: number, width: number) =>
   y > height || x > width;
@@ -33,19 +54,22 @@ export const createImageResizer =
     /* c8 ignore next */
   };
 
-export const importAndScaleImage = async (cfg: {
+export const scaleImageAndWrite = async ({
+  scaleFactor,
+  path,
+}: {
   scaleFactor: number;
   path: string;
 }) => {
-  const imgBuffer = fs.readFileSync(cfg.path);
-  const rawImgNew = PNG.sync.read(imgBuffer);
-  if (cfg.scaleFactor === 1) return rawImgNew;
+  const imgBuffer = fs.readFileSync(path);
+  if (scaleFactor === 1) return imgBuffer;
 
-  const newImageWidth = Math.ceil(rawImgNew.width * cfg.scaleFactor);
-  const newImageHeight = Math.ceil(rawImgNew.height * cfg.scaleFactor);
-  await sharp(imgBuffer).resize(newImageWidth, newImageHeight).toFile(cfg.path);
+  const rawImgNew = PNG.sync.read(imgBuffer);
+  const newImageWidth = Math.ceil(rawImgNew.width * scaleFactor);
+  const newImageHeight = Math.ceil(rawImgNew.height * scaleFactor);
+  await sharp(imgBuffer).resize(newImageWidth, newImageHeight).toFile(path);
 
-  return PNG.sync.read(fs.readFileSync(cfg.path));
+  return fs.readFileSync(path);
 };
 
 export const alignImagesToSameSize = (
@@ -70,3 +94,20 @@ export const alignImagesToSameSize = (
     fillSizeDifference(resizedSecond, secondImageWidth, secondImageHeight),
   ];
 };
+
+export const cleanupUnused = (rootPath: string) => {
+  glob
+    .sync("**/*.png", {
+      cwd: rootPath,
+      ignore: "node_modules/**/*",
+    })
+    .forEach((pngPath) => {
+      const absolutePath = path.join(rootPath, pngPath);
+      if (
+        !wasScreenshotUsed(pngPath) &&
+        isImageGeneratedByPlugin(fs.readFileSync(absolutePath))
+      ) {
+        fs.unlinkSync(absolutePath);
+      }
+    });
+};

src/commands.ts

@@ -27,6 +27,6 @@ export const initPlugin = (
     initForceDeviceScaleFactor(on);
   }
   /* c8 ignore stop */
-  on("task", initTaskHook());
+  on("task", initTaskHook(config));
   on("after:screenshot", initAfterScreenshotHook(config));
 };

src/constants.ts

@@ -0,0 +1,46 @@
+import path from "path";
+import { FILE_SUFFIX, IMAGE_SNAPSHOT_PREFIX } from "./constants";
+import sanitize from "sanitize-filename";
+
+const nameCacheCounter: Record<string, number> = {};
+
+export const generateScreenshotPath = ({
+  titleFromOptions,
+  imagesDir,
+  specPath,
+}: {
+  titleFromOptions: string;
+  imagesDir: string;
+  specPath: string;
+}) => {
+  const screenshotPath = path.join(
+    path.dirname(specPath),
+    ...imagesDir.split("/"),
+    sanitize(titleFromOptions)
+  );
+
+  if (typeof nameCacheCounter[screenshotPath] === "undefined") {
+    nameCacheCounter[screenshotPath] = -1;
+  }
+  return path.join(
+    IMAGE_SNAPSHOT_PREFIX,
+    `${screenshotPath} #${++nameCacheCounter[screenshotPath]}${
+      FILE_SUFFIX.actual
+    }.png`
+  );
+};
+
+const screenshotPathRegex = new RegExp(
+  `^([\\s\\S]+?) #([0-9]+)(?:(?:\\${FILE_SUFFIX.diff})|(?:\\${FILE_SUFFIX.actual}))?\\.(?:png|PNG)$`
+);
+export const wasScreenshotUsed = (imagePath: string) => {
+  const matched = imagePath.match(screenshotPathRegex);
+  /* c8 ignore next */ if (!matched) return false;
+  const [, screenshotPath, numString] = matched;
+  const num = parseInt(numString);
+  /* c8 ignore next */ if (!screenshotPath || isNaN(num)) return false;
+  return (
+    screenshotPath in nameCacheCounter &&
+    num <= nameCacheCounter[screenshotPath]
+  );
+};

src/image.utils.ts

@@ -77,6 +77,8 @@ before(() => {
 after(() => {
   if (!top) return null;
 
+  cy.task(TASK.cleanupImages, { log: false });
+
   Cypress.$(top.document.body).on(
     "click",
     `a[href^="${LINK_PREFIX}"]`,