Jest Matcher Utilities

Common errors

• TypeError: (0, _jestMatcherUtils.matcherHint) is not a function

  cause This typically occurs when mixing CommonJS `require()` syntax with ESM-first packages, or when incorrect destructuring is applied in a CommonJS context to an ESM export. It can also happen if `jest-matcher-utils` is loaded in an unexpected way.
  fix Ensure you are using `import { matcherHint } from 'jest-matcher-utils';` for ESM environments (e.g., in `package.json` with `"type": "module"` or when using bundlers). If strictly using CommonJS, verify the module's compatibility or adjust import syntax if it's a dual-package.

• MatcherResult must be an object with a `pass` boolean property.

  cause Your custom matcher function is not returning an object with a `pass` property (which must be a boolean) and typically a `message` property (which must be a function). This is a fundamental requirement for all Jest custom matchers.
  fix Review your custom matcher implementation. Ensure it returns an object like `{ pass: boolean; message: () => string; }`. For example: `return { pass: true, message: () => '...' };`

Warnings

• breaking Jest 30 introduced substantial changes across the entire Jest ecosystem. While `jest-matcher-utils` specifically might not have had direct breaking API changes, upgrading Jest to v30.0.0 or later requires reviewing the general Jest migration guide, which may indirectly impact custom matchers or test setups.
  Fix: Consult the official Jest 30 migration guide for your project. Run `npm install jest@^30.0.0` and address any reported issues or warnings.
• gotcha In Jest v30.0.2, the `deepCyclicCopyObject` utility (used internally and potentially in advanced custom matchers) was made safer by setting descriptors to a null-prototype object. If you had custom logic relying on specific behaviors of deep copying or encountered issues with deeply nested objects in earlier 30.x versions, this fix might subtly change behavior or resolve previous edge cases.
  Fix: No direct fix needed, but be aware that object cloning behavior for complex structures might be more robust in 30.0.2 and later. If you were working around previous `deepCyclicCopyObject` limitations, those workarounds might now be unnecessary or cause issues.

Install

• npm install jest-matcher-utils npm
• yarn add jest-matcher-utils yarn
• pnpm add jest-matcher-utils pnpm

Imports

• matcherHint
  wrong:

  const { matcherHint } = require('jest-matcher-utils')

  correct:

  import { matcherHint } from 'jest-matcher-utils'

  Prefer ESM imports for Jest v30+ projects. CommonJS `require` might work but is not the idiomatic approach for new TypeScript/ESM projects.
• printReceived
  wrong:

  import { printReceived } from 'jest-matcher-utils/dist/printReceived'

  correct:

  import { printReceived } from 'jest-matcher-utils'

  All core utilities are exported directly from the main package entry point. Avoid importing from internal paths.
• EXPECTED_COLOR

  import { EXPECTED_COLOR } from 'jest-matcher-utils'

  Color utility functions like `EXPECTED_COLOR` and `RECEIVED_COLOR` are direct named exports, providing consistent coloring for matcher outputs.

Quickstart

This quickstart demonstrates how to create a custom Jest matcher using `jest-matcher-utils` to provide consistent output formatting for success and failure messages, including color coding.

import { matcherHint, printReceived, printExpected, EXPECTED_COLOR, RECEIVED_COLOR } from 'jest-matcher-utils';
import { expect } from '@jest/globals'; // Or global 'expect' if configured

declare global {
  namespace jest {
    interface Matchers<R> {
      toBeDivisibleBy(divisor: number): R;
    }
  }
}

expect.extend({
  toBeDivisibleBy(received: number, argument: number) {
    const pass = received % argument === 0;

    const message = () =>
      matcherHint('.toBeDivisibleBy', 'received', 'argument') +
      '\n\n' +
      `Expected: ${EXPECTED_COLOR(argument)}\n` +
      `Received: ${pass ? printReceived(received) : RECEIVED_COLOR(received)}`;

    if (pass) {
      return {
        message,
        pass: true,
      };
    } else {
      return {
        message,
        pass: false,
      };
    }
  },
});

describe('toBeDivisibleBy', () => {
  test('should pass if the number is divisible', () => {
    expect(4).toBeDivisibleBy(2);
  });

  test('should fail if the number is not divisible', () => {
    expect(() => expect(5).toBeDivisibleBy(2)).toThrowErrorMatchingSnapshot();
  });
});