{"id":11141,"library":"jest-matcher-utils","title":"Jest Matcher Utilities","description":"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.","status":"active","version":"30.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/jestjs/jest","tags":["javascript","typescript"],"install":[{"cmd":"npm install jest-matcher-utils","lang":"bash","label":"npm"},{"cmd":"yarn add jest-matcher-utils","lang":"bash","label":"yarn"},{"cmd":"pnpm add jest-matcher-utils","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Prefer ESM imports for Jest v30+ projects. CommonJS `require` might work but is not the idiomatic approach for new TypeScript/ESM projects.","wrong":"const { matcherHint } = require('jest-matcher-utils')","symbol":"matcherHint","correct":"import { matcherHint } from 'jest-matcher-utils'"},{"note":"All core utilities are exported directly from the main package entry point. Avoid importing from internal paths.","wrong":"import { printReceived } from 'jest-matcher-utils/dist/printReceived'","symbol":"printReceived","correct":"import { printReceived } from 'jest-matcher-utils'"},{"note":"Color utility functions like `EXPECTED_COLOR` and `RECEIVED_COLOR` are direct named exports, providing consistent coloring for matcher outputs.","symbol":"EXPECTED_COLOR","correct":"import { EXPECTED_COLOR } from 'jest-matcher-utils'"}],"quickstart":{"code":"import { matcherHint, printReceived, printExpected, EXPECTED_COLOR, RECEIVED_COLOR } from 'jest-matcher-utils';\nimport { expect } from '@jest/globals'; // Or global 'expect' if configured\n\ndeclare global {\n  namespace jest {\n    interface Matchers<R> {\n      toBeDivisibleBy(divisor: number): R;\n    }\n  }\n}\n\nexpect.extend({\n  toBeDivisibleBy(received: number, argument: number) {\n    const pass = received % argument === 0;\n\n    const message = () =>\n      matcherHint('.toBeDivisibleBy', 'received', 'argument') +\n      '\\n\\n' +\n      `Expected: ${EXPECTED_COLOR(argument)}\\n` +\n      `Received: ${pass ? printReceived(received) : RECEIVED_COLOR(received)}`;\n\n    if (pass) {\n      return {\n        message,\n        pass: true,\n      };\n    } else {\n      return {\n        message,\n        pass: false,\n      };\n    }\n  },\n});\n\ndescribe('toBeDivisibleBy', () => {\n  test('should pass if the number is divisible', () => {\n    expect(4).toBeDivisibleBy(2);\n  });\n\n  test('should fail if the number is not divisible', () => {\n    expect(() => expect(5).toBeDivisibleBy(2)).toThrowErrorMatchingSnapshot();\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=30.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=30.0.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","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.","error":"TypeError: (0, _jestMatcherUtils.matcherHint) is not a function"},{"fix":"Review your custom matcher implementation. Ensure it returns an object like `{ pass: boolean; message: () => string; }`. For example: `return { pass: true, message: () => '...' };`","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.","error":"MatcherResult must be an object with a `pass` boolean property."}],"ecosystem":"npm"}