How do you write custom Jest matchers?

A custom matcher is useful when the same multi-step assertion appears across many tests. It centralises the comparison and, more importantly, the failure message. A good matcher explains what was expected in the domain's language.

expect.extend({
  toBeWithinRange(received: number, floor: number, ceiling: number) {
    const pass = received >= floor && received <= ceiling;

    return {
      pass,
      message: () =>
        "expected " + received + " to be within " + floor + " and " + ceiling,
    };
  },
});

test("stays in range", () => {
  expect(7).toBeWithinRange(1, 10);
});

Writing a good matcher

• Return an object with pass and a message function
• Use this.isNot to give a different message when negated
• Include this.utils.printExpected and printReceived for readable output
• Put registration in setupFilesAfterEnv so every test sees it
• Add a TypeScript declaration so the matcher is typed

Keep matchers generic. A matcher named toBeValidInvoice that checks ten unrelated rules is hard to diagnose when it fails. Prefer several small matchers with clear names, and let the test name describe the scenario.