assert: add partialDeepStrictEqual

Fixes: #50399 Co-Authored-By: Cristian Barlutiu <[email protected]> PR-URL: #54630 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Moshe Atlow <[email protected]> Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Chemi Atlow <[email protected]> Reviewed-By: Ruben Bridgewater <[email protected]> Reviewed-By: Jithil P Ponnan <[email protected]> Reviewed-By: Marco Ippolito <[email protected]>

Author: 2 people

doc/api/assert.md

@@ -2548,6 +2548,96 @@ assert.throws(throwingFirst, /Second$/);
 Due to the confusing error-prone notation, avoid a string as the second
 argument.
 
+## `assert.partialDeepStrictEqual(actual, expected[, message])`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+*`actual`{any}
+*`expected`{any}
+*`message`{string|Error}
+
+[`assert.partialDeepStrictEqual()`][] Asserts the equivalence between the `actual` and `expected` parameters through a
+deep comparison, ensuring that all properties in the `expected` parameter are
+present in the `actual` parameter with equivalent values, not allowing type coercion.
+The main difference with [`assert.deepStrictEqual()`][] is that [`assert.partialDeepStrictEqual()`][] does not require
+all properties in the `actual` parameter to be present in the `expected` parameter.
+This method should always pass the same test cases as [`assert.deepStrictEqual()`][], behaving as a super set of it.
+
+```mjs
+importassertfrom'node:assert';
+
+assert.partialDeepStrictEqual({a:1, b:2 },{a:1, b:2 });
+// OK
+
+assert.partialDeepStrictEqual({a:{b:{c:1 } } },{a:{b:{c:1 } } });
+// OK
+
+assert.partialDeepStrictEqual({a:1, b:2, c:3 },{a:1, b:2 });
+// OK
+
+assert.partialDeepStrictEqual(newSet(['value1', 'value2']), newSet(['value1', 'value2']));
+// OK
+
+assert.partialDeepStrictEqual(newMap([['key1', 'value1']]), newMap([['key1', 'value1']]));
+// OK
+
+assert.partialDeepStrictEqual(newUint8Array([1, 2, 3]), newUint8Array([1, 2, 3]));
+// OK
+
+assert.partialDeepStrictEqual(/abc/,/abc/);
+// OK
+
+assert.partialDeepStrictEqual([{a:5 },{b:5 }], [{a:5 }]);
+// OK
+
+assert.partialDeepStrictEqual(newSet([{a:1 },{b:1 }]), newSet([{a:1 }]));
+// OK
+
+assert.partialDeepStrictEqual(newDate(0), newDate(0));
+// OK
+
+assert.partialDeepStrictEqual({a:1 },{a:1, b:2 });
+// AssertionError
+
+assert.partialDeepStrictEqual({a:1, b:'2' },{a:1, b:2 });
+// AssertionError
+
+assert.partialDeepStrictEqual({a:{b:2 } },{a:{b:'2' } });
+// AssertionError
+```
+
+```cjs
+constassert=require('node:assert');
+
+assert.partialDeepStrictEqual({a:1, b:2 },{a:1, b:2 });
+// OK
+
+assert.partialDeepStrictEqual({a:{b:{c:1 } } },{a:{b:{c:1 } } });
+// OK
+
+assert.partialDeepStrictEqual({a:1, b:2, c:3 },{a:1, b:2 });
+// OK
+
+assert.partialDeepStrictEqual([{a:5 },{b:5 }], [{a:5 }]);
+// OK
+
+assert.partialDeepStrictEqual(newSet([{a:1 },{b:1 }]), newSet([{a:1 }]));
+// OK
+
+assert.partialDeepStrictEqual({a:1 },{a:1, b:2 });
+// AssertionError
+
+assert.partialDeepStrictEqual({a:1, b:'2' },{a:1, b:2 });
+// AssertionError
+
+assert.partialDeepStrictEqual({a:{b:2 } },{a:{b:'2' } });
+// AssertionError
+```
+
 [Object wrappers]: https://developer.mozilla.org/en-US/docs/Glossary/Primitive#Primitive_wrapper_objects_in_JavaScript
 [Object.prototype.toString()]: https://tc39.github.io/ecma262/#sec-object.prototype.tostring
 [`!=` operator]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Inequality
