v2.0.0

Following the release of Jest 30, this package has removed the following aliases for consistency:

• toBeCalledWithContext
• nthCalledWithContext
• lastCalledWithContext

This matches the removal of toBeCalled, nthCalledWith and lastCalledWith in Jest 30. These were never included in Vitest either.

The package is also now built with tsdown instead of tsup.

tsdown's build broke the matcher extensions in Typescript, so v2.0.1 has been published using tsup to build.

What's Changed

Full Changelog: v1.8.1...v2.0.0

v1.5.0 - iterableOf and recordOf!

This minor release adds matchers for iterables and records (i.e. dictionary objects where all values are the same type).

toBeIterableOf,toBeStrictIterableOf,expect.iterableOf, expect.strictIterableOf

These matchers check that all the values in an iterable match a given value, using deep (and strict where applicable) equality.

For example, to check every value in an array is a number:

expect([1, 2, 3]).toBeIterableOf(expect.typeOf("number")); // or expect.any(Number)

toBeRecordOf, toBeStrictRecordOf, expect.recordOf, expect.strictRecordOf

These matchers check that all values in an object match a given value, using deep (and strict where applicable) equality.

For example, to check every value in an object is a number:

expect({ a: 1, b: 2, c: 3 }).toBeRecordOf(expect.typeOf("number")); // or expect.any(Number)

Optionally, you can pass two expected values, and the first will be used to check the key instead.

expect({ a: 1, b: 2, c: 3 }).toBeRecordOf(
  expect.oneOf(["a", "b", "c"]),
  expect.typeOf("number"),
);

Note that only enumerable string keys are checked, as the matcher iterates using Object.entries.

The naming of this matcher comes from Typescript's Record type.

v1.4.0 - Sequences and iterables!

This minor release adds new matchers for iterables. Namely:

toSatisfySequence and expect.sequence, which match against an iterable using predicates:

expect([1,2,3]).toSatisfySequence(
  (x) => x === 1,
  (x) => x === 2,
  (x) => x === 3,
)

expect({ value: [1,2,3] }).toEqual({
  value: expect.sequence(
    (x) => x === 1,
    (x) => x === 2,
    (x) => x === 3,
  ),
})

toEqualSequence, toStrictEqualSequence, expect.sequenceOf and expect.strictSequenceOf which compare each item of an iterable deeply:

expect([1,2,3]).toEqualSequence(1,2,3)

expect([1,2,3]).toStrictEqualSequence(1,2,3)

expect({ value: [1,2,3] }).toEqual({
  value: expect.sequenceOf(1,2,3)
})

expect({ value: [1,2,3] }).toEqual({
  value: expect.strictSequenceOf(1,2,3)
})

Notes

The examples are shown with arrays for ease of understanding, but any iterable will work:

function* countToThree() {
  yield 1;
  yield 2;
  yield 3;
}

expect(countToThree()).toEqualSequence(1, 2, 3)

There can be more received items than expected items/predicates, but there needs to be at least the same amount.

expect([1,2,3]).toEqualSequence(1,2) // fine
expect([1,2]).toEqualSequence(1,2,3) // not fine

v1.3.0 - expect.oneOf, expect.enum, and .toBeEnum

This minor release:

• adds expect.oneOf([1,2,3]) to asymmetrically match against a number of items - each is compared using deep equality.
• adds toBeEnum(Enum) and expect.enum(Enum) matchers to check a value is from a given enum
  • works with both Typescript native enums and "const object" style enums

What's Changed

• Add expect.oneOf([1, 2, 3]) by @EskiMojo14 in #7
• Add toBeEnum and expect.ofEnum/enum matchers by @EskiMojo14 in #8

Full Changelog: v1.2.0...v1.3.0

v1.2.0 - Vitest, plus some new matchers

This minor release adds Vitest support, and some new matchers.

Vitest

This release adds support for Vitest, by adding an explicit dependency on jest-matcher-utils for utilities provided by Jest but not Vitest.

See the README for the setup guide.

New matchers

expect.typeOf

This asymmetric matcher checks that a given value has a given typeof.

expect(getPost()).toEqual({ title: expect.typeOf("string") })

expect.arrayContainingOnly

This asymmetric matcher checks that a given array only contains values from an expected array.
Values can be duplicate or omitted, but all values present must match.

expect([1, 2]).toEqual(expect.arrayContainingOnly([1, 2, 3])) // passes
expect([1, 2, 3]).toEqual(expect.arrayContainingOnly([1, 2])) // fails

This is different to expect.arrayContaining, which checks that all expected values are present and allows for other values.

expect([1, 2]).toEqual(expect.arrayContaining([1,2,3])) // fails
expect([1, 2, 3]).toEqual(expect.arrayContaining([1, 2])) // passes

expect.objectContainingOnly

This asymmetric matcher checks that a given object only contains matching keys from an expected object.
Keys can be omitted, but keys present must match.

expect({ a: 1 }).toEqual(expect.objectContainingOnly({ a: 1, b: 2 })) // passes
expect({ a: 1, b: 2 }).toEqual(expect.objectContainingOnly({ a: 1 })) // fails

This is different to expect.objectContaining, which checks that all expected keys are present and allows for other keys.

expect({ a: 1 }).toEqual(expect.objectContaining({ a: 1, b: 2 })) // fails
expect({ a: 1, b: 2 }).toEqual(expect.objectContaining({ a: 1 })) // passes

What's Changed

• Add asymmetric expect.typeOf matcher by @EskiMojo14 in #4
• Add vitest support by @EskiMojo14 in #2
• Add arrayContainingOnly and objectContainingOnly by @EskiMojo14 in #5

Full Changelog: v1.1.1...v1.2.0

v1.1.0 (and v1.1.1) - @jest/globals support

This release adds a new entry point to support @jest/globals usage - you can now import from "mix-n-matchers/jest-globals" for all the matchers to be added.

If you're only using some matchers, your usage will be the same as previous - just import expect from "@jest/globals" and call expect.extend() as usual.

See README for a guide on Typescript setup.

NOTE: the jest-globals entry point is broken in v1.1.0 due to a bundling issue. Use v1.1.1, which fixes this.

What's Changed

• support @jest/globals by @EskiMojo14 in #1

Full Changelog: v1.0.1...v1.1.1

v1.0.1

Should have README a little closer! This patch release fixes a usage example in the README.

v1.0.0 - Initial release!

The library currently contains an asymmetric matcher for comparing by reference (via Object.is) and a number of symmetric matchers for checking mock function context (this).