Miscellaneous custom Jest matchers
Install via npm
or yarn
:
npm install -D mix-n-matchers
yarn add -D mix-n-matchers
Create a setup script with the following:
// add all matchers
import * as mixNMatchers from "mix-n-matchers";
expect.extend(mixNMatchers);
// or just add specific matchers
import {
toBeCalledWithContext,
lastCalledWithContext,
nthCalledWithContext,
exactly,
} from "mix-n-matchers";
expect.extend({
toBeCalledWithContext,
lastCalledWithContext,
nthCalledWithContext,
exactly,
});
Add your setup script to your Jest setupFilesAfterEnv
configuration. For reference
"jest": {
"setupFilesAfterEnv": ["./testSetup.js"]
}
To automatically extend expect
with all matchers, you can use
"jest": {
"setupFilesAfterEnv": ["mix-n-matchers/all"]
}
If you're using @jest/globals
instead of injecting globals, you should use the jest-globals
entry point instead of all
.
"jest": {
"setupFilesAfterEnv": ["mix-n-matchers/jest-globals"]
}
If you're using Vitest, you should instead use mix-n-matchers/vitest
:
import { defineConfig } from "vitest/config";
export default defineConfig({
test: {
setupFiles: ["mix-n-matchers/vitest"],
include: ["src/**/*.vi.test.ts"],
},
});
If your editor does not recognise the custom mix-n-matchers
matchers, add a global.d.ts
file to your project with:
// global.d.ts
import "mix-n-matchers/all";
If you want finer control of which matchers are included (i.e. you're only extending with some), you can set this up yourself:
// global.d.ts
import type { MixNMatchers, AsymmetricMixNMatchers } from "mix-n-matchers";
declare global {
namespace jest {
export interface Matchers<R, T>
extends Pick<
MixNMatchers<R, T>,
| "toBeCalledWithContext"
| "lastCalledWithContext"
| "nthCalledWithContext"
> {}
export interface Expect extends Pick<AsymmetricMixNMatchers, "exactly"> {}
export interface InverseAsymmetricMatchers
extends Pick<AsymmetricMixNMatchers, "exactly"> {}
}
}
One method of ensuring this is in line with your actual setup file would be by exporting objects:
// testSetup.js
import {
toBeCalledWithContext,
lastCalledWithContext,
nthCalledWithContext,
exactly,
} from "mix-n-matchers";
export const mixNMatchers = {
toBeCalledWithContext,
lastCalledWithContext,
nthCalledWithContext,
};
expect.extend(mixNMatchers);
export const asymmMixNMatchers = { exactly };
expect.extend(asymmMixNMatchers);
// global.d.ts
import type { mixNMatchers, asymmMixNMatchers } from "../testSetup.js";
import type { MixNMatchers, AsymmetricMixNMatchers } from "mix-n-matchers";
declare global {
namespace jest {
export interface Matchers<R, T>
extends Pick<MixNMatchers<R, T>, keyof typeof mixNMatchers> {}
export interface Expect
extends Pick<AsymmetricMixNMatchers, keyof typeof asymmMixNMatchers> {}
export interface InverseAsymmetricMatchers
extends Pick<AsymmetricMixNMatchers, keyof typeof asymmMixNMatchers> {}
}
}
If you disable injectGlobals
for Jest and instead import from '@jest/globals'
, the setup will look slightly different.
If you just want all of the matchers, your global.d.ts
file should have:
// global.d.ts
import "mix-n-matchers/jest-globals";
If you want finer control over which matchers are added, you should follow the below:
// global.d.ts
import type { MixNMatchers, AsymmetricMixNMatchers } from "mix-n-matchers";
declare module "@jest/extend" {
export interface Matchers<R, T>
extends Pick<
MixNMatchers<R, T>,
"toBeCalledWithContext" | "lastCalledWithContext" | "nthCalledWithContext"
> {}
export interface AsymmetricMatchers
extends Pick<AsymmetricMixNMatchers, "exactly"> {}
}
If you're using Vitest, you should use mix-n-matchers/vitest
instead of the 'all' entry point:
// global.d.ts
import "mix-n-matchers/vitest";
If you want finer control over which matchers are added, you should follow the below:
// global.d.ts
import { expect } from "vitest";
import type { MixNMatchers, AsymmetricMixNMatchers } from "mix-n-matchers";
declare module "vitest" {
interface Assertion<T>
extends Pick<
mixNMatchers.MixNMatchers<void, T>,
"toBeCalledWithContext" | "lastCalledWithContext" | "nthCalledWithContext"
> {}
interface AsymmetricMatchersContaining
extends Pick<mixNMatchers.AsymmetricMixNMatchers, "exactly"> {}
}
Name | Description | Example |
---|---|---|
|
Uses |
expect(mock).toBeCalledWith(expect.exactly(reference)); |
|
Checks equality using |
expect(mock).toBeCalledWith(expect.typeOf("string")); |
|
Checks that the value matches one of the specified values, using deep equality. |
expect(mock).toBeCalledWith(expect.oneOf([1, 2, 3])); |
|
Checks that the value is a member of the specified enum. Exported as |
expect(mock).toBeCalledWith(expect.ofEnum(MyEnum));
expect(mock).toBeCalledWith(expect.enum(MyEnum)); |
|
Checks that value is an array only containing the specified values. Values can be repeated (or omitted), but all elements present should be present in the expected array. Put another way, it checks that the received array is a subset of (or equal to) the expected array. This is in contrast to |
// will pass
expect({ array: [1, 2] }).toEqual({
array: expect.arrayContainingOnly([1, 2, 3]),
});
expect({ array: [1, 2] }).toEqual({
array: expect.arrayContainingOnly([1, 2]),
});
expect({ array: [1, 1] }).toEqual({
array: expect.arrayContainingOnly([1, 2, 2]),
});
// will fail
expect({ array: [1, 2, 3] }).toEqual({
array: expect.arrayContainingOnly([1, 2]),
}); |
|
Checks that value is an object only containing the specified keys. Keys can be omitted, but all keys present should match the expected object. Put another way, it checks that the received object is a subset of (or equal to) the expected object. This is in contrast to |
// will pass
expect({ a: 1 }).toEqual(expect.objectContainingOnly({ a: 1, b: 2 }));
expect({ a: 1, b: 2 }).toEqual(expect.objectContainingOnly({ a: 1, b: 2 }));
// will fail
expect({ a: 1, b: 2 }).toEqual(expect.objectContainingOnly({ a: 1 })); |
|
Matches an iterable that satisfies the specified sequence of predicates. |
expect({
array: [1, 2, 3],
}).toEqual({
array: expect.sequence(
(x) => x === 1,
(x) => x === 2,
(x) => x === 3,
),
}); |
|
Matches an iterable that satisfies the specified sequence of values, using deep equality. |
expect({
array: [1, 2, 3],
}).toEqual({
array: expect.sequenceOf(1, 2, 3),
}); |
|
Matches an iterable that satisfies the specified sequence of values, using strict deep equality. |
expect({
array: [1, 2, 3],
}).toEqual({
array: expect.strictSequenceOf(1, 2, 3),
}); |
|
Matches an iterable where every value matches the expected value, using deep equality. |
expect({
array: [1, 2, 3],
}).toEqual({
array: expect.iterableOf(expect.any(Number)),
}); |
|
Matches an iterable where every value matches the expected value, using strict deep equality. |
expect({
array: [1, 2, 3],
}).toEqual({
array: expect.strictIterableOf(expect.any(Number)),
}); |
|
Matches an object where every value matches the expected value, using deep equality. Optionally, you can pass two arguments and the first will be matched against keys. Note: keys and values are retrieved using |
expect({
object: { a: 1, b: 2 },
}).toEqual({
object: expect.recordOf(expect.any(Number)),
});
expect({
object: { a: 1, b: 2 },
}).toEqual({
object: expect.recordOf(expect.any(String), expect.any(Number)),
}); |
|
Matches an object where every value matches the expected value, using strict deep equality. Optionally, you can pass two arguments and the first will be matched against keys. Note: keys and values are retrieved using |
expect({
object: { a: 1, b: 2 },
}).toEqual({
object: expect.strictRecordOf(expect.any(Number)),
});
expect({
object: { a: 1, b: 2 },
}).toEqual({
object: expect.strictRecordOf(expect.any(String), expect.any(Number)),
}); |
Name | Description | Example |
---|---|---|
|
Assert a value is a member of the specified enum. |
expect(getDirection()).toBeEnum(Direction); |
|
Assert a value is an iterable that satisfies the specified sequence of predicates. |
expect([1, 2, 3]).toSatisfySequence(
(x) => x === 1,
(x) => x === 2,
(x) => x === 3,
); |
|
Assert a value is an iterable that satisfies the specified sequence of values, using deep equality. |
expect([1, 2, 3]).toEqualSequence(1, 2, 3); |
|
Assert a value is an iterable that satisfies the specified sequence of values, using strict deep equality. |
expect([1, 2, 3]).toStrictEqualSequence(1, 2, 3); |
|
Assert a value is an iterable where every value matches the expected value, using deep equality. |
expect([1, 2, 3]).toBeIterableOf(expect.any(Number)); |
|
Assert a value is an iterable where every value matches the expected value, using strict deep equality. |
expect([1, 2, 3]).toBeStrictIterableOf(expect.any(Number)); |
|
Assert a value is an object where every value matches the expected value, using deep equality. Optionally, you can pass two arguments and the first will be matched against keys. Note: keys and values are retrieved using |
expect({ a: 1, b: 2 }).toBeRecordOf(expect.any(Number));
expect({ a: 1, b: 2 }).toBeRecordOf(expect.any(String), expect.any(Number)); |
|
Assert a value is an object where every value matches the expected value, using strict deep equality. Optionally, you can pass two arguments and the first will be matched against keys. Note: keys and values are retrieved using |
expect({ a: 1, b: 2 }).toBeStrictRecordOf(expect.any(Number));
expect({ a: 1, b: 2 }).toBeStrictRecordOf(
expect.any(String),
expect.any(Number),
); |
|
Assert a function has been called with a specific context ( |
expect(mock).toBeCalledWithContext(expectedContext);
expect(mock).toHaveBeenCalledWithContext(expectedContext); |
|
Assert the last call of a function was with a specific context ( |
expect(mock).lastCalledWithContext(expectedContext);
expect(mock).toHaveBeenLastCalledWithContext(expectedContext); |
|
Assert the Nth call of a function was with a specific context ( |
expect(mock).nthCalledWithContext(1, expectedContext);
expect(mock).toHaveBeenNthCalledWithContext(1, expectedContext); |
As enum
is a reserved word in Javascript, it is not possible to export a matcher with this name. However, you can alias it in your setup file:
import { ofEnum } from "mix-n-matchers";
expect.extend({ enum: ofEnum });
To add this to your global.d.ts
:
// global.d.ts
import type { AsymmetricMixNMatchers } from "mix-n-matchers";
declare global {
namespace jest {
export interface Expect {
enum: AsymmetricMixNMatchers["ofEnum"];
}
interface InverseAsymmetricMatchers {
enum: AsymmetricMixNMatchers["ofEnum"];
}
}
}
This approach can be adapted for Jest globals and Vitest as well.
After this setup, you should be able to use expect.enum
as a matcher.
expect(mock).toBeCalledWith(expect.enum(MyEnum));
This is automatically done for you with the auto-setup files (mix-n-matchers/all
, mix-n-matchers/jest-globals
, mix-n-matchers/vitest
).
When expect.extend
is called, each matcher is added as both an asymmetric and symmetric matcher.
expect.extend({
foo(received) {
const pass = received === "foo";
return {
pass,
message: pass ? () => "Expected 'foo'" : () => "Expected not 'foo'",
};
},
});
expect(value).foo(); // symmetric
expect(value).toEqual(expect.foo()); // asymmetric
However, conventionally there is a difference in how these matchers are named. For example, expect().toBeAnArray
vs expect.array
.
mix-n-matchers
intentionally only exposes types for matchers as either asymmetric or symmetric, and not both. Sometimes a matcher is available as both, but with different names. For example, expect().toBeEnum
and expect.ofEnum
.
This helps to avoid confusion and makes it clear which matchers are designed to be asymmetric and which are symmetric.
If there's any existing matchers that are only available as asymmetric matchers and you'd like to use them as symmetric matchers (or vice versa), please open an issue or a pull request!
You can of course choose to expose these types yourself to enable both symmetric and asymmetric usage of a matcher.
declare module "mix-n-matchers" {
interface MixNMatchers<R, T> extends Pick<AsymmetricMixNMatchers, "typeOf"> {}
interface AsymmetricMixNMatchers
extends Pick<MixNMatchers, "toBeCalledWithContext"> {}
}
// now allowed
expect(value).typeOf("string");
expect(value).toEqual({ fn: expect.toBeCalledWithContext(context) });