@vitest/expect 3.2.0-beta.1 → 3.2.0-beta.3

package/dist/index.js

@@ -10,6 +10,7 @@ const JEST_MATCHERS_OBJECT = Symbol.for("$$jest-matchers-object");
 const GLOBAL_EXPECT = Symbol.for("expect-global");
 const ASYMMETRIC_MATCHERS_OBJECT = Symbol.for("asymmetric-matchers-object");
 
+// selectively ported from https://github.com/jest-community/jest-extended
 const customMatchers = {
 	toSatisfy(actual, expected, message) {
 		const { printReceived, printExpected, matcherHint } = this.utils;
@@ -81,8 +82,11 @@ function matcherHint(matcherName, received = "received", expected = "expected",
 		dimString = "";
 	}
 	if (matcherName.includes(".")) {
+		// Old format: for backward compatibility,
+		// especially without promise or isNot options
 		dimString += matcherName;
 	} else {
+		// New format: omit period from matcherName arg
 		hint += DIM_COLOR(`${dimString}.`) + matcherName;
 		dimString = "";
 	}
@@ -104,6 +108,8 @@ function matcherHint(matcherName, received = "received", expected = "expected",
 	return hint;
 }
 const SPACE_SYMBOL = "·";
+// Instead of inverse highlight which now implies a change,
+// replace common spaces with middle dot at the end of any line.
 function replaceTrailingSpaces(text) {
 	return text.replace(/\s+$/gm, (spaces) => SPACE_SYMBOL.repeat(spaces.length));
 }
@@ -144,6 +150,7 @@ function getCustomEqualityTesters() {
 	return globalThis[JEST_MATCHERS_OBJECT].customEqualityTesters;
 }
 
+// Extracted out of jasmine 2.5.2
 function equals(a, b, customTesters, strictCheck) {
 	customTesters = customTesters || [];
 	return eq(a, b, [], [], customTesters, strictCheck ? hasKey : hasDefinedKey);
@@ -184,6 +191,8 @@ function asymmetricMatch(a, b) {
 		return b.asymmetricMatch(a);
 	}
 }
+// Equality function lovingly adapted from isEqual in
+//   [Underscore](http://underscorejs.org)
 function eq(a, b, aStack, bStack, customTesters, hasKey) {
 	let result = true;
 	const asymmetricResult = asymmetricMatch(a, b);
@@ -203,6 +212,7 @@ function eq(a, b, aStack, bStack, customTesters, hasKey) {
 	if (Object.is(a, b)) {
 		return true;
 	}
+	// A strict comparison is necessary because `null == undefined`.
 	if (a === null || b === null) {
 		return a === b;
 	}
@@ -214,35 +224,58 @@ function eq(a, b, aStack, bStack, customTesters, hasKey) {
 		case "[object Boolean]":
 		case "[object String]":
 		case "[object Number]": if (typeof a !== typeof b) {
+			// One is a primitive, one a `new Primitive()`
 			return false;
 		} else if (typeof a !== "object" && typeof b !== "object") {
+			// both are proper primitives
 			return Object.is(a, b);
 		} else {
+			// both are `new Primitive()`s
 			return Object.is(a.valueOf(), b.valueOf());
 		}
 		case "[object Date]": {
 			const numA = +a;
 			const numB = +b;
+			// Coerce dates to numeric primitive values. Dates are compared by their
+			// millisecond representations. Note that invalid dates with millisecond representations
+			// of `NaN` are equivalent.
 			return numA === numB || Number.isNaN(numA) && Number.isNaN(numB);
 		}
 		case "[object RegExp]": return a.source === b.source && a.flags === b.flags;
+		case "[object Temporal.Instant]":
+		case "[object Temporal.ZonedDateTime]":
+		case "[object Temporal.PlainDateTime]":
+		case "[object Temporal.PlainDate]":
+		case "[object Temporal.PlainTime]":
+		case "[object Temporal.PlainYearMonth]":
+		case "[object Temporal.PlainMonthDay]": return a.equals(b);
+		case "[object Temporal.Duration]": return a.toString() === b.toString();
 	}
 	if (typeof a !== "object" || typeof b !== "object") {
 		return false;
 	}
+	// Use DOM3 method isEqualNode (IE>=9)
 	if (isDomNode(a) && isDomNode(b)) {
 		return a.isEqualNode(b);
 	}
+	// Used to detect circular references.
 	let length = aStack.length;
 	while (length--) {
+		// Linear search. Performance is inversely proportional to the number of
+		// unique nested structures.
+		// circular references at same depth are equal
+		// circular reference is not equal to non-circular one
 		if (aStack[length] === a) {
 			return bStack[length] === b;
 		} else if (bStack[length] === b) {
 			return false;
 		}
 	}
+	// Add the first object to the stack of traversed objects.
 	aStack.push(a);
 	bStack.push(b);
+	// Recursively compare objects and arrays.
+	// Compare array lengths to determine if a deep comparison is necessary.
 	if (className === "[object Array]" && a.length !== b.length) {
 		return false;
 	}
@@ -254,31 +287,42 @@ function eq(a, b, aStack, bStack, customTesters, hasKey) {
 			bStack.pop();
 		}
 	}
+	// Deep compare objects.
 	const aKeys = keys(a, hasKey);
 	let key;
 	let size = aKeys.length;
+	// Ensure that both objects contain the same number of properties before comparing deep equality.
 	if (keys(b, hasKey).length !== size) {
 		return false;
 	}
 	while (size--) {
 		key = aKeys[size];
+		// Deep compare each member
 		result = hasKey(b, key) && eq(a[key], b[key], aStack, bStack, customTesters, hasKey);
 		if (!result) {
 			return false;
 		}
 	}
+	// Remove the first object from the stack of traversed objects.
 	aStack.pop();
 	bStack.pop();
 	return result;
 }
 function isErrorEqual(a, b, aStack, bStack, customTesters, hasKey) {
+	// https://nodejs.org/docs/latest-v22.x/api/assert.html#comparison-details
+	// - [[Prototype]] of objects are compared using the === operator.
+	// - Only enumerable "own" properties are considered.
+	// - Error names, messages, causes, and errors are always compared, even if these are not enumerable properties. errors is also compared.
 	let result = Object.getPrototypeOf(a) === Object.getPrototypeOf(b) && a.name === b.name && a.message === b.message;
+	// check Error.cause asymmetrically
 	if (typeof b.cause !== "undefined") {
 		result && (result = eq(a.cause, b.cause, aStack, bStack, customTesters, hasKey));
 	}
+	// AggregateError.errors
 	if (a instanceof AggregateError && b instanceof AggregateError) {
 		result && (result = eq(a.errors, b.errors, aStack, bStack, customTesters, hasKey));
 	}
+	// spread to compare enumerable properties
 	result && (result = eq({ ...a }, { ...b }, aStack, bStack, customTesters, hasKey));
 	return result;
 }
@@ -328,6 +372,7 @@ function hasProperty(obj, property) {
 	}
 	return hasProperty(getPrototype(obj), property);
 }
+// SENTINEL constants are from https://github.com/facebook/immutable-js
 const IS_KEYED_SENTINEL = "@@__IMMUTABLE_KEYED__@@";
 const IS_SET_SENTINEL = "@@__IMMUTABLE_SET__@@";
 const IS_LIST_SENTINEL = "@@__IMMUTABLE_LIST__@@";
@@ -374,6 +419,10 @@ function iterableEquality(a, b, customTesters = [], aStack = [], bStack = []) {
 	}
 	let length = aStack.length;
 	while (length--) {
+		// Linear search. Performance is inversely proportional to the number of
+		// unique nested structures.
+		// circular references at same depth are equal
+		// circular reference is not equal to non-circular one
 		if (aStack[length] === a) {
 			return bStack[length] === b;
 		}
@@ -404,6 +453,7 @@ function iterableEquality(a, b, customTesters = [], aStack = [], bStack = []) {
 					}
 				}
 			}
