jest-extended

jest-extended adds over 70 additional matchers to Jest, covering common assertions for types, ranges, dates, objects, arrays, mocks, and promises that aren’t included in Jest’s core matcher set. Instead of hand-rolling assertions like checking whether a value falls within a numeric range or whether an object contains a specific set of keys, jest-extended provides expressive, well-tested matchers such as toBeWithin, toContainAllKeys, and toHaveBeenCalledBefore.

The library is maintained by the Jest community, ships full TypeScript typings, and is designed to be added to a project’s Jest setup with a single import, extending the global expect object without any per-test boilerplate.

What You Get

• 70+ custom matchers - A single import registers matchers for types, ranges, dates, collections, mocks, and promises that Jest doesn’t ship by default.
• Full TypeScript typings - Matchers are typed out of the box via the bundled types/index.d.ts, giving autocomplete and compile-time checking on expect(...) calls.
• Selective or all-in-one setup - Import specific matchers from jest-extended or register the entire set at once via jest-extended/all in your Jest setup file.
• Actively maintained matcher set - Regular releases (latest 7.0.0) keep pace with new Jest versions and community-requested matchers.

Common Use Cases

• Asserting numeric ranges - Using toBeWithin, toBeInRange, or toBePositive instead of manual comparison expressions.
• Validating object shape - Using toContainAllKeys, toContainEntry, or toBeEmptyObject to assert on object structure without verbose loops.
• Testing mock call order - Using toHaveBeenCalledBefore/toHaveBeenCalledAfter to assert the relative ordering of mock function invocations.
• Date and type assertions - Using toBeDateString, toBeValidDate, or toBeArray to reduce type-checking boilerplate in tests.

Under The Hood

Architecture jest-extended is a flat, modular library where each matcher lives in its own file under src/matchers/ (77 files), individually exported and re-exported through src/matchers/index.ts and then src/index.ts. A separate entry point, src/all/index.ts, imports every matcher module as a namespace and calls the global expect.extend(matchers) once, coupling the library to Jest’s global expect only when that specific submodule is imported. This one-file-per-matcher structure means adding, removing, or changing a matcher never risks touching unrelated matchers, and the two-entry design (selective import vs jest-extended/all) lets consumers choose between a curated subset or blanket registration without altering how any individual matcher is implemented. There is no internal service layer, dependency injection, or shared mutable state — each matcher module depends only on a small src/utils module for print/formatting helpers.

Tech Stack The codebase is mostly TypeScript, built via tsc plus tsc-alias for path resolution into dist/, with a separate types/index.d.ts published for consumers. The project is tested with Jest and ts-jest, using jest-serializer-ansi-escapes for snapshot serialization and jest-watch-typeahead for watch-mode filtering, while ESLint with typescript-eslint, eslint-plugin-prettier, and eslint-plugin-jest enforce lint/format rules, wired through husky and lint-staged pre-commit hooks. Releases are managed via changesets, and the package targets modern Node runtimes, declaring jest and typescript as peer dependencies rather than bundling them — the only actual runtime dependency is jest-diff. A CI workflow runs the build and test suite, and a separate website/ directory hosts the published documentation site.

Code Quality Every matcher under src/matchers has a mirrored test file under test/matchers/, and the project’s own Jest config enforces a coverageThreshold of 100% for branches, functions, lines, and statements. Individual matcher implementations follow a consistent pattern: returning { pass, message } per the Jest custom-matcher contract, using this.utils for consistent failure-message formatting, and staying in typed TypeScript with only narrow @ts-expect-error escapes for untyped Jest internals. ESLint, Prettier, and pre-commit hooks enforce consistent style, and CI runs on every push. Naming is highly consistent across matcher families, which keeps the large matcher surface easy to navigate despite its size.

API Design jest-extended’s core design choice is to extend Jest’s native expect surface directly rather than provide a separate assertion API, so consumers write expect(x).toBeWithin(1, 10) exactly as they would any built-in Jest matcher, with no new mental model or wrapper object to learn. The two-tier setup — importing individual matchers for typed access, or importing jest-extended/all once in a Jest setup file to register everything globally — gives teams a low-friction default with an escape hatch for selective imports when bundle or type surface matters. Matcher names are grouped into clear families (toBe*, toContain*, toHaveBeenCalled*, toChange*), making the large matcher surface discoverable via autocomplete, and full TypeScript typings catch invalid matcher arguments at compile time rather than only at test-run time.