feat: auto clean unused files

add documentation info
add metadata to images generated by the plugin
update fixtures screenshots (add metadata)

closes #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.

Signed-off-by: Jakub Freisler <[email protected]>

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

@@ -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.diff.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, {

__tests__/fixtures/screenshot.png

@@ -9,9 +9,12 @@ 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";

package.json

@@ -1,6 +1,25 @@
+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);
+export const getPNGMetadata = (png: Buffer) => getMetadata(png, METADATA_KEY);
+export const isImageCurrentVersion = (png: Buffer) =>
+  getPNGMetadata(png) === version;
+export const isImageGeneratedByPlugin = (png: Buffer) => !!getPNGMetadata(png);
+
+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 +52,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 +92,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));
 };