[Docs]: .tocontainequalitem() explanation is ambiguous

[jauntyjocularjay]

Page(s)

https://github.com/jestjs/jest/blob/main/docs/ExpectAPI.md#tocontainequalitem

Description

I find this explanation is very ambiguous.

Use .toContainEqual when you want to check that an item with a specific structure and values is contained in an array. For testing the items in the array, this matcher recursively checks the equality of all fields, rather than checking for object identity.

describe('my beverage', () => {
  test('is delicious and not sour', () => {
    const myBeverage = {delicious: true, sour: false};
    expect(myBeverages()).toContainEqual(myBeverage);
  });
});

I have the following questions:
What does the myBeverages() return? An array, I think.
So does the expect argument HAVE TO BE an array? I think so.
Does myBeverage have to be an object literal? Could it be an array inside an array? Not sure.
Does myBeverage match to things which have more fields than the specified fields? Not sure.

function myBeverages() {
  return [
    {
        delicious: true,
        sour: false,
        salty: false
    },
    {
        delicious: true,
        sour: true,
        salty: true
    }
  ]
}

const const myBeverage = {
  delicious: true,
  sour: false
}

expect(myBeverages()).toContainEqual(myBeverage) // True? Possibly?

[jauntyjocularjay]

What does the myBeverages() return? An array, I think.

Still can't tell from context.

So does the expect argument HAVE TO BE an array? I think so

I tested it and Jest throws an error when the expect() argument is an object literal.

Console Output:

myBeverages does contain myBeverage

    expect(received).toContainEqual(expected) // deep equality

    Expected value:  {"delicious": true, "sour": false}
    Received object: {"0": {"delicious": true, "sour": false}, "1": {"delicious": true, "salty": true, "sour": true}}

    > 197 |                         ? expect(target).toContainEqual(subject)

Also this is somewhat misleading as we are using the term 'deep equality' when comparing objects when 'deep equality' compares objects in the location in memory, not by comparing their key: value pairs.

ex.

const obj1 = { pet: 'dog'}
const obj2 = { pet: 'dog'}
const obj3 = { pet: 'cat'}

console.log(obj1 === obj1) // true
console.log(obj1 === obj2) // false
console.log(obj1 === obj3) // false

Does myBeverage have to be an object literal? Could it be an array inside an array? Not sure.

Still not sure

Does myBeverage match to things which have more fields than the specified fields? Not sure

No, it does not. It has to be exactly the same key: value pairs.

[github-actions]

This issue is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 30 days.

[github-actions]

This issue was closed because it has been stalled for 30 days with no activity. Please open a new issue if the issue is still relevant, linking to this one.

[github-actions]

This issue was closed because it has been stalled for 30 days with no activity. Please open a new issue if the issue is still relevant, linking to this one.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.