mix-n-matchers

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>
      extends Pick<
        MixNMatchers<R>,
        | "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>
      extends Pick<MixNMatchers<R>, 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>
    extends Pick<
      MixNMatchers<R>,
      "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 = any>
    extends Pick<
      mixNMatchers.MixNMatchers<T>,
      "toBeCalledWithContext" | "lastCalledWithContext" | "nthCalledWithContext"
    > {}
  interface AsymmetricMatchersContaining
    extends Pick<mixNMatchers.AsymmetricMixNMatchers, "exactly"> {}
}

Matchers

Asymmetric Matchers

Name	Description	Example
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 }));

Symmetric Matchers

Name	Description	Example
toBeEnum	Assert a value is a member of the specified enum.	expect(getDirection()).toBeEnum(Direction);
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).