jest-extended 7.x

Complete instructions

Verified against jest-extended@7.0.0 on 2026-09-08. 3 of 3 examples executed.

jest-extended v7

What this package is

jest-extended v7 provides additional Jest matchers. Its package entry point re-exports the matchers from ./matchers.

The documented integration is with Jest's expect.extend:

import * as matchers from 'jest-extended';
expect.extend(matchers);

Selective registration is also supported:

import { toBeArray, toBeSealed } from 'jest-extended';
expect.extend({ toBeArray, toBeSealed });

The package does not provide a standalone assertion runner. describe, it, and expect are not supplied by the package in a directly executed script. Vitest can use the same matchers through Vitest's compatible expect.extend API and a setup file.

Exported matcher surface

The v7 entry point exports:

• fail, pass
• Type/value matchers: toBeArray, toBeArrayOfSize, toBeBigInt, toBeBoolean, toBeDate, toBeDateString, toBeEmpty, toBeEmptyObject, toBeEven, toBeExtensible, toBeFalse, toBeFinite, toBeFrozen, toBeFunction, toBeHexadecimal, toBeInteger, toBeNaN, toBeNegative, toBeNil, toBeNumber, toBeObject, toBeOdd, toBeOneOf, toBePositive, toBeSealed, toBeString, toBeSymbol, toBeTrue, toBeValidDate
• Range/date matchers: toBeAfter, toBeAfterOrEqualTo, toBeBefore, toBeBeforeOrEqualTo, toBeBetween, toBeWithin, toBeInRange
• Collection/content matchers: toContainAllEntries, toContainAllKeys, toContainAllValues, toContainAnyEntries, toContainAnyKeys, toContainAnyValues, toContainEntries, toContainEntry, toContainKey, toContainKeys, toContainValue, toContainValues, toInclude, toIncludeAllMembers, toIncludeAllPartialMembers, toIncludeSamePartialMembers, toIncludeAnyMembers, toIncludeMultiple, toIncludeRepeated, toIncludeSameMembers, toPartiallyContain
• String/predicate matchers: toEndWith, toEqualCaseInsensitive, toEqualIgnoringWhitespace, toSatisfy, toSatisfyAll, toSatisfyAny, toStartWith
• Change/spy/promise/error matchers: toChange, toChangeBy, toChangeTo, toHaveBeenCalledAfter, toHaveBeenCalledBefore, toHaveBeenCalledOnce, toHaveBeenCalledExactlyOnceWith, toReject, toResolve, toThrowWithMessage

Directly exercising matchers without a runner

The matcher functions themselves can be imported and called with a matcher context. A direct script must provide the this.utils methods the matcher uses; this tests the matcher result, not a Jest assertion environment.

toBeArray uses Array.isArray, so arrays pass and other values fail.

import assert from 'node:assert/strict';
import { toBeArray } from 'jest-extended';

const context = {
  utils: {
    matcherHint: (hint: string) => hint,
    printReceived: (value: unknown) => String(value),
  },
};

const isArray = (toBeArray as any).call(context, [1, 2]);
const isNotArray = (toBeArray as any).call(context, 'not an array');

assert.equal(isArray.pass, true);
assert.equal(isNotArray.pass, false);

toInclude only passes when the received value is a string containing the expected string. It does not use array membership semantics.

import assert from 'node:assert/strict';
import { toInclude } from 'jest-extended';

const context = {
  utils: {
    matcherHint: (hint: string) => hint,
    printReceived: (value: unknown) => String(value),
    printExpected: (value: unknown) => String(value),
  },
};

const included = (toInclude as any).call(context, 'hello world', 'world');
const absent = (toInclude as any).call(context, 'hello world', 'mars');
const wrongType = (toInclude as any).call(context, ['hello', 'world'], 'world');

assert.equal(included.pass, true);
assert.equal(absent.pass, false);
assert.equal(wrongType.pass, false);

toBeWithin uses an inclusive start and exclusive end. It accepts numbers and bigints according to its type check. Keep the operand types compatible with JavaScript comparisons.

import assert from 'node:assert/strict';
import { toBeWithin } from 'jest-extended';

const context = {
  utils: {
    matcherHint: (hint: string) => hint,
    printReceived: (value: unknown) => String(value),
    printExpected: (value: unknown) => String(value),
  },
};

const atStart = (toBeWithin as any).call(context, 10, 10, 20);
const atEnd = (toBeWithin as any).call(context, 20, 10, 20);
const bigintValue = (toBeWithin as any).call(context, 15n, 10n, 20n);
const wrongType = (toBeWithin as any).call(context, '15', 10, 20);

assert.equal(atStart.pass, true);
assert.equal(atEnd.pass, false);
assert.equal(bigintValue.pass, true);
assert.equal(wrongType.pass, false);

Setup mistakes to avoid

• Do not call expect(...) in a plain script unless you supply a compatible expect host. The package supplies matchers, not the runner or assertion global.
• Do not assume importing the package automatically installs every matcher. Register all matchers with expect.extend(matchers), or register selected named exports.
• Do not treat jest-extended/all as a standalone implementation. Its v7 entry point forwards to the built dist/all output and is intended for Jest setup configuration such as setupFilesAfterEnv.
• Do not use the old toHaveBeenCalledOnceWith name. It was renamed in an earlier major to toHaveBeenCalledExactlyOnceWith.
• BigInt support and the toBeBigInt matcher were added in v6; code targeting older versions may show a shape that does not reflect v7.
• v7's documented Jest support is Jest 27.2.5 and newer. The package metadata declares Jest as an optional peer and TypeScript as a peer, with TypeScript >=5.0.0.
• v7 changed the supported Node engine range: it drops Node 18 and Node 23 and adds Node 24 and 25 support. Its published engine range is ^20.9.0 || ^22.11.0 || ^24.11.0 || >=25.0.0.

What this skill does not cover

The supplied research does not document the argument semantics or implementation behavior of most exported matchers beyond the three shown above. It also does not cover Jest configuration details beyond the setup-file pattern, matcher failure formatting in a real Jest run, TypeScript declaration usage, Vitest version compatibility, or the behavior of fail, pass, spies, promises, changes, dates, objects, collections, and predicate matchers. Those parts should be exercised through the compatible Jest/Vitest host or verified from their individual v7 implementations.