assert: add partialDeepStrictEqual

[puskin94]

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

Co-Authored-By: Cristian Barlutiu

[codecov]

Codecov Report

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

Project coverage is 88.42%. Comparing base (4f88179) to head (6ac494a).
Report is 408 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #54630      +/-   ##
==========================================
+ Coverage   88.23%   88.42%   +0.18%     
==========================================
  Files         652      654       +2     
  Lines      183920   188060    +4140     
  Branches    35863    36190     +327     
==========================================
+ Hits       162286   166295    +4009     
- Misses      14913    15003      +90     
- Partials     6721     6762      +41     

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

... and 283 files with indirect coverage changes

[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.

[RedYetiDev]

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))

[puskin94]

@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.

[puskin94]

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?

[puskin94]

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

[puskin94]

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"?

[puskin94]

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"?)

[puskin94]

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

[RedYetiDev]

+1 for partialDeepEqual

Agreed. Also, should this have a notPartialDeepEqual inverse?

[puskin94]

Fixed the issue with the comparison between objects in Sets, updated the commit message and the documentation

[tniessen]

Fixed the issue with the comparison between objects in Sets

I checked out f0722f9. Is this expected behavior?

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

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/63477/

[puskin94]

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

you are right, I might have introduced that issue in the last commit. Fixed and added relevant tests :)

[marco-ippolito]

LGTM

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/63481/

[tniessen]

I still think this function deserves a precise definition of its behavior. The two Set-related bugs that I discovered today could have been expected behavior for all I know.

Looking at the implementation, objects in Sets are apparently not tested for reference-equality, but objects in Arrays are. Again, I have no idea if that is expected behavior or not.

assert.deepStrictEqual([{ a: 5 }], [{ a: 5 }])
// No error.

assert.partialDeepStrictEqual([{ a: 5 }], [{ a: 5 }])
// AssertionError.

Also, the order of elements of Arrays is ignored for the purpose of this assertion, and holes in sparse arrays are ignored as well. I again have no idea if that is expected or not, but as a user, I certainly wouldn't expect it based on the documentation.

[puskin94]

I still think this function deserves a precise definition of its behavior. The two Set-related bugs that I discovered today could have been expected behavior for all I know.

Looking at the implementation, objects in Sets are apparently not tested for reference-equality, but objects in Arrays are. Again, I have no idea if that is expected behavior or not.

assert.deepStrictEqual([{ a: 5 }], [{ a: 5 }])
// No error.

assert.partialDeepStrictEqual([{ a: 5 }], [{ a: 5 }])
// AssertionError.

Also, the order of elements of Arrays is ignored for the purpose of this assertion, and holes in sparse arrays are ignored as well. I again have no idea if that is expected or not, but as a user, I certainly wouldn't expect it based on the documentation.

I would consider what you found an issue, I will fix the code soon, but I would like other people to chip in on how this case should work according to them

[BridgeAR]

I think this could land as experimental and we explicitly mention that this should always pass deepStrictEqual(). So it's like a superset of that. I also think we should verify that later on and improving the code accordingly.

@puskin94 would you mind adding that?

[tniessen]

I think this could land as experimental and we explicitly mention that this should always pass deepStrictEqual(). So it's like a superset of that.

I agree with the general strategy, but I think it'd be a good idea for the documentation to accurately define what superset of input pairs are permitted that are not allowed by deepStrictEqual. Otherwise, users have no way of knowing whether they are relying on expected behavior or on bugs.

[BridgeAR]

I think it will still be refined during the development. And while doing that, we should define it.
It is marked as experimental because it's not yet where it should be.

[danielbayley]

I still think this function deserves a precise definition of its behavior. The two Set-related bugs that I discovered today could have been expected behavior for all I know.
Looking at the implementation, objects in Sets are apparently not tested for reference-equality, but objects in Arrays are. Again, I have no idea if that is expected behavior or not.

assert.deepStrictEqual([{ a: 5 }], [{ a: 5 }])
// No error.

assert.partialDeepStrictEqual([{ a: 5 }], [{ a: 5 }])
// AssertionError.

Also, the order of elements of Arrays is ignored for the purpose of this assertion, and holes in sparse arrays are ignored as well. I again have no idea if that is expected or not, but as a user, I certainly wouldn't expect it based on the documentation.

I would consider what you found an issue, I will fix the code soon, but I would like other people to chip in on how this case should work according to them

Would these different behaviours not be best expressed as boolean props of an optional object passed as the last argument to these functions? Something like:

assert.deepStrictEqual([1, 2, 3], [3, 1, 2]) // pass

assert.deepStrictEqual([1, 2, 3], [3, 1, 2], { order: true }) // fail

[tniessen]

@danielbayley The problem with such options is that it's unclear whether or not they should apply to nested decision procedures. Neither option will cover all use cases.

[aduh95]

Tests are failing