diff --git a/doc/api/assert.md b/doc/api/assert.md index 3f44dffbe7d..32740d2f303 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -804,8 +804,10 @@ are recursively evaluated also by the following rules. * [`Map`][] keys and [`Set`][] items are compared unordered. * Recursion stops when both sides differ or both sides encounter a circular reference. -* [`WeakMap`][] and [`WeakSet`][] comparison does not rely on their values. See - below for further details. +* [`WeakMap`][] and [`WeakSet`][] instances are **not** compared structurally. + They are only equal if they reference the same object. Any comparison between + different `WeakMap` or `WeakSet` instances will result in inequality, + even if they contain the same entries. * [`RegExp`][] lastIndex, flags, and source are always compared, even if these are not enumerable properties. @@ -882,23 +884,40 @@ assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 }); // } const weakMap1 = new WeakMap(); -const weakMap2 = new WeakMap([[{}, {}]]); -const weakMap3 = new WeakMap(); -weakMap3.unequal = true; +const weakMap2 = new WeakMap(); +const obj = {}; +weakMap1.set(obj, 'value'); +weakMap2.set(obj, 'value'); + +// Comparing different instances fails, even with same contents assert.deepStrictEqual(weakMap1, weakMap2); -// OK, because it is impossible to compare the entries +// AssertionError: Values have same structure but are not reference-equal: +// +// WeakMap { +// +// } -// Fails because weakMap3 has a property that weakMap1 does not contain: -assert.deepStrictEqual(weakMap1, weakMap3); +// Comparing the same instance to itself succeeds +assert.deepStrictEqual(weakMap1, weakMap1); +// OK + +const weakSet1 = new WeakSet(); +const weakSet2 = new WeakSet(); +weakSet1.add(obj); +weakSet2.add(obj); + +// Comparing different instances fails, even with same contents +assert.deepStrictEqual(weakSet1, weakSet2); // AssertionError: Expected inputs to be strictly deep-equal: // + actual - expected // -// WeakMap { -// + [items unknown] -// - [items unknown], -// - unequal: true -// } +// + WeakSet { } +// - WeakSet { } + +// Comparing the same instance to itself succeeds +assert.deepStrictEqual(weakSet1, weakSet1); +// OK ``` ```cjs @@ -974,23 +993,40 @@ assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 }); // } const weakMap1 = new WeakMap(); -const weakMap2 = new WeakMap([[{}, {}]]); -const weakMap3 = new WeakMap(); -weakMap3.unequal = true; +const weakMap2 = new WeakMap(); +const obj = {}; +weakMap1.set(obj, 'value'); +weakMap2.set(obj, 'value'); + +// Comparing different instances fails, even with same contents assert.deepStrictEqual(weakMap1, weakMap2); -// OK, because it is impossible to compare the entries +// AssertionError: Values have same structure but are not reference-equal: +// +// WeakMap { +// +// } -// Fails because weakMap3 has a property that weakMap1 does not contain: -assert.deepStrictEqual(weakMap1, weakMap3); +// Comparing the same instance to itself succeeds +assert.deepStrictEqual(weakMap1, weakMap1); +// OK + +const weakSet1 = new WeakSet(); +const weakSet2 = new WeakSet(); +weakSet1.add(obj); +weakSet2.add(obj); + +// Comparing different instances fails, even with same contents +assert.deepStrictEqual(weakSet1, weakSet2); // AssertionError: Expected inputs to be strictly deep-equal: // + actual - expected // -// WeakMap { -// + [items unknown] -// - [items unknown], -// - unequal: true -// } +// + WeakSet { } +// - WeakSet { } + +// Comparing the same instance to itself succeeds +assert.deepStrictEqual(weakSet1, weakSet1); +// OK ``` If the values are not equal, an [`AssertionError`][] is thrown with a `message`