+			// Remove the first value from the stack of traversed values.
 			aStack.pop();
 			bStack.pop();
 			return allFound;
@@ -428,6 +478,7 @@ function iterableEquality(a, b, customTesters = [], aStack = [], bStack = []) {
 					}
 				}
 			}
+			// Remove the first value from the stack of traversed values.
 			aStack.pop();
 			bStack.pop();
 			return allFound;
@@ -446,10 +497,11 @@ function iterableEquality(a, b, customTesters = [], aStack = [], bStack = []) {
 	if (!isImmutableList(a) && !isImmutableOrderedKeyed(a) && !isImmutableOrderedSet(a) && !isImmutableRecord(a)) {
 		const aEntries = Object.entries(a);
 		const bEntries = Object.entries(b);
-		if (!equals(aEntries, bEntries)) {
+		if (!equals(aEntries, bEntries, filteredCustomTesters)) {
 			return false;
 		}
 	}
+	// Remove the first value from the stack of traversed values.
 	aStack.pop();
 	bStack.pop();
 	return true;
@@ -469,6 +521,9 @@ function isObjectWithKeys(a) {
 }
 function subsetEquality(object, subset, customTesters = []) {
 	const filteredCustomTesters = customTesters.filter((t) => t !== subsetEquality);
+	// subsetEquality needs to keep track of the references
+	// it has already visited to avoid infinite loops in case
+	// there are circular references in the subset passed to it.
 	const subsetEqualityWithContext = (seenReferences = new WeakMap()) => (object, subset) => {
 		if (!isObjectWithKeys(subset)) {
 			return undefined;
@@ -481,6 +536,11 @@ function subsetEquality(object, subset, customTesters = []) {
 				seenReferences.set(subset[key], true);
 			}
 			const result = object != null && hasPropertyInObject(object, key) && equals(object[key], subset[key], [...filteredCustomTesters, subsetEqualityWithContext(seenReferences)]);
+			// The main goal of using seenReference is to avoid circular node on tree.
+			// It will only happen within a parent and its child, not a node and nodes next to it (same level)
+			// We should keep the reference for a parent and its child only
+			// Thus we should delete the reference immediately so that it doesn't interfere
+			// other nodes within the same level on tree.
 			seenReferences.delete(subset[key]);
 			return result;
 		});
@@ -507,9 +567,11 @@ function arrayBufferEquality(a, b) {
 			return undefined;
 		}
 	}
+	// Buffers are not equal when they do not have the same byte length
 	if (dataViewA.byteLength !== dataViewB.byteLength) {
 		return false;
 	}
+	// Check if every byte value is equal to each other
 	for (let i = 0; i < dataViewA.byteLength; i++) {
 		if (dataViewA.getUint8(i) !== dataViewB.getUint8(i)) {
 			return false;
@@ -521,6 +583,7 @@ function sparseArrayEquality(a, b, customTesters = []) {
 	if (!Array.isArray(a) || !Array.isArray(b)) {
 		return undefined;
 	}
+	// A sparse array [, , 1] will have keys ["2"] whereas [undefined, undefined, 1] will have keys ["0", "1", "2"]
 	const aKeys = Object.keys(a);
 	const bKeys = Object.keys(b);
 	const filteredCustomTesters = customTesters.filter((t) => t !== sparseArrayEquality);
@@ -547,6 +610,7 @@ function getObjectSubset(object, subset, customTesters) {
 	const getObjectSubsetWithContext = (seenReferences = new WeakMap()) => (object, subset) => {
 		if (Array.isArray(object)) {
 			if (Array.isArray(subset) && subset.length === object.length) {
+				// The map method returns correct subclass of subset.
 				return subset.map((sub, i) => getObjectSubsetWithContext(seenReferences)(object[i], sub));
 			}
 		} else if (object instanceof Date) {
@@ -557,10 +621,12 @@ function getObjectSubset(object, subset, customTesters) {
 				iterableEquality,
 				subsetEquality
 			])) {
+				// return "expected" subset to avoid showing irrelevant toMatchObject diff
 				return subset;
 			}
 			const trimmed = {};
 			seenReferences.set(object, trimmed);
+			// preserve constructor for toMatchObject diff
 			if (typeof object.constructor === "function" && typeof object.constructor.name === "string") {
 				Object.defineProperty(trimmed, "constructor", {
 					enumerable: false,
@@ -614,6 +680,7 @@ function getState(expect) {
 function setState(state, expect) {
 	const map = globalThis[MATCHERS_OBJECT];
 	const current = map.get(expect) || {};
+	// so it keeps getters from `testPath`
 	const results = Object.defineProperties(current, {
 		...Object.getOwnPropertyDescriptors(current),
 		...Object.getOwnPropertyDescriptors(state)
@@ -622,6 +689,7 @@ function setState(state, expect) {
 }
 
 class AsymmetricMatcher {
+	// should have "jest" to be compatible with its ecosystem
 	$$typeof = Symbol.for("jest.asymmetricMatcher");
 	constructor(sample, inverse = false) {
 		this.sample = sample;
@@ -643,7 +711,12 @@ class AsymmetricMatcher {
 		};
 	}
 }
+// implement custom chai/loupe inspect for better AssertionError.message formatting
+// https://github.com/chaijs/loupe/blob/9b8a6deabcd50adc056a64fb705896194710c5c6/src/index.ts#L29
+// @ts-expect-error computed properties is not supported when isolatedDeclarations is enabled
+// FIXME: https://github.com/microsoft/TypeScript/issues/61068
 AsymmetricMatcher.prototype[Symbol.for("chai/inspect")] = function(options) {
+	// minimal pretty-format with simple manual truncation
 	const result = stringify(this, options.depth, { min: true });
 	if (result.length <= options.truncate) {
 		return result;
@@ -872,6 +945,7 @@ const JestAsymmetricMatchers = (chai, utils) => {
 	utils.addMethod(chai.expect, "arrayContaining", (expected) => new ArrayContaining(expected));
 	utils.addMethod(chai.expect, "stringMatching", (expected) => new StringMatching(expected));
 	utils.addMethod(chai.expect, "closeTo", (expected, precision) => new CloseTo(expected, precision));
+	// defineProperty does not work
 	chai.expect.not = {
 		stringContaining: (expected) => new StringContaining(expected, true),
 		objectContaining: (expected) => new ObjectContaining(expected, true),
@@ -890,7 +964,9 @@ function createAssertionMessage(util, assertion, hasArgs) {
 }
 function recordAsyncExpect(_test, promise, assertion, error) {
 	const test = _test;
+	// record promise for test, that resolves before test ends
 	if (test && promise instanceof Promise) {
+		// if promise is explicitly awaited, remove it from the list
 		promise = promise.finally(() => {
 			if (!test.promises) {
 				return;
@@ -900,6 +976,7 @@ function recordAsyncExpect(_test, promise, assertion, error) {
 				test.promises.splice(index, 1);
 			}
 		});
+		// record promise
 		if (!test.promises) {
 			test.promises = [];
 		}
@@ -937,6 +1014,7 @@ function recordAsyncExpect(_test, promise, assertion, error) {
 }
 function wrapAssertion(utils, name, fn) {
 	return function(...args) {
+		// private
 		if (name !== "withTest") {
 			utils.flag(this, "_name", name);
 		}
@@ -959,6 +1037,7 @@ function wrapAssertion(utils, name, fn) {
 	};
 }
 
+// Jest Expect Compact
 const JestChaiExpect = (chai, utils) => {
 	const { AssertionError } = chai;
 	const customTesters = getCustomEqualityTesters();
@@ -1001,6 +1080,7 @@ const JestChaiExpect = (chai, utils) => {
 			};
 		});
 	});
+	// @ts-expect-error @internal
 	def("withTest", function(test) {
 		utils.flag(this, "vitest-test", test);
 		return this;
@@ -1091,9 +1171,11 @@ const JestChaiExpect = (chai, utils) => {
 			const expectedClassList = isNot ? actual.value.replace(item, "").trim() : `${actual.value} ${item}`;
 			return this.assert(actual.contains(item), `expected "${actual.value}" to contain "${item}"`, `expected "${actual.value}" not to contain "${item}"`, expectedClassList, actual.value);
 		}
+		// handle simple case on our own using `this.assert` to include diff in error message
 		if (typeof actual === "string" && typeof item === "string") {
 			return this.assert(actual.includes(item), `expected #{this} to contain #{exp}`, `expected #{this} not to contain #{exp}`, item, actual);
 		}
+		// make "actual" indexable to have compatibility with jest
 		if (actual != null && typeof actual !== "string") {
 			utils.flag(this, "object", Array.from(actual));
 		}
@@ -1165,6 +1247,7 @@ const JestChaiExpect = (chai, utils) => {
 	def("toHaveLength", function(length) {
 		return this.have.length(length);
 	});
+	// destructuring, because it checks `arguments` inside, and value is passing as `undefined`
 	def("toHaveProperty", function(...args) {
 		if (Array.isArray(args[0])) {
 			args[0] = args[0].map((key) => String(key).replace(/([.[\]])/g, "\\$1")).join(".");
@@ -1243,6 +1326,8 @@ const JestChaiExpect = (chai, utils) => {
 			throw new AssertionError(msg);
 		}
 	});
+	// manually compare array elements since `jestEquals` cannot
+	// apply asymmetric matcher to `undefined` array element.
 	function equalsArgumentArray(a, b) {
 		return a.length === b.length && a.every((aItem, i) => equals(aItem, b[i], [...customTesters, iterableEquality]));
 	}
@@ -1322,6 +1407,7 @@ const JestChaiExpect = (chai, utils) => {
 	});
 	def(["toThrow", "toThrowError"], function(expected) {
 		if (typeof expected === "string" || typeof expected === "undefined" || expected instanceof RegExp) {
+			// Fixes the issue related to `chai` <https://github.com/vitest-dev/vitest/issues/6618>
 			return this.throws(expected === "" ? /^$/ : expected);
 		}
 		const obj = this._obj;
@@ -1444,14 +1530,7 @@ const JestChaiExpect = (chai, utils) => {
 			const results = action === "return" ? spy.mock.results : spy.mock.settledResults;
 			const result = results[results.length - 1];
 			const spyName = spy.getMockName();
-			this.assert(
-				condition(spy, value),
-				`expected last "${spyName}" call to ${action} #{exp}`,
-				`expected last "${spyName}" call to not ${action} #{exp}`,
-				value,
-				// for jest compat
-				result === null || result === void 0 ? void 0 : result.value
-);
+			this.assert(condition(spy, value), `expected last "${spyName}" call to ${action} #{exp}`, `expected last "${spyName}" call to not ${action} #{exp}`, value, result === null || result === void 0 ? void 0 : result.value);
 		});
 	});
 	[{
@@ -1478,6 +1557,7 @@ const JestChaiExpect = (chai, utils) => {
 			this.assert(condition(spy, nthCall, value), `expected ${ordinalCall} "${spyName}" call to ${action} #{exp}`, `expected ${ordinalCall} "${spyName}" call to not ${action} #{exp}`, value, result === null || result === void 0 ? void 0 : result.value);
 		});
 	});
+	// @ts-expect-error @internal
 	def("withContext", function(context) {
 		for (const key in context) {
 			utils.flag(this, key, context[key]);
@@ -1689,6 +1769,8 @@ function JestExtendPlugin(c, expect, matchers) {
 				value: (...sample) => new CustomMatcher(true, ...sample),
 				writable: true
 			});
+			// keep track of asymmetric matchers on global so that it can be copied over to local context's `expect`.
+			// note that the negated variant is automatically shared since it's assigned on the single `expect.not` object.
 			Object.defineProperty(globalThis[ASYMMETRIC_MATCHERS_OBJECT], expectAssertionName, {
 				configurable: true,
 				enumerable: true,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vitest/expect",
   "type": "module",
-  "version": "3.2.0-beta.1",
+  "version": "3.2.0-beta.3",
   "description": "Jest's expect matchers as a Chai plugin",
   "license": "MIT",
   "funding": "https://opencollective.com/vitest",
@@ -30,15 +30,15 @@
     "dist"
   ],
   "dependencies": {
+    "@types/chai": "^5.2.2",
     "chai": "^5.2.0",
     "tinyrainbow": "^2.0.0",
-    "@vitest/spy": "3.2.0-beta.1",
-    "@vitest/utils": "3.2.0-beta.1"
+    "@vitest/utils": "3.2.0-beta.3",
+    "@vitest/spy": "3.2.0-beta.3"
   },
   "devDependencies": {
-    "@types/chai": "5.0.1",
     "rollup-plugin-copy": "^3.5.0",
-    "@vitest/runner": "3.2.0-beta.1"
+    "@vitest/runner": "3.2.0-beta.3"
   },
   "scripts": {
     "build": "rimraf dist && rollup -c",