Are literal values deliberately allowed as property matchers in toMatchSnapshot()?

The docs say here:

For these cases, Jest allows providing an asymmetric matcher for any property. These matchers are checked before the snapshot is written or tested, and then saved to the snapshot file instead of the received value:

and here:

The optional propertyMatchers argument allows you to specify asymmetric matchers which are verified instead of the exact values.

Both only refers to asymmetric matchers. But if I do this everything works:

expect({ p: 'hi' }).toMatchSnapshot({ p: 'hi' });

Even if I’m not using an asymmetric matcher, but using a literal value, the expectation passes and the snapshot is written correctly.

So the question is: Is the fact that the value of a property matcher works with a literal value instead of an asymmetric matcher planned, even if the docs doesn’t say anything about, or is it a coincidence and my code could be suddenly break and destroy all life as we know it?

I am asking this here because I think this is a design question or perhaps it shows that docs are incomplete. If this was not appropriate I apologize and understand if it gets closed.

Here a little context. Similar to #6455 (and maybe until #6528), it is not straightforward to put an asymmetric matcher on a nested property of an object or on an object inside and array. The workaround I’m using is something like this:

test('foo', () => {
    // The `anArray` property could be very large. Every object inside
    // has an `id` property with an autogenerated value.
    const obj = { anArray: [{ id: 'autogenerated', p: 1 }] };

    expect(obj).toMatchSnapshot({
        anArray: obj.anArray.map(a => ({
            ...a, // this "copies" every other property so will be written
                  // in the snapshot and compared the next time.
            id: expect.any(String),
        })),
    });
});

In that example the anArray property is using a literal value (the array returned from map) and the spreading of every property of every element in ...a. Nonetheless, and beyond this particular example, the question holds in general.

[rickhanlonii]

Is the fact that the value of a property matcher works with a literal value instead of an asymmetric matcher planned

Great question @InExtremaRes. The short answer is yes and we should update the docs.

For some background, the proposal was that only the property matchers would be checked, but the whole object would be merged. This would allow you to specify overrides for certain values in the object, as in:

const user = {
  id: '58e2a3fc05649b0f00497fed',
  name: 'Mike',
};

expect(user).toMatchSnapshot({ id: 'generated-id' });

exports[`something 1`] = `
Object {
  "id": "generated-id",
  "name": "Mike",
}
`;

During implementation we realized this was confusing/unexpected behavior and that if you want to override what’s in the snapshot you should use a matcher:

expect(user).toMatchSnapshot({ id: expect.any(String) });

exports[`something 1`] = `
Object {
  "id": Any<String>,
  "name": "Mike",
}
`;

When it came to what to do for non-matcher properties (if they weren’t going to override) it seemed to make sense to match them exactly, (also much easier to implement) so the docs should be updated to say:

values will be matched exactly if not provided as a matcher

By the way, using custom asymmetric matchers, the above example can be written as:

expect(user).toMatchSnapshot({ id: expect.objectId() });

exports[`something 1`] = `
Object {
  "id": Any<ObjectID>,
  "name": "Mike",
}
`;

Which is probably the best case in terms of both readability and asserting values.

[github-actions[bot]]

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.