assert: add partialDeepStrictEqual

[puskin]

Fixes: #50399

Took heavy inspiration from #53415 , trying to push it to the finish line 🚀

On top of it, I took the liberty of:

1. refactor the code a bit
2. wrote more documentation
3. added more tests and restructured old ones
4. implement previously reported comments / suggestions

Notable change

Introducing experimental assert.partialDeepStrictEqual

Sometimes, when writing test, we want to validate that some specific properties
are present, and the mere presence of additional keys are not exactly relevant
for that specific test. For this use case, we can now use
assert.partialDeepStrictEqual, which should be familiar to those already using
assert.deepStrictEqual, with the main difference that it does not require all
properties in the actual parameter to be present in the expected parameter.

Here are a few examples of usage:

assert.partialDeepStrictEqual(
  { a: 1, b: 2, c: 3 },
  { a: 1, b: 2 },
);

assert.partialDeepStrictEqual(
  [1, 2, 3, 4],
  [2, 3],
);

assert.partialDeepStrictEqual(
  { a: { b: { c: 1, d: 2 } }, e: 3 },
  { a: { b: { c: 1 } } },
);

assert.partialDeepStrictEqual(
  { a: { b: { c: 1, d: 2 } }, e: 3 },
  { a: { b: { c: 1 } } },
);

assert.partialDeepStrictEqual(
  new Set([{ a: 1 }, { b: 1 }]),
  new Set([{ a: 1 }]),
);

assert.partialDeepStrictEqual(
  { a: new Set([{ a: 1 }, { b: 1 }]), b: new Map(), c: [1, 2, 3] },
  { a: new Set([{ a: 1 }]), c: [2] },
);

Co-Authored-By: Cristian Barlutiu

[codecov]

Codecov Report

Attention: Patch coverage is 95.73460% with 9 lines in your changes missing coverage. Please review.

Project coverage is 88.50%. Comparing base (4f88179) to head (8722fbd).
Report is 463 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/assert.js	95.71%	8 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #54630      +/-   ##
==========================================
+ Coverage   88.23%   88.50%   +0.26%     
==========================================
  Files         652      653       +1     
  Lines      183920   187937    +4017     
  Branches    35863    36233     +370     
==========================================
+ Hits       162286   166333    +4047     
+ Misses      14913    14827      -86     
- Partials     6721     6777      +56     

Files with missing lines	Coverage Δ
lib/internal/test_runner/test.js	96.97% <100.00%> (+0.03%)	⬆️
lib/assert.js	99.01% <95.71%> (-0.86%)	⬇️

... and 289 files with indirect coverage changes

---- 🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests
• JS Bundle Analysis - Avoid shipping oversized bundles

[github-actions]

The notable-change PRs with changes that should be highlighted in changelogs. label has been added by @redyetidev.

Please suggest a text for the release notes if you'd like to include a more detailed summary, then proceed to update the PR description with the text or a link to the notable change suggested text comment. Otherwise, the commit will be placed in the Other Notable Changes section.

[avivkeller]

This PR adds new functionality, hence semver-minor

This PR's new functionality (IMO) is notable-change

[jasnell]

I'm less convinced that this one is useful. Why not just simply use assert(actual.includes(expected))

[puskin]

@jasnell I just followed the most "approved" comment in the original PR and implemented it :)

#50399 (comment)

[BridgeAR]

I agree with @jasnell and don't think this should be implemented. Let us concentrate on the partial inclusion. If anyone would ever ask for something else, we can still implement more.

[puskin]

is there any way we can push this forward? ar far as I know there is a little bit of people waiting for this and no clear consensus on the naming convention :)

[jasnell]

I still have concerns about whether we need everything in this PR but would very much like others to weigh in. @nodejs/test_runner @nodejs/assert ... anyone have thoughts?

[ljharb]

re naming, I definitely think the term "match" should be reserved for regexes.

if the only difference between these new methods and deepEqual etc is that they allow extra properties, then perhaps it would make more sense as an option to the existing methods rather than entirely new ones?

[puskin]

@ljharb the discussion where the "option" was discarded in favor of the new API started from this comment: #50399 (comment)

[puskin]

other method names we could consider:

assert.subsetEqual() assert.containsSubset() assert.partialEqual()

[ljharb]

To clarify, the current proposal takes an "actual" and "expected", and it checks that every property on expected is deepEqual to the same property on actual? Are nested objects on expected checked using full or partial equality?

What about if I want to assert that a property is not present? is there a way to represent "never"?

[puskin]

good questions!

yes, this test will pass:

      {
        description: 'compares two deeply nested objects with partial equality',
        actual: { a: {nested: {property: true, some: 'other'}} },
        expected: { a: {nested: {property: true}} },
      },

and no, there is no way to check "not inclusion" , just if an object is a subset of another

[ljharb]

assert.subsetDeepEqual? (also shouldn't the default be strict, and the extra one be "Loose"?)

[puskin]

that would deviate from the already present implementations, like deepStrictEqual and deepEqual

[MoLow]

implementation LGTM, I agree with the concerns on naming, lets change the name so this can land?
+1 for partialDeepEqual

[avivkeller]

+1 for partialDeepEqual

Agreed. Also, should this have a notPartialDeepEqual inverse?