jest-image-snapshot 6.1.1 → 6.3.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [6.3.0](https://github.com/americanexpress/jest-image-snapshot/compare/v6.2.0...v6.3.0) (2023-11-28)
+
+
+### Features
+
+* Add `runtimeHooksPath` options ([#337](https://github.com/americanexpress/jest-image-snapshot/issues/337)) ([57741a2](https://github.com/americanexpress/jest-image-snapshot/commit/57741a242cd2192c453a87c34fa89c7c35a0763c))
+
+# [6.2.0](https://github.com/americanexpress/jest-image-snapshot/compare/v6.1.1...v6.2.0) (2023-07-25)
+
+
+### Features
+
+* allow configuration of postfix for received screenshots filename ([#328](https://github.com/americanexpress/jest-image-snapshot/issues/328)) ([bade294](https://github.com/americanexpress/jest-image-snapshot/commit/bade294ec2843c62b1dbcbf894faffd3a5708b98))
+
 ## [6.1.1](https://github.com/americanexpress/jest-image-snapshot/compare/v6.1.0...v6.1.1) (2023-07-25)
 
 

package/CONTRIBUTING.md

@@ -47,7 +47,7 @@ Verifies that your code matches the American Express code style defined in [`esl
 
 Runs unit tests **and** verifies the format of all commit messages on the current branch.
 
-- **`npm posttest`**
+- **`npm run posttest`**
 
 Runs linting on the current branch, checks that the commits follow [conventional commits](https://www.conventionalcommits.org/) and verifies that the `package-lock.json` file includes public NPM registry URLs.
 

package/README.md

@@ -111,6 +111,7 @@ See [the examples](./examples/README.md) for more detailed usage or read about a
 * `customDiffDir`: A custom absolute path of a directory to keep this diff in
 * `storeReceivedOnFailure`: (default: `false`) Store the received images seperately from the composed diff images on failure. This can be useful when updating baseline images from CI.
 * `customReceivedDir`: A custom absolute path of a directory to keep this received image in
+* `customReceivedPostfix`: A custom postfix which is added to the snapshot name of the received image, defaults to `-received`
 * `customSnapshotIdentifier`: A custom name to give this snapshot. If not provided one is computed automatically. When a function is provided it is called with an object containing `testPath`, `currentTestName`, `counter` and `defaultIdentifier` as its first argument. The function must return an identifier to use for the snapshot. If a path is given, the path will be created inside the snapshot/diff directories.
 * `diffDirection`: (default: `horizontal`) (options `horizontal` or `vertical`) Changes diff image layout direction
 * `onlyDiff`: (default: `false`) Either only include the difference between the baseline and the received image in the diff image, or include the 3 images (following the direction set by `diffDirection`).
@@ -123,6 +124,9 @@ See [the examples](./examples/README.md) for more detailed usage or read about a
 * `dumpDiffToConsole`: (default `false`) Will output base64 string of a diff image to console in case of failed tests (in addition to creating a diff image). This string can be copy-pasted to a browser address string to preview the diff for a failed test.
 * `dumpInlineDiffToConsole`: (default `false`) Will output the image to the terminal using iTerm's [Inline Images Protocol](https://iterm2.com/documentation-images.html). If the term is not compatible, it does the same thing as `dumpDiffToConsole`.
 * `allowSizeMismatch`: (default `false`) If set to true, the build will not fail when the screenshots to compare have different sizes.
+* `runtimeHooksPath`: (default `undefined`) This needs to be set to a existing file, like `require.resolve('./runtimeHooksPath.cjs')`. This file can expose a few hooks:
+  * `onBeforeWriteToDisc`: before saving any image to the disc, this function will be called (can be used to write EXIF data to images for instance)
+    `onBeforeWriteToDisc: (arguments: { buffer: Buffer; destination: string; testPath: string; currentTestName: string }) => Buffer`
 
 ```javascript
 it('should demonstrate this matcher`s usage with a custom pixelmatch config', () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jest-image-snapshot",
-  "version": "6.1.1",
+  "version": "6.3.0",
   "description": "Jest matcher for image comparisons. Most commonly used for visual regression testing.",
   "main": "src/index.js",
   "engines": {
@@ -30,7 +30,7 @@
       "!test-results/**"
     ],
     "testMatch": [
-      "<rootDir>/__tests__/**/*.js"
+      "<rootDir>/__tests__/**/*.spec.js"
     ],
     "coveragePathIgnorePatterns": [
       "/node_modules/",
@@ -44,8 +44,8 @@
   "author": "Andres Escobar <andres.escobar@aexp.com> (https://github.com/anescobar1991)",
   "license": "Apache-2.0",
   "devDependencies": {
-    "@commitlint/cli": "^8.3.5",
-    "@commitlint/config-conventional": "^8.3.4",
+    "@commitlint/cli": "^17.6.5",
+    "@commitlint/config-conventional": "^17.7.0",
     "@semantic-release/changelog": "^5.0.0",
     "@semantic-release/git": "^9.0.0",
     "amex-jest-preset": "^6.1.0",

package/src/diff-snapshot.js

@@ -200,12 +200,45 @@ function composeDiff(options) {
   return composer;
 }
 
+function writeFileWithHooks({
+  pathToFile,
+  content,
+  runtimeHooksPath,
+  testPath,
+  currentTestName,
+}) {
+  let finalContent = content;
+  if (runtimeHooksPath) {
+    let runtimeHooks;
+    try {
+      // As `diffImageToSnapshot` can be called in a worker, and as we cannot pass a function
+      // to a worker, we need to use an external file path that can be imported
+      // eslint-disable-next-line import/no-dynamic-require, global-require
+      runtimeHooks = require(runtimeHooksPath);
+    } catch (e) {
+      throw new Error(`Couldn't import ${runtimeHooksPath}: ${e.message}`);
+    }
+    try {
+      finalContent = runtimeHooks.onBeforeWriteToDisc({
+        buffer: content,
+        destination: pathToFile,
+        testPath,
+        currentTestName,
+      });
+    } catch (e) {
+      throw new Error(`Couldn't execute onBeforeWriteToDisc: ${e.message}`);
+    }
+  }
+  fs.writeFileSync(pathToFile, finalContent);
+}
+
 function diffImageToSnapshot(options) {
   const {
     receivedImageBuffer,
     snapshotIdentifier,
     snapshotsDir,
     storeReceivedOnFailure,
+    receivedPostfix = '-received',
     receivedDir = path.join(options.snapshotsDir, '__received_output__'),
     diffDir = path.join(options.snapshotsDir, '__diff_output__'),
     diffDirection,
@@ -218,6 +251,9 @@ function diffImageToSnapshot(options) {
     blur,
     allowSizeMismatch = false,
     comparisonMethod = 'pixelmatch',
+    testPath,
+    currentTestName,
+    runtimeHooksPath,
   } = options;
 
   const comparisonFn = comparisonMethod === 'ssim' ? ssimMatch : pixelmatch;
@@ -225,10 +261,16 @@ function diffImageToSnapshot(options) {
   const baselineSnapshotPath = path.join(snapshotsDir, `${snapshotIdentifier}.png`);
   if (!fs.existsSync(baselineSnapshotPath)) {
     fs.mkdirSync(path.dirname(baselineSnapshotPath), { recursive: true });
-    fs.writeFileSync(baselineSnapshotPath, receivedImageBuffer);
+    writeFileWithHooks({
+      pathToFile: baselineSnapshotPath,
+      content: receivedImageBuffer,
+      runtimeHooksPath,
+      testPath,
+      currentTestName,
+    });
     result = { added: true };
   } else {
-    const receivedSnapshotPath = path.join(receivedDir, `${snapshotIdentifier}-received.png`);
+    const receivedSnapshotPath = path.join(receivedDir, `${snapshotIdentifier}${receivedPostfix}.png`);
     rimraf.sync(receivedSnapshotPath);
 
     const diffOutputPath = path.join(diffDir, `${snapshotIdentifier}-diff.png`);
@@ -293,7 +335,13 @@ function diffImageToSnapshot(options) {
     if (isFailure({ pass, updateSnapshot })) {
       if (storeReceivedOnFailure) {
         fs.mkdirSync(path.dirname(receivedSnapshotPath), { recursive: true });
-        fs.writeFileSync(receivedSnapshotPath, receivedImageBuffer);
+        writeFileWithHooks({
+          pathToFile: receivedSnapshotPath,
+          content: receivedImageBuffer,
+          runtimeHooksPath,
+          testPath,
+          currentTestName,
+        });
         result = { receivedSnapshotPath };
       }
 
@@ -319,7 +367,13 @@ function diffImageToSnapshot(options) {
       // Set filter type to Paeth to avoid expensive auto scanline filter detection
       // For more information see https://www.w3.org/TR/PNG-Filters.html
       const pngBuffer = PNG.sync.write(compositeResultImage, { filterType: 4 });
-      fs.writeFileSync(diffOutputPath, pngBuffer);
+      writeFileWithHooks({
+        pathToFile: diffOutputPath,
+        content: pngBuffer,
+        runtimeHooksPath,
+        testPath,
+        currentTestName,
+      });
 
       result = {
         ...result,
@@ -333,7 +387,13 @@ function diffImageToSnapshot(options) {
       };
     } else if (shouldUpdate({ pass, updateSnapshot, updatePassedSnapshot })) {
       fs.mkdirSync(path.dirname(baselineSnapshotPath), { recursive: true });
-      fs.writeFileSync(baselineSnapshotPath, receivedImageBuffer);
+      writeFileWithHooks({
+        pathToFile: baselineSnapshotPath,
+        content: receivedImageBuffer,
+        runtimeHooksPath,
+        testPath,
+        currentTestName,
+      });
       result = { updated: true };
     } else {
       result = {

package/src/index.js

@@ -137,8 +137,10 @@ function configureToMatchImageSnapshot({
   customSnapshotsDir: commonCustomSnapshotsDir,
   storeReceivedOnFailure: commonStoreReceivedOnFailure = false,
   customReceivedDir: commonCustomReceivedDir,
+  customReceivedPostfix: commonCustomReceivedPostfix,
   customDiffDir: commonCustomDiffDir,
   onlyDiff: commonOnlyDiff = false,
+  runtimeHooksPath: commonRuntimeHooksPath = undefined,
   diffDirection: commonDiffDirection = 'horizontal',
   noColors: commonNoColors,
   failureThreshold: commonFailureThreshold = 0,
@@ -156,8 +158,10 @@ function configureToMatchImageSnapshot({
     customSnapshotsDir = commonCustomSnapshotsDir,
     storeReceivedOnFailure = commonStoreReceivedOnFailure,
     customReceivedDir = commonCustomReceivedDir,
+    customReceivedPostfix = commonCustomReceivedPostfix,
     customDiffDir = commonCustomDiffDir,
     onlyDiff = commonOnlyDiff,
+    runtimeHooksPath = commonRuntimeHooksPath,
     diffDirection = commonDiffDirection,
     customDiffConfig = {},
     noColors = commonNoColors,
@@ -197,6 +201,7 @@ function configureToMatchImageSnapshot({
 
     const snapshotsDir = customSnapshotsDir || path.join(path.dirname(testPath), SNAPSHOTS_DIR);
     const receivedDir = customReceivedDir;
+    const receivedPostfix = customReceivedPostfix;
     const diffDir = customDiffDir;
     const baselineSnapshotPath = path.join(snapshotsDir, `${snapshotIdentifier}.png`);
     OutdatedSnapshotReporter.markTouchedFile(baselineSnapshotPath);
@@ -218,8 +223,11 @@ function configureToMatchImageSnapshot({
         snapshotsDir,
         storeReceivedOnFailure,
         receivedDir,
+        receivedPostfix,
         diffDir,
         diffDirection,
+        testPath,
+        currentTestName,
         onlyDiff,
         snapshotIdentifier,
         updateSnapshot: snapshotState._updateSnapshot === 'all',
@@ -230,6 +238,7 @@ function configureToMatchImageSnapshot({
         blur,
         allowSizeMismatch,
         comparisonMethod,
+        runtimeHooksPath,
       });
 
     return checkResult({