Registry / testing / jest-matcher-utils

jest-matcher-utils

library30.3.0jsnpmunverified

jest-matcher-utils provides a collection of helper functions used internally by Jest and exposed for developers creating custom matchers. These utilities facilitate consistent formatting and error reporting within Jest's `expect` assertions. The package is part of the larger Jest monorepo, which is currently stable at version 30.3.0, with major releases occurring every few years (Jest 30 was released after three years, with a stated aim for more frequent future majors). It's actively maintained, with frequent patch and minor updates addressing bug fixes, performance improvements, and new features across the Jest ecosystem. Its primary differentiation lies in providing the exact formatting and utility logic that Jest itself uses, ensuring seamless integration and a consistent user experience when extending Jest's assertion capabilities. This includes functions for printing values, generating matcher hints, and handling object comparisons, crucial for building custom assertion logic that feels native to Jest.

testing

npm install jest-matcher-utils

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JEST-MATCHER-UTILS

jest-matcher-utils

testingjavascriptv30.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

matcherHint

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

✗ const { matcherHint } = require('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

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

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

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.

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(); }); });

Debug

Known issues

breakingJest 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.

affects: >=30.0.0

gotchaIn 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.

affects: >=30.0.2

Errors

Common errors & fixes

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

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.

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: () => '...' };`

Upgrade

Version history

30.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/jestjs/jest ↗

packagehttps://www.npmjs.com/package/jest-matcher-utils ↗

homepagehttps://jestjs.io/ ↗