@@ -2576,6 +2666,7 @@ argument.
 [`assert.notEqual()`]: #assertnotequalactual-expected-message
 [`assert.notStrictEqual()`]: #assertnotstrictequalactual-expected-message
 [`assert.ok()`]: #assertokvalue-message
+[`assert.partialDeepStrictEqual()`]: #assertpartialdeepstrictequalactual-expected-message
 [`assert.strictEqual()`]: #assertstrictequalactual-expected-message
 [`assert.throws()`]: #assertthrowsfn-error-message
 [`getColorDepth()`]: tty.md#writestreamgetcolordepthenv

lib/assert.js

@@ -21,22 +21,35 @@
 'use strict';
 
 const{
+ ArrayFrom,
+ ArrayIsArray,
  ArrayPrototypeIndexOf,
  ArrayPrototypeJoin,
  ArrayPrototypePush,
  ArrayPrototypeSlice,
  Error,
+ FunctionPrototypeCall,
+ MapPrototypeDelete,
+ MapPrototypeGet,
+ MapPrototypeHas,
+ MapPrototypeSet,
  NumberIsNaN,
  ObjectAssign,
  ObjectIs,
  ObjectKeys,
  ObjectPrototypeIsPrototypeOf,
  ReflectApply,
+ ReflectHas,
+ ReflectOwnKeys,
  RegExpPrototypeExec,
+ SafeMap,
+ SafeSet,
+ SafeWeakSet,
  String,
  StringPrototypeIndexOf,
  StringPrototypeSlice,
  StringPrototypeSplit,
+ SymbolIterator,
 }=primordials;
 
 const{
@@ -50,8 +63,18 @@ const{
 }=require('internal/errors');
 constAssertionError=require('internal/assert/assertion_error');
 const{ inspect }=require('internal/util/inspect');
-const{ isPromise, isRegExp }=require('internal/util/types');
-const{ isError, deprecate }=require('internal/util');
+const{ Buffer }=require('buffer');
+const{
+ isKeyObject,
+ isPromise,
+ isRegExp,
+ isMap,
+ isSet,
+ isDate,
+ isWeakSet,
+ isWeakMap,
+}=require('internal/util/types');
+const{ isError, deprecate, emitExperimentalWarning }=require('internal/util');
 const{ innerOk }=require('internal/assert/utils');
 
 constCallTracker=require('internal/assert/calltracker');
@@ -341,6 +364,191 @@ assert.notStrictEqual = function notStrictEqual(actual, expected, message){
 }
 };
 
+functionisSpecial(obj){
+returnobj==null||typeofobj!=='object'||isError(obj)||isRegExp(obj)||isDate(obj);
+}
+
+consttypesToCallDeepStrictEqualWith=[
+isKeyObject,isWeakSet,isWeakMap,Buffer.isBuffer,
+];
+
+/**
+ * Compares two objects or values recursively to check if they are equal.
+ * @param{any} actual - The actual value to compare.
+ * @param{any} expected - The expected value to compare.
+ * @param{Set} [comparedObjects=new Set()] - Set to track compared objects for handling circular references.
+ * @returns{boolean} - Returns `true` if the actual value matches the expected value, otherwise `false`.
+ * @example
+ * compareBranch({a: 1, b: 2, c: 3},{a: 1, b: 2}); // true
+ */
+functioncompareBranch(
+actual,
+expected,
+comparedObjects,
+){
+// Check for Map object equality
+if(isMap(actual)&&isMap(expected)){
+if(actual.size!==expected.size){
+returnfalse;
+}
+constsafeIterator=FunctionPrototypeCall(SafeMap.prototype[SymbolIterator],actual);
+
+comparedObjects??=newSafeWeakSet();
+
+for(const{0: key,1: val}ofsafeIterator){
+if(!MapPrototypeHas(expected,key)){
+returnfalse;
+}
+if(!compareBranch(val,MapPrototypeGet(expected,key),comparedObjects)){
+returnfalse;
+}
+}
+returntrue;
+}
+
+for(consttypeoftypesToCallDeepStrictEqualWith){
+if(type(actual)||type(expected)){
+if(isDeepStrictEqual===undefined)lazyLoadComparison();
+returnisDeepStrictEqual(actual,expected);
+}
+}
+
+// Check for Set object equality
+// TODO(aduh95): switch to `SetPrototypeIsSubsetOf` when it's available
+if(isSet(actual)&&isSet(expected)){
+if(expected.size>actual.size){
+returnfalse;// `expected` can't be a subset if it has more elements
+}
+
+if(isDeepEqual===undefined)lazyLoadComparison();
+
+constactualArray=ArrayFrom(actual);
+constexpectedArray=ArrayFrom(expected);
+constusedIndices=newSafeSet();
+
+for(letexpectedIdx=0;expectedIdx<expectedArray.length;expectedIdx++){
+constexpectedItem=expectedArray[expectedIdx];
+letfound=false;
+
+for(letactualIdx=0;actualIdx<actualArray.length;actualIdx++){
+if(!usedIndices.has(actualIdx)&&isDeepStrictEqual(actualArray[actualIdx],expectedItem)){
+usedIndices.add(actualIdx);
+found=true;
+break;
+}
+}
+
+if(!found){
+returnfalse;
+}
+}
+
+returntrue;
+}
+
+// Check if expected array is a subset of actual array
+if(ArrayIsArray(actual)&&ArrayIsArray(expected)){
+if(expected.length>actual.length){
+returnfalse;
+}
+
+if(isDeepEqual===undefined)lazyLoadComparison();
+
+// Create a map to count occurrences of each element in the expected array
+constexpectedCounts=newSafeMap();
+for(constexpectedItemofexpected){
+letfound=false;
+for(const{0: key,1: count}ofexpectedCounts){
+if(isDeepStrictEqual(key,expectedItem)){
+MapPrototypeSet(expectedCounts,key,count+1);
+found=true;
+break;
+}
+}
+if(!found){
+MapPrototypeSet(expectedCounts,expectedItem,1);
+}
+}
+
+// Create a map to count occurrences of relevant elements in the actual array
+for(constactualItemofactual){
+for(const{0: key,1: count}ofexpectedCounts){
+if(isDeepStrictEqual(key,actualItem)){
+if(count===1){
+MapPrototypeDelete(expectedCounts,key);
+}else{
+MapPrototypeSet(expectedCounts,key,count-1);
+}
+break;
+}
+}
+}
+
+return!expectedCounts.size;
+}
+
+// Comparison done when at least one of the values is not an object
+if(isSpecial(actual)||isSpecial(expected)){
+if(isDeepEqual===undefined){
+lazyLoadComparison();
+}
+returnisDeepStrictEqual(actual,expected);
+}
+
+// Use Reflect.ownKeys() instead of Object.keys() to include symbol properties
+constkeysExpected=ReflectOwnKeys(expected);
+
+comparedObjects??=newSafeWeakSet();
+
+// Handle circular references
+if(comparedObjects.has(actual)){
+returntrue;
+}
+comparedObjects.add(actual);
+
+// Check if all expected keys and values match
+for(leti=0;i<keysExpected.length;i++){
+constkey=keysExpected[i];
+assert(
+ReflectHas(actual,key),
+newAssertionError({message: `Expected key ${String(key)} not found in actual object`}),
+);
+if(!compareBranch(actual[key],expected[key],comparedObjects)){
+returnfalse;
+}
+}
+
+returntrue;
+}
+
+/**
+ * The strict equivalence assertion test between two objects
+ * @param{any} actual
+ * @param{any} expected
+ * @param{string | Error} [message]
+ * @returns{void}
+ */
+assert.partialDeepStrictEqual=functionpartialDeepStrictEqual(
+actual,
+expected,
+message,
+){
+emitExperimentalWarning('assert.partialDeepStrictEqual');
+if(arguments.length<2){
+thrownewERR_MISSING_ARGS('actual','expected');
+}
+
+if(!compareBranch(actual,expected)){
+innerFail({
+ actual,
+ expected,
+ message,
+operator: 'partialDeepStrictEqual',
+stackStartFn: partialDeepStrictEqual,
+});
+}
+};
+
 classComparison{
 constructor(obj,keys,actual){
 for(constkeyofkeys){

lib/internal/test_runner/test.js

@@ -119,6 +119,7 @@ function lazyAssertObject(harness){
 'notDeepStrictEqual',
 'notEqual',
 'notStrictEqual',
+'partialDeepStrictEqual',
 'rejects',
 'strictEqual',
 'throws',