`toContainValue` and `toContainValues` do not handle arrays anymore since v5.0

[falkenhawk]

• package version: 5.0.1-6.0.0
• node version: 22.16.0
• npm (or yarn) version: 11.4.2

toContainValue and toContainValues have been crippled in v5 (and remain like that in v6) in a way that they do not handle arrays anymore.

I think it was done to clearly separate the purpose that toContain* matchers are expected to be used on objects, since there is toIncludeAllMembers matcher which works with arrays.

The point is, in my opinion, those matchers (and especially the toContainValue for checking whether a single value exists in an array) are more intuitive to use and is easier to read and remember. After all, arrays are objects, right? And array elements are its values. They can operate on arrays without any logic issue or type conflict.

Now they simply rejects with a fail, simply ignoring array values and refusing to run any checks, which really confused me - there is no mention in the release notes about this breaking change, or did I overlook it? I only learned from the code that there are now extra !Array.isArray checks in those matchers.

Note: toContainEntry and toContain*Entries still work fine with arrays (please keep them like that 🙏 )

Reproduction:

test('passes when object contains given value', () => {
  const o = [1, 2, 3];
  expect(o).toContainValue(2);
});

Fail
/toContainValue.test.js
● › passes when object contains given value
expect(received).toContainValue(expected)

Expected object to contain value:
  2
Received:
  [1, 2, 3]

  1 | test('passes when object contains given value', () => {
  2 | const o = [1, 2, 3];
> 3 | expect(o).toContainValue(2);
    |           ^
  4 | });
Test suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Time:        0.001s

test('passes when object contains given value', () => {
  const o = [1, 2, 3];
  expect(o).toContainValue(2);
});

test('passes when object contains all of the given values', () => {
  const o = [1, 2, 3];
  expect(o).toContainValues([3, 2]);
});

Fail
/toContainValues.test.js
● › passes when object contains all of the given values
expect(received).toContainValues(expected)

Expected object to contain all values:
  [3, 2]
Received:
  [1, 2, 3]

  1 | test('passes when object contains all of the given values', () => {
  2 | const o = [1, 2, 3];
> 3 | expect(o).toContainValues([3, 2]);
    |           ^
  4 | });
Test suites: 1 failed, 1 total
Tests:       1 failed, 1 total
Time:        0s

[aldex32]

Hi @mattphillips , is this an active repo still?

[aldex32]

or perhaps @keeganwitt ?

[keeganwitt]

Sorry for the slow reply.

This was mentioned in #773.
#773 (comment)

Let me know if I've missed something.

[keeganwitt]

To expand on my thinking behind the changes in 5.0,

1. The behavior of supporting arrays was never documented.
2. The behavior of supporting arrays never had any tests.
3. We have the toContain* toInclude* matchers, which are meant for arrays.

So when I was tightening the type checks we had, it made sense to go with the intent of the matcher, as documented and tested.

[oldium]

Yeah, but "toContainValues" is a perfect method name for arrays too. And it worked like that. That is the point.

Intuitive API is what makes the library great. If people used to use it like that and it is easy to implement it, why not implement it?