til/javascript/define-a-custom-jest-matcher.md

Define A Custom Jest Matcher

Though Jest's built-in matchers will get you pretty far in most testing scenarios, you may find yourself in a testing situation better served by a custom matcher. Custom matchers can be defined using the expect.extend() function.

Here is an example of a matcher that can check equality of two objects based solely on their id property.

expect.extend({
  toHaveMatchingId(recieved, expected) {
    const pass = recieved.id === expected.id;

    if (pass) {
      return {
        pass: true,
        message: `Actual ${recieved.id} matches expected ${expected.id}`
      };
    } else {
      return {
        pass: false,
        message: `Actual ${recieved.id} does not match expected ${expected.id}`
      };
    }
  }
});

This defines the name of the matcher (toHaveMatchingId), contains some logic to figure out whether received and expected pass the matcher, and then two return conditions (pass: true and pass: false) with accompanying messages.

It can then be used like any other Jest matcher:

test("compare objects", () => {
  expect({ id: "001" }).toHaveMatchingId({ id: "001" });
  expect({ id: "001" }).toHaveMatchingId({ id: "002" });
});

Check out a live example.