mix-n-matchers v1.5.0
mix-n-matchers
Miscellaneous custom Jest matchers
Installation
Install via npm
or yarn
:
npm install -D mix-n-matchers
yarn add -D mix-n-matchers
Setup
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"],
},
});
Typescript
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> {}
}
}
@jest/globals
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"> {}
}
Vitest
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"> {}
}
Matchers
Asymmetric Matchers
exactly
Uses Object.is
to ensure referential equality in situations where deep equality would typically be used.
expect(mock).toBeCalledWith(expect.exactly(reference));
typeOf
Checks equality using typeof
.
expect(mock).toBeCalledWith(expect.typeOf("string"));
oneOf
Checks that the value matches one of the specified values, using deep equality.
expect(mock).toBeCalledWith(expect.oneOf([1, 2, 3]));
ofEnum
/ enum
Checks that the value is a member of the specified enum.
Exported as ofEnum
and aliased as enum
in auto-setup files. (See Tips)
expect(mock).toBeCalledWith(expect.ofEnum(MyEnum));
expect(mock).toBeCalledWith(expect.enum(MyEnum));
arrayContainingOnly
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 arrayContaining
, which checks that the received array is a superset of (or equal to) the expected array.
// 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]),
});
objectContainingOnly
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 objectContaining
, which checks that the received object is a superset of (or equal to) the expected object.
// 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 }));
sequence
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,
),
});
sequenceOf
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),
});
strictSequenceOf
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),
});
iterableOf
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)),
});
strictIterableOf
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)),
});
recordOf
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 Object.entries
, so only string (non-symbol) enumerable keys are checked.
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)),
});
strictRecordOf
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 Object.entries
, so only string (non-symbol) enumerable keys are checked.
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)),
});
Symmetric Matchers
toBeEnum
Assert a value is a member of the specified enum.
expect(getDirection()).toBeEnum(Direction);
toSatisfySequence
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,
);
toEqualSequence
Assert a value is an iterable that satisfies the specified sequence of values, using deep equality.
expect([1, 2, 3]).toEqualSequence(1, 2, 3);
toStrictEqualSequence
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);
toBeIterableOf
Assert a value is an iterable where every value matches the expected value, using deep equality.
expect([1, 2, 3]).toBeIterableOf(expect.any(Number));
tobeStrictIterableOf
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));
toBeRecordOf
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 Object.entries
, so only string (non-symbol) enumerable keys are checked.
expect({ a: 1, b: 2 }).toBeRecordOf(expect.any(Number));
expect({ a: 1, b: 2 }).toBeRecordOf(expect.any(String), expect.any(Number));
toBeStrictRecordOf
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 Object.entries
, so only string (non-symbol) enumerable keys are checked.
expect({ a: 1, b: 2 }).toBeStrictRecordOf(expect.any(Number));
expect({ a: 1, b: 2 }).toBeStrictRecordOf(
expect.any(String),
expect.any(Number),
);
toBeCalledWithContext
/toHaveBeenCalledWithContext
Assert a function has been called with a specific context (this
).
expect(mock).toBeCalledWithContext(expectedContext);
expect(mock).toHaveBeenCalledWithContext(expectedContext);
lastCalledWithContext
/toHaveBeenLastCalledWithContext
Assert the last call of a function was with a specific context (this
).
expect(mock).lastCalledWithContext(expectedContext);
expect(mock).toHaveBeenLastCalledWithContext(expectedContext);
nthCalledWithContext
/toHaveBeenNthCalledWithContext
Assert the Nth call of a function was with a specific context (this
).
expect(mock).nthCalledWithContext(1, expectedContext);
expect(mock).toHaveBeenNthCalledWithContext(1, expectedContext);
Tips
Aliasing expect.ofEnum
to expect.enum
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
).
Asymmetric Matchers vs Symmetric Matchers
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) });