@tryghost/jest-snapshot 0.5.15 → 0.5.17

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2013-2023 Ghost Foundation
+Copyright (c) 2013-2025 Ghost Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -38,4 +38,4 @@ Follow the instructions for the top-level repo.
 
 # Copyright & License 
 
-Copyright (c) 2013-2023 Ghost Foundation - Released under the [MIT license](LICENSE).
+Copyright (c) 2013-2025 Ghost Foundation - Released under the [MIT license](LICENSE).

package/lib/SnapshotManager.js

@@ -1,38 +1,74 @@
-const {SnapshotState, toMatchSnapshot} = require('jest-snapshot');
+const {SnapshotState, toMatchSnapshot, EXTENSION} = require('jest-snapshot');
 const errors = require('@tryghost/errors');
 const utils = require('@jest/expect-utils');
 const assert = require('assert');
 const path = require('path');
 const {makeMessageFromMatchMessage} = require('./utils');
 
+const DOT_EXTENSION = `.${EXTENSION}`;
+
 class SnapshotManager {
     constructor() {
         this.registry = {};
         this.currentTest = {};
-        this.defaultSnapshotPath = '__snapshots__';
+        this.defaultSnapshotRoot = '__snapshots__';
     }
 
-    _getNameForSnapshot(snapshotFilename, snapshotNameTemplate) {
-        if (!this.registry[snapshotFilename]) {
-            this.registry[snapshotFilename] = {};
-        }
-
-        const nextCounter = (this.registry[snapshotFilename][snapshotNameTemplate] || 0) + 1;
-        this.registry[snapshotFilename][snapshotNameTemplate] = nextCounter;
+    /**
+     * Determines whether to update all snapshots or only new ones
+     * @returns {string} e.g. 'all' or 'new'
+     */
+    _willUpdate() {
+        const updateSnapshots = (
+            process.env.SNAPSHOT_UPDATE
+            || process.env.UPDATE_SNAPSHOT
+            || process.env.SNAPSHOTS_UPDATE
+            || process.env.UPDATE_SNAPSHOTS
+        );
 
-        return `${snapshotNameTemplate} ${nextCounter}`;
+        return updateSnapshots ? 'all' : 'new';
     }
 
-    _resolveSnapshotFilePath(testFile) {
-        const parsedPath = path.parse(testFile);
+    /**
+     * Looks in the registry for a snapshot with the same filename and nameTemplate
+     * If needed, increments the counter
+     * Returns nametemplate with the counter appended.
+     *
+     * @param {string} testPath e.g. '/path/to/tests/my-fake.test.js'
+     * @param {string} testTitle e.g. 'My fake test title'
+     * @returns {string} e.g. 'My fake test title 1'
+     */
+    _getNameForSnapshot(testPath, testTitle) {
+        if (!(testPath in this.registry)) {
+            this.registry[testPath] = {};
+        }
+
+        const nextCounter = (this.registry[testPath][testTitle] || 0) + 1;
+        this.registry[testPath][testTitle] = nextCounter;
 
-        parsedPath.dir = path.join(parsedPath.dir, this.defaultSnapshotPath);
+        return `${testTitle} ${nextCounter}`;
+    }
 
-        return path.format(parsedPath);
+    /**
+     * Takes the full path to the test file and returns the full path to the snapshot file
+     *
+     * @param {string} testPath e.g. '/path/to/tests/my-fake.test.js'
+     * @returns {string} snapshotFilePath e.g. '/path/to/tests/__snapshots__/my-fake.test.js.snap'
+     */
+    _resolveSnapshotFilePath(testPath) {
+        return path.join(
+            path.join(path.dirname(testPath), this.defaultSnapshotRoot),
+            path.basename(testPath) + DOT_EXTENSION
+        );
     }
 
+    /**
+     * Returns config for the current test
+     * Throws an error if the current test is not configured
+     * @returns {Object} e.g. {snapshotPath: 'test/__snapshots__/my-fake.test.js.snap', snapshotName: 'My fake test title 1', willUpdate: 'new'}
+     */
     _getConfig() {
-        if (!this.currentTest.filename || !this.currentTest.nameTemplate) {
+        if (!this.currentTest.testPath || !this.currentTest.testTitle) {
             throw new errors.IncorrectUsageError({
                 message: 'Unable to run snapshot tests, current test was not configured',
                 context: 'Snapshot testing requires current test filename and nameTemplate to be set for each test',
@@ -40,46 +76,64 @@ class SnapshotManager {
             });
         }
 
-        let testFile = this.currentTest.filename;
-        const testTitle = this.currentTest.nameTemplate;
-        const snapshotName = this._getNameForSnapshot(testFile, testTitle);
-        const updateSnapshots = (
-            process.env.SNAPSHOT_UPDATE
-            || process.env.UPDATE_SNAPSHOT
-            || process.env.SNAPSHOTS_UPDATE
-            || process.env.UPDATE_SNAPSHOTS
-        );
-        const willUpdate = updateSnapshots ? 'all' : 'new';
+        const {testPath, testTitle} = this.currentTest;
+
+        const snapshotName = this._getNameForSnapshot(testPath, testTitle);
+        const willUpdate = this._willUpdate();
 
         // Set full path
-        testFile = this._resolveSnapshotFilePath(testFile);
+        const snapshotPath = this._resolveSnapshotFilePath(testPath);
 
-        return {testFile, snapshotName, willUpdate};
+        return {snapshotPath, snapshotName, willUpdate};
     }
 
+    /**
+     * Resets the registry to an empty object
+     */
     resetRegistry() {
         this.registry = {};
     }
 
+    /**
+     * Resets the registry for the current test only
+     */
     resetRegistryForCurrentTest() {
-        const testTitle = this.currentTest.nameTemplate;
-        if (this.currentTest.filename in this.registry && testTitle in this.registry[this.currentTest.filename]) {
-            delete this.registry[this.currentTest.filename][testTitle];
+        const {testPath, testTitle} = this.currentTest;
+        if (testPath in this.registry && testTitle in this.registry[testPath]) {
+            delete this.registry[testPath][testTitle];
         }
     }
 
+    /**
+     * @param {Object} testConfig
+     * @param {String} testConfig.testPath full path to the test file
+     * @param {String} testConfig.testTitle the full title of the test - all the describe and it names concatenated
+     */
     setCurrentTest(testConfig) {
         this.currentTest = testConfig;
     }
 
-    getSnapshotState(testFile, willUpdate) {
+    /**
+     * Gets a SnapshotState instance for the current test
+     * @param {string} snapshotPath e.g. 'test/__snapshots__/my-fake.test.js.snap'
+     * @param {string} willUpdate e.g. 'new'
+     * @returns {SnapshotState}
+     */
+    getSnapshotState(snapshotPath, willUpdate) {
         // Initialize the SnapshotState, it’s responsible for actually matching
         // actual snapshot with expected one and storing results
-        return new SnapshotState(testFile, {
+        return new SnapshotState(snapshotPath, {
             updateSnapshot: willUpdate
         });
     }
 
+    /**
+     * Asserts the snapshot values match using the match function
+     * Does some formatting of the error message
+     *
+     * @param {{field: string}} response
+     * @param {{properties: Object, field: string, error: Object, hint: string}} assertion
+     */
     assertSnapshot(response, assertion) {
         const {properties, field, error} = assertion;
 
@@ -116,10 +170,21 @@ class SnapshotManager {
         assert.equal(match.pass, true, error);
     }
 
+    /**
+     * Calls Jest's toMatchSnapshot function
+     * Binds the snapshotState, currentTestName, utils and equals function to the matcher
+     * Executes the matcher
+     * Saves the snapshot state
+     *
+     * @param {Object} received - our actual value
+     * @param {Object} [properties] - the properties we want to match against
+     * @param {string} [hint] - a hint to help with the match
+     * @returns {Object} result of the match
+     */
     match(received, properties = {}, hint) {
-        const {testFile, snapshotName, willUpdate} = this._getConfig();
+        const {snapshotPath, snapshotName, willUpdate} = this._getConfig();
 
-        const snapshotState = this.getSnapshotState(testFile, willUpdate);
+        const snapshotState = this.getSnapshotState(snapshotPath, willUpdate);
         const matcher = toMatchSnapshot.bind({
             snapshotState,
             currentTestName: snapshotName,

package/lib/jest-snapshot.js

@@ -12,9 +12,20 @@ function matchSnapshotAssertion(properties) {
 }
 
 const mochaHooks = {
+
+    /**
+     * Runs before all tests
+     * Resets the registry so we start with a clean slate
+     */
     beforeAll() {
         snapshotManager.resetRegistry();
     },
+
+    /**
+     * Runs before each test
+     * Passes the current test config to the snapshot manager
+     * If we're running a retry, reset the registry for this test only
+     */
     beforeEach() {
         const {currentTest} = this;
 
@@ -24,8 +35,8 @@ const mochaHooks = {
         }
 
         snapshotManager.setCurrentTest({
-            filename: currentTest.file + '.snap',
-            nameTemplate: currentTest.fullTitle()
+            testPath: currentTest.file,
+            testTitle: currentTest.fullTitle()
         });
     }
 };

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@tryghost/jest-snapshot",
-  "version": "0.5.15",
+  "version": "0.5.17",
   "repository": "https://github.com/TryGhost/framework/tree/main/packages/jest-snapshot",
   "author": "Ghost Foundation",
   "license": "MIT",
   "main": "index.js",
   "scripts": {
     "dev": "echo \"Implement me!\"",
-    "test": "NODE_ENV=testing c8 --all --check-coverage --100 --reporter text --reporter cobertura mocha './test/**/*.test.js'",
+    "test": "NODE_ENV=testing c8 --all --check-coverage --100 --reporter text --reporter cobertura --reporter html-spa mocha './test/**/*.test.js'",
     "lint": "eslint . --ext .js --cache",
     "posttest": "yarn lint"
   },
@@ -19,16 +19,16 @@
     "access": "public"
   },
   "devDependencies": {
-    "c8": "10.1.2",
-    "mocha": "10.6.0",
+    "c8": "10.1.3",
+    "mocha": "10.7.3",
     "should": "13.2.3",
     "sinon": "18.0.0"
   },
   "dependencies": {
     "@jest/expect": "^28.0.1",
     "@jest/expect-utils": "^28.0.1",
-    "@tryghost/errors": "^1.3.5",
+    "@tryghost/errors": "^1.3.7",
     "jest-snapshot": "^29.0.0"
   },
-  "gitHead": "d3d489cb44ac3d4e35e21388d48ee0d94e496d86"
+  "gitHead": "b169bd1734b749c3abdaac134f030756b9a282bb"
 }