vitest-unsettled

Custom Vitest matcher for checking if a Promise is settled (either resolved or rejected).

If you expect a promise to be settled, you probably assert on its value: expect(p).resolves.toBe(value). But what if you want to assert that a promise is not settled? You can't do that with the built-in matchers.

I've needed this a few times, so I made a custom matcher. Here's how it works.

let resolve = null;
const p = new Promise((r) => {
  resolve = r;
});
expect(p).toBeUnsettled(); // passes
resolve(12);
expect(p).not.toBeUnsettled(); // passes

Installation

# with npm
npm install --save-dev vitest-unsettled
# yarn
yarn add --dev vitest-unsettled
# pnpm
pnpm add -D vitest-unsettled

Setup

Import vitest-unsettled/extend-expect module

The simplest way to use this library is to import vitest-unsettled/extend-expect from your test setup file.

// vitest-setup.js
import "vitest-unsettled/extend-expect";

Extend in test setup file

You can also import the matcher from vitest-unsettled and pass them to Vitest's expect.extend method yourself:

// vitest-setup.js
import { toBeUnsettled } from "vitest-unsettled";
import { extend } from "vitest";
expect.extend({ toBeUnsettled });

With TypeScript

If you imported the vitest-unsettled/extend-expect module, you don't need to do anything else. Make sure your setup file is included in your tsconfig.json.

If you're extending the matchers yourself, you may need to add a type declaration to your test setup file:

import type { UnsettledMatcher } from "vitest-unsettled";
declare module "vitest" {
  export interface Assertion extends UnsettledMatcher {}
  export interface AsymmetricMatchersContaining extends UnsettledMatcher {}
}

Further reading:

• Extending matchers in Vitest
• Module augmentation in TypeScript

Acknowledgements

I leaned heavily on the chaance/vitest-axe project to see how to structure this project and README.