feat: introduce imagesPath option (#152)

allow relative path resolution
create special {spec_path} variable
allow absolute path resolution (under unix and win systems) refactor afterScreenshot hook to awaits
add deprecation message for imagesDir option
add docs info

references issue #147
BREAKING CHANGE: deprecate imagesDir option in favor of imagesPath - see docs for additional information

Author: FRSgit

README.md

@@ -174,9 +174,13 @@ cy.matchImage({
   // default: false
   updateImages: true,
   // directory path in which screenshot images will be stored
-  // image visualiser will normalise path separators depending on OS it's being run within, so always use / for nested paths
-  // default: '__image_snapshots__'
-  imagesDir: 'this-might-be-your-custom/maybe-nested-directory',
+  // relative path are resolved against project root
+  // absolute paths (both on unix and windows OS) supported
+  // path separators will be normalised by the plugin depending on OS, you should always use / as path separator, e.g.: C:/my-directory/nested for windows-like drive notation
+  // There are one special variable available to be used in the path:
+  // - {spec_path} - relative path leading from project root to the current spec file directory (e.g. `/src/components/my-tested-component`)
+  // default: '{spec_path}/__image_snapshots__'
+  imagesPath: 'this-might-be-your-custom/maybe-nested-directory',
   // maximum threshold above which the test should fail
   // default: 0.01
   maxDiffThreshold: 0.1,

example/package.json

@@ -5,7 +5,7 @@
   "scripts": {
     "serve": "vue-cli-service serve",
     "build": "vue-cli-service build",
-    "test:open": "vue-cli-service test:e2e --env \"pluginVisualRegressionImagesDir=__image_snapshots_local__\"",
+    "test:open": "vue-cli-service test:e2e --env \"pluginVisualRegressionImagesPath={spec_path}/__image_snapshots_local__\"",
     "test:run": "vue-cli-service test:e2e",
     "test:ct": "yarn test:open --component",
     "test:ct:ci": "yarn test:run --component --headless",

src/afterScreenshot.hook.test.ts

@@ -1,9 +1,12 @@
 import { it, expect, describe } from "vitest";
 import path from "path";
 import { promises as fs, existsSync } from "fs";
-import { initAfterScreenshotHook } from "./afterScreenshot.hook";
+import {
+  initAfterScreenshotHook,
+  parseAbsolutePath,
+} from "./afterScreenshot.hook";
 import { dir, file, setGracefulCleanup } from "tmp-promise";
-import { IMAGE_SNAPSHOT_PREFIX } from "./constants";
+import { IMAGE_SNAPSHOT_PREFIX, PATH_VARIABLES } from "./constants";
 
 setGracefulCleanup();
 
@@ -31,3 +34,33 @@ describe("initAfterScreenshotHook", () => {
     await fs.unlink(expectedNewPath);
   });
 });
+
+describe("parseAbsolutePath", () => {
+  const projectRoot = "/its/project/root";
+
+  it("resolves relative paths against project root", () => {
+    expect(
+      parseAbsolutePath({ screenshotPath: "some/path.png", projectRoot })
+    ).toBe("/its/project/root/some/path.png");
+  });
+
+  it("builds proper win paths when found", () => {
+    expect(
+      parseAbsolutePath({
+        screenshotPath: `${PATH_VARIABLES.winSystemRootPath}/D/some/path.png`,
+        projectRoot,
+      })
+    )
+      // that's expected output accorind to https://stackoverflow.com/a/64135721/8805801
+      .toBe("D:\\/some/path.png");
+  });
+
+  it("resolves relative paths against project root", () => {
+    expect(
+      parseAbsolutePath({
+        screenshotPath: `${PATH_VARIABLES.unixSystemRootPath}/some/path.png`,
+        projectRoot,
+      })
+    ).toBe("/some/path.png");
+  });
+});

src/afterScreenshot.hook.ts

@@ -1,10 +1,17 @@
 import path from "path";
-import fs from "fs";
+import { promises as fs } from "fs";
 import moveFile from "move-file";
-import { IMAGE_SNAPSHOT_PREFIX } from "./constants";
+import { IMAGE_SNAPSHOT_PREFIX, PATH_VARIABLES } from "./constants";
 
 type NotFalsy<T> = T extends false | null | undefined ? never : T;
 
+const MIMIC_ROOT_WIN_REGEX = new RegExp(
+  `^${PATH_VARIABLES.winSystemRootPath}\\${path.sep}([A-Z])\\${path.sep}`
+);
+const MIMIC_ROOT_UNIX_REGEX = new RegExp(
+  `^${PATH_VARIABLES.unixSystemRootPath}\\${path.sep}`
+);
+
 const getConfigVariableOrThrow = <K extends keyof Cypress.PluginConfigOptions>(
   config: Cypress.PluginConfigOptions,
   name: K
@@ -14,25 +21,33 @@ const getConfigVariableOrThrow = <K extends keyof Cypress.PluginConfigOptions>(
   }
 
   /* c8 ignore start */
-  throw `[Image snapshot] CypressConfig.${name} cannot be missing or \`false\`!`;
+  throw `[@frsource/cypress-plugin-visual-regression-diff] CypressConfig.${name} cannot be missing or \`false\`!`;
 };
 /* c8 ignore stop */
 
-const removeScreenshotsDirectory = (
-  screenshotsFolder: string,
-  onSuccess: () => void,
-  onError: (e: Error) => void
-) => {
-  fs.rm(
-    path.join(screenshotsFolder, IMAGE_SNAPSHOT_PREFIX),
-    { recursive: true, force: true },
-    (err) => {
-      /* c8 ignore start */
-      if (err) return onError(err);
-      /* c8 ignore stop */
-      onSuccess();
-    }
-  );
+export const parseAbsolutePath = ({
+  screenshotPath,
+  projectRoot,
+}: {
+  screenshotPath: string;
+  projectRoot: string;
+}) => {
+  let newAbsolutePath: string;
+  const matchedMimicingWinRoot = screenshotPath.match(MIMIC_ROOT_WIN_REGEX);
+  const matchedMimicingUnixRoot = screenshotPath.match(MIMIC_ROOT_UNIX_REGEX);
+  if (matchedMimicingWinRoot && matchedMimicingWinRoot[1]) {
+    const driveLetter = matchedMimicingWinRoot[1];
+    newAbsolutePath = path.join(
+      `${driveLetter}:\\`,
+      screenshotPath.substring(matchedMimicingWinRoot[0].length)
+    );
+  } else if (matchedMimicingUnixRoot) {
+    newAbsolutePath =
+      path.sep + screenshotPath.substring(matchedMimicingUnixRoot[0].length);
+  } else {
+    newAbsolutePath = path.join(projectRoot, screenshotPath);
+  }
+  return path.normalize(newAbsolutePath);
 };
 
 export const initAfterScreenshotHook =
@@ -47,27 +62,25 @@ export const initAfterScreenshotHook =
     /* c8 ignore start */
     if (details.name?.indexOf(IMAGE_SNAPSHOT_PREFIX) !== 0) return;
     /* c8 ignore stop */
-    return new Promise((resolve, reject) => {
-      const screenshotsFolder = getConfigVariableOrThrow(
-        config,
-        "screenshotsFolder"
-      );
+    const screenshotsFolder = getConfigVariableOrThrow(
+      config,
+      "screenshotsFolder"
+    );
+    const screenshotPath = details.name.substring(
+      IMAGE_SNAPSHOT_PREFIX.length + path.sep.length
+    );
+    const newAbsolutePath = parseAbsolutePath({
+      screenshotPath,
+      projectRoot: config.projectRoot,
+    });
 
-      const newRelativePath = details.name.substring(
-        IMAGE_SNAPSHOT_PREFIX.length + path.sep.length
-      );
-      const newAbsolutePath = path.normalize(
-        path.join(config.projectRoot, newRelativePath)
-      );
+    return (async () => {
+      await moveFile(details.path, newAbsolutePath);
+      await fs.rm(path.join(screenshotsFolder, IMAGE_SNAPSHOT_PREFIX), {
+        recursive: true,
+        force: true,
+      });
 
-      void moveFile(details.path, newAbsolutePath)
-        .then(() =>
-          removeScreenshotsDirectory(
-            screenshotsFolder,
-            () => resolve({ path: newAbsolutePath }),
-            reject
-          )
-        )
-        .catch(reject);
-    });
+      return { path: newAbsolutePath };
+    })();
   };