Implementing the negated matcher

Negating a matcher is a tricky business, mainly because negated matchers can have confusing meanings. For example, what does the following expectation mean?

expect(result).not.toBeUnprocessableEntity({
  error: 'An unknown ID was provided.'
});

Presumably, it should fail if the response is 422 and the response body matches the object provided. But should it also fail if the response is, say, a 500 or 200 response? If that was what was expected, wouldn’t it be enough to write this?

expect(result).not.toBeUnprocessableEntity();

I find that when writing matchers for domain-specific ideas, negated matchers are best avoided, or at least restricted in their use. However, to show how it’s done, let’s carry on with the matcher.

When we negate the matcher, the Vitest test runner will fail the test if the matcher returns a pass value of true. We have exactly one scenario where this occurs, as all our guard...