Document expect(.not).(array|object)Containing()'s actual behavior

[ninevra]

Summary

The existing documentation for expect.objectContaining(), expect.not.objectContaining(), and to a lesser degree expect.arrayContaining() and expect.not.arrayContaining() doesn't match their behavior. This has resulted in a number of issues (see #11126, #10462, #10186) and attempts to align the behavior with the documentation (see #10508, #10766, #10708), with varying degrees of success.

In this PR, I documented the actual behavior of these asymmetric matchers on master. As it turns out, the actual behavior of expect.objectContaining() is quite strange. Unfortunately, I don't know what the behavior should be, so I'm submitting this PR as-is rather than opening issues.

Documentation/behavior conflicts and edge cases:

• expect.objectContaining(), expect.not.objectContaining() are not recursive
• expect.objectContaining() can match primitive values
  • expect.objectContaining() boxes truthy primitives and doesn't box falsy primitives
• expect.arrayContaining([]) can match non-arrays (and in fact matches anything)
• expect.not.arrayContaining([]) matches nothing

I recommend not merging this PR and instead deciding what expect.objectContaining() should actually do. I'd be happy to update this to reflect the intended behavior, or someone else could submit a new PR.

This PR would close #11126 and close #10462.

Test plan

Several tests were added to cover expect.objectContaining() and expect.not.objectContaining()'s behavior with primitive received values.

[codecov-io]

Codecov Report

Merging #11157 (da3ad5c) into master (1d8f955) will decrease coverage by 0.01%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master   #11157      +/-   ##
==========================================
- Coverage   64.20%   64.19%   -0.02%     
==========================================
  Files         307      307              
  Lines       13371    13371              
  Branches     3261     3261              
==========================================
- Hits         8585     8583       -2     
- Misses       4082     4083       +1     
- Partials      704      705       +1     

Impacted Files	Coverage Δ
packages/expect/src/utils.ts	94.83% <0.00%> (-1.30%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1d8f955...da3ad5c. Read the comment docs.

[SimenB]

Hey @ninevra! I'd love to land this - any particular reason it's a draft? 🙂

EDIT:

I recommend not merging this PR and instead deciding what expect.objectContaining() should actually do. I'd be happy to update this to reflect the intended behavior, or someone else could submit a new PR.

Oh 😅 Let me give it a think, and add it to the milestone so we don't forget

[SimenB]

I don't want this to hold up the release, so swapping milestone. I'll probably have time to deal with this before next major (which will be this summer after node 17 is EOL)