@vitest/snapshot 3.2.0-beta.2 → 3.2.0

package/dist/index.d.ts

@@ -20,6 +20,11 @@ declare class DefaultMap<
 }
 declare class CounterMap<K> extends DefaultMap<K, number> {
 	constructor();
+	// compat for jest-image-snapshot https://github.com/vitest-dev/vitest/issues/7322
+	// `valueOf` and `Snapshot.added` setter allows
+	//   snapshotState.added = snapshotState.added + 1
+	// to function as
+	//   snapshotState.added.total_ = snapshotState.added.total() + 1
 	_total: number | undefined;
 	valueOf(): number;
 	increment(key: K): void;
@@ -54,6 +59,8 @@ declare class SnapshotState {
 	private _environment;
 	private _fileExists;
 	expand: boolean;
+	// getter/setter for jest-image-snapshot compat
+	// https://github.com/vitest-dev/vitest/issues/7322
 	private _added;
 	private _matched;
 	private _unmatched;

package/dist/index.js

@@ -656,6 +656,7 @@ const stackIgnorePatterns = [
 	/\/deps\/vitest_/
 ];
 function extractLocation(urlLike) {
+	// Fail-fast but return locations like "(native)"
 	if (!urlLike.includes(":")) {
 		return [urlLike];
 	}
@@ -695,6 +696,7 @@ function parseSingleFFOrSafariStack(raw) {
 	if (!line.includes("@") && !line.includes(":")) {
 		return null;
 	}
+	// eslint-disable-next-line regexp/no-super-linear-backtracking, regexp/optimal-quantifier-concatenation
 	const functionNameRegex = /((.*".+"[^@]*)?[^@]*)(@)/;
 	const matches = line.match(functionNameRegex);
 	const functionName = matches && matches[1] ? matches[1] : undefined;
@@ -709,6 +711,8 @@ function parseSingleFFOrSafariStack(raw) {
 		column: Number.parseInt(columnNumber)
 	};
 }
+// Based on https://github.com/stacktracejs/error-stack-parser
+// Credit to stacktracejs
 function parseSingleV8Stack(raw) {
 	let line = raw.trim();
 	if (!CHROME_IE_STACK_REGEXP.test(line)) {
@@ -718,8 +722,13 @@ function parseSingleV8Stack(raw) {
 		line = line.replace(/eval code/g, "eval").replace(/(\(eval at [^()]*)|(,.*$)/g, "");
 	}
 	let sanitizedLine = line.replace(/^\s+/, "").replace(/\(eval code/g, "(").replace(/^.*?\s+/, "");
+	// capture and preserve the parenthesized location "(/foo/my bar.js:12:87)" in
+	// case it has spaces in it, as the string is split on \s+ later on
 	const location = sanitizedLine.match(/ (\(.+\)$)/);
+	// remove the parenthesized location from the line, if it was matched
 	sanitizedLine = location ? sanitizedLine.replace(location[0], "") : sanitizedLine;
+	// if a location was matched, pass it to extractLocation() otherwise pass all sanitizedLine
+	// because this line doesn't have function name
 	const [url, lineNumber, columnNumber] = extractLocation(location ? location[1] : sanitizedLine);
 	let method = location && sanitizedLine || "";
 	let file = url && ["eval", "<anonymous>"].includes(url) ? undefined : url;
@@ -732,6 +741,7 @@ function parseSingleV8Stack(raw) {
 	if (file.startsWith("file://")) {
 		file = file.slice(7);
 	}
+	// normalize Windows path (\ -> /)
 	file = file.startsWith("node:") || file.startsWith("internal:") ? file : resolve$2(file);
 	if (method) {
 		method = method.replace(/__vite_ssr_import_\d+__\./g, "");
@@ -762,6 +772,10 @@ function parseStacktrace(stack, options = {}) {
 			const fileUrl = stack.file.startsWith("file://") ? stack.file : `file://${stack.file}`;
 			const sourceRootUrl = map.sourceRoot ? new URL(map.sourceRoot, fileUrl) : fileUrl;
 			file = new URL(source, sourceRootUrl).pathname;
+			// if the file path is on windows, we need to remove the leading slash
+			if (file.match(/\/\w:\//)) {
+				file = file.slice(1);
+			}
 		}
 		if (shouldFilter(ignoreStackEntries, file)) {
 			return null;
@@ -793,8 +807,10 @@ function parseErrorStacktrace(e, options = {}) {
 	if (e.stacks) {
 		return e.stacks;
 	}
-	const stackStr = e.stack || e.stackStr || "";
-	let stackFrames = parseStacktrace(stackStr, options);
+	const stackStr = e.stack || "";
+	// if "stack" property was overwritten at runtime to be something else,
+	// ignore the value because we don't know how to process it
+	let stackFrames = typeof stackStr === "string" ? parseStacktrace(stackStr, options) : [];
 	if (!stackFrames.length) {
 		const e_ = e;
 		if (e_.fileName != null && e_.lineNumber != null && e_.columnNumber != null) {
@@ -1447,8 +1463,10 @@ function replaceObjectSnap(code, s, index, newSnap) {
 	const shapeEnd = getObjectShapeEndIndex(code, shapeStart);
 	const snap = `, ${prepareSnapString(newSnap, code, index)}`;
 	if (shapeEnd === callEnd) {
+		// toMatchInlineSnapshot({ foo: expect.any(String) })
 		s.appendLeft(callEnd, snap);
 	} else {
+		// toMatchInlineSnapshot({ foo: expect.any(String) }, ``)
 		s.overwrite(shapeEnd, callEnd, snap);
 	}
 	return true;
@@ -1481,6 +1499,7 @@ function prepareSnapString(snap, source, index) {
 }
 const toMatchInlineName = "toMatchInlineSnapshot";
 const toThrowErrorMatchingInlineName = "toThrowErrorMatchingInlineSnapshot";
+// on webkit, the line number is at the end of the method, not at the start
 function getCodeStartingAtIndex(code, index) {
 	const indexInline = index - toMatchInlineName.length;
 	if (code.slice(indexInline, index) === toMatchInlineName) {
@@ -1527,27 +1546,37 @@ function replaceInlineSnap(code, s, currentIndex, newSnap) {
 }
 const INDENTATION_REGEX = /^([^\S\n]*)\S/m;
 function stripSnapshotIndentation(inlineSnapshot) {
+	// Find indentation if exists.
 	const match = inlineSnapshot.match(INDENTATION_REGEX);
 	if (!match || !match[1]) {
+		// No indentation.
 		return inlineSnapshot;
 	}
 	const indentation = match[1];
 	const lines = inlineSnapshot.split(/\n/g);
 	if (lines.length <= 2) {
+		// Must be at least 3 lines.
 		return inlineSnapshot;
 	}
 	if (lines[0].trim() !== "" || lines[lines.length - 1].trim() !== "") {
+		// If not blank first and last lines, abort.
 		return inlineSnapshot;
 	}
 	for (let i = 1; i < lines.length - 1; i++) {
 		if (lines[i] !== "") {
 			if (lines[i].indexOf(indentation) !== 0) {
+				// All lines except first and last should either be blank or have the same
+				// indent as the first line (or more). If this isn't the case we don't
+				// want to touch the snapshot at all.
 				return inlineSnapshot;
 			}
 			lines[i] = lines[i].substring(indentation.length);
 		}
 	}
+	// Last line is a special case because it won't have the same indent as others
+	// but may still have been given some indent to line up.
 	lines[lines.length - 1] = "";
+	// Return inline snapshot, now at indent 0.
 	inlineSnapshot = lines.join("\n");
 	return inlineSnapshot;
 }
@@ -1628,6 +1657,7 @@ var naturalCompareExports = requireNaturalCompare();
 var naturalCompare = /*@__PURE__*/getDefaultExportFromCjs(naturalCompareExports);
 
 const serialize$1 = (val, config, indentation, depth, refs, printer) => {
+	// Serialize a non-default name, even if config.printFunctionName is false.
 	const name = val.getMockName();
 	const nameString = name === "vi.fn()" ? "" : ` ${name}`;
 	let callsString = "";
@@ -1660,6 +1690,7 @@ function getSerializers() {
 	return PLUGINS;
 }
 
+// TODO: rewrite and clean up
 function testNameToKey(testName, count) {
 	return `${testName} ${count}`;
 }
@@ -1677,11 +1708,15 @@ function getSnapshotData(content, options) {
 	if (content != null) {
 		try {
 			snapshotContents = content;
+			// eslint-disable-next-line no-new-func
 			const populate = new Function("exports", snapshotContents);
 			populate(data);
 		} catch {}
 	}
+	// const validationResult = validateSnapshotVersion(snapshotContents)
 	const isInvalid = snapshotContents;
+	// if (update === 'none' && isInvalid)
+	//   throw validationResult
 	if ((update === "all" || update === "new") && isInvalid) {
 		dirty = true;
 	}
@@ -1690,12 +1725,27 @@ function getSnapshotData(content, options) {
 		dirty
 	};
 }
+// Add extra line breaks at beginning and end of multiline snapshot
+// to make the content easier to read.
 function addExtraLineBreaks(string) {
 	return string.includes("\n") ? `\n${string}\n` : string;
 }
+// Remove extra line breaks at beginning and end of multiline snapshot.
+// Instead of trim, which can remove additional newlines or spaces
+// at beginning or end of the content from a custom serializer.
 function removeExtraLineBreaks(string) {
 	return string.length > 2 && string.startsWith("\n") && string.endsWith("\n") ? string.slice(1, -1) : string;
 }
+// export const removeLinesBeforeExternalMatcherTrap = (stack: string): string => {
+//   const lines = stack.split('\n')
+//   for (let i = 0; i < lines.length; i += 1) {
+//     // It's a function name specified in `packages/expect/src/index.ts`
+//     // for external custom matchers.
+//     if (lines[i].includes('__EXTERNAL_MATCHER_TRAP__'))
+//       return lines.slice(i + 1).join('\n')
+//   }
+//   return stack
+// }
 const escapeRegex = true;
 const printFunctionName = false;
 function serialize(val, indent = 2, formatOverrides = {}) {
@@ -1735,6 +1785,7 @@ function deepMergeArray(target = [], source = []) {
 		} else if (isObject(targetElement)) {
 			mergedOutput[index] = deepMergeSnapshot(target[index], sourceElement);
 		} else {
+			// Source does not exist in target or target is primitive and cannot be deep merged
 			mergedOutput[index] = sourceElement;
 		}
 	});
@@ -1790,6 +1841,11 @@ class CounterMap extends DefaultMap {
 	constructor() {
 		super(() => 0);
 	}
+	// compat for jest-image-snapshot https://github.com/vitest-dev/vitest/issues/7322
+	// `valueOf` and `Snapshot.added` setter allows
+	//   snapshotState.added = snapshotState.added + 1
+	// to function as
+	//   snapshotState.added.total_ = snapshotState.added.total() + 1
 	_total;
 	valueOf() {
 		return this._total = this.total();
@@ -1830,6 +1886,8 @@ class SnapshotState {
 	_environment;
 	_fileExists;
 	expand;
+	// getter/setter for jest-image-snapshot compat
+	// https://github.com/vitest-dev/vitest/issues/7322
 	_added = new CounterMap();
 	_matched = new CounterMap();
 	_unmatched = new CounterMap();
@@ -1889,14 +1947,19 @@ class SnapshotState {
 	}
 	markSnapshotsAsCheckedForTest(testName) {
 		this._uncheckedKeys.forEach((uncheckedKey) => {
+			// skip snapshots with following keys
+			//   testName n
+			//   testName > xxx n (this is for toMatchSnapshot("xxx") API)
 			if (/ \d+$| > /.test(uncheckedKey.slice(testName.length))) {
 				this._uncheckedKeys.delete(uncheckedKey);
 			}
 		});
 	}
 	clearTest(testId) {
+		// clear inline
 		this._inlineSnapshots = this._inlineSnapshots.filter((s) => s.testId !== testId);
 		this._inlineSnapshotStacks = this._inlineSnapshotStacks.filter((s) => s.testId !== testId);
+		// clear file
 		for (const key of this._testIdToKeys.get(testId)) {
 			const name = keyToTestName(key);
 			const count = this._counters.get(name);
@@ -1908,16 +1971,20 @@ class SnapshotState {
 			}
 		}
 		this._testIdToKeys.delete(testId);
+		// clear stats
 		this.added.delete(testId);
 		this.updated.delete(testId);
 		this.matched.delete(testId);
 		this.unmatched.delete(testId);
 	}
 	_inferInlineSnapshotStack(stacks) {
+		// if called inside resolves/rejects, stacktrace is different
 		const promiseIndex = stacks.findIndex((i) => i.method.match(/__VITEST_(RESOLVES|REJECTS)__/));
 		if (promiseIndex !== -1) {
 			return stacks[promiseIndex + 3];
 		}
+		// inline snapshot function is called __INLINE_SNAPSHOT__
+		// in integrations/snapshot/chai.ts
 		const stackIndex = stacks.findIndex((i) => i.method.includes("__INLINE_SNAPSHOT__"));
 		return stackIndex !== -1 ? stacks[stackIndex + 2] : null;
 	}
@@ -1982,12 +2049,16 @@ class SnapshotState {
 		}
 	}
 	match({ testId, testName, received, key, inlineSnapshot, isInline, error, rawSnapshot }) {
+		// this also increments counter for inline snapshots. maybe we shouldn't?
 		this._counters.increment(testName);
 		const count = this._counters.get(testName);
 		if (!key) {
 			key = testNameToKey(testName, count);
 		}
 		this._testIdToKeys.get(testId).push(key);
+		// Do not mark the snapshot as "checked" if the snapshot is inline and
+		// there's an external snapshot. This way the external snapshot can be
+		// removed with `--updateSnapshot`.
 		if (!(isInline && this._snapshotData[key] !== undefined)) {
 			this._uncheckedKeys.delete(key);
 		}
@@ -1996,6 +2067,7 @@ class SnapshotState {
 			receivedSerialized = addExtraLineBreaks(receivedSerialized);
 		}
 		if (rawSnapshot) {
+			// normalize EOL when snapshot contains CRLF but received is LF
 			if (rawSnapshot.content && rawSnapshot.content.match(/\r\n/) && !receivedSerialized.match(/\r\n/)) {
 				rawSnapshot.content = normalizeNewlines(rawSnapshot.content);
 			}
@@ -2006,8 +2078,15 @@ class SnapshotState {
 		const hasSnapshot = expected !== undefined;
 		const snapshotIsPersisted = isInline || this._fileExists || rawSnapshot && rawSnapshot.content != null;
 		if (pass && !isInline && !rawSnapshot) {
+			// Executing a snapshot file as JavaScript and writing the strings back
+			// when other snapshots have changed loses the proper escaping for some
+			// characters. Since we check every snapshot in every test, use the newly
+			// generated formatted string.
+			// Note that this is only relevant when a snapshot is added and the dirty
+			// flag is set.
 			this._snapshotData[key] = receivedSerialized;
 		}
+		// find call site of toMatchInlineSnapshot
 		let stack;
 		if (isInline) {
 			var _this$environment$pro, _this$environment;
@@ -2017,9 +2096,14 @@ class SnapshotState {
 				throw new Error(`@vitest/snapshot: Couldn't infer stack frame for inline snapshot.\n${JSON.stringify(stacks)}`);
 			}
 			stack = ((_this$environment$pro = (_this$environment = this.environment).processStackTrace) === null || _this$environment$pro === void 0 ? void 0 : _this$environment$pro.call(_this$environment, _stack)) || _stack;
+			// removing 1 column, because source map points to the wrong
+			// location for js files, but `column-1` points to the same in both js/ts
+			// https://github.com/vitejs/vite/issues/8657
 			stack.column--;
+			// reject multiple inline snapshots at the same location if snapshot is different
 			const snapshotsWithSameStack = this._inlineSnapshotStacks.filter((s) => isSameStackPosition(s, stack));
 			if (snapshotsWithSameStack.length > 0) {
+				// ensure only one snapshot will be written at the same location
 				this._inlineSnapshots = this._inlineSnapshots.filter((s) => !isSameStackPosition(s, stack));
 				const differentSnapshot = snapshotsWithSameStack.find((s) => s.snapshot !== receivedSerialized);
 				if (differentSnapshot) {
@@ -2035,6 +2119,13 @@ class SnapshotState {
 				snapshot: receivedSerialized
 			});
 		}
+		// These are the conditions on when to write snapshots:
+		//  * There's no snapshot file in a non-CI environment.
+		//  * There is a snapshot file and we decided to update the snapshot.
+		//  * There is a snapshot file, but it doesn't have this snapshot.
+		// These are the conditions on when not to write snapshots:
+		//  * The update flag is set to 'none'.
+		//  * There's no snapshot file or a file without this snapshot on a CI environment.
 		if (hasSnapshot && this._updateSnapshot === "all" || (!hasSnapshot || !snapshotIsPersisted) && (this._updateSnapshot === "new" || this._updateSnapshot === "all")) {
 			if (this._updateSnapshot === "all") {
 				if (!pass) {
@@ -2179,6 +2270,7 @@ class SnapshotClient {
 			try {
 				var _this$options$isEqual, _this$options;
 				const pass = ((_this$options$isEqual = (_this$options = this.options).isEqual) === null || _this$options$isEqual === void 0 ? void 0 : _this$options$isEqual.call(_this$options, received, properties)) ?? false;
+				// const pass = equals(received, properties, [iterableEquality, subsetEquality])
 				if (!pass) {
 					throw createMismatchError("Snapshot properties mismatched", snapshotState.expand, received, properties);
 				} else {
@@ -2213,7 +2305,9 @@ class SnapshotClient {
 				throw new Error("Snapshot cannot be used outside of test");
 			}
 			const snapshotState = this.getSnapshotState(filepath);
+			// save the filepath, so it don't lose even if the await make it out-of-context
 			options.filepath || (options.filepath = filepath);
+			// resolve and read the raw snapshot file
 			rawSnapshot.file = await snapshotState.environment.resolveRawPath(filepath, rawSnapshot.file);
 			rawSnapshot.content = await snapshotState.environment.readSnapshotFile(rawSnapshot.file) ?? undefined;
 		}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vitest/snapshot",
   "type": "module",
-  "version": "3.2.0-beta.2",
+  "version": "3.2.0",
   "description": "Vitest snapshot manager",
   "license": "MIT",
   "funding": "https://opencollective.com/vitest",
@@ -40,12 +40,12 @@
   "dependencies": {
     "magic-string": "^0.30.17",
     "pathe": "^2.0.3",
-    "@vitest/pretty-format": "3.2.0-beta.2"
+    "@vitest/pretty-format": "3.2.0"
   },
   "devDependencies": {
     "@types/natural-compare": "^1.4.3",
     "natural-compare": "^1.4.0",
-    "@vitest/utils": "3.2.0-beta.2"
+    "@vitest/utils": "3.2.0"
   },
   "scripts": {
     "build": "rimraf dist && rollup -c",