Skip to content
Vitest 3
Main Navigation Guide & APIConfigBrowser ModeAdvanced API
3.2.0
2.1.9
1.6.1
0.34.6

English

简体中文
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

English

简体中文
繁體中文
Español
Français
Русский
Português – Brasil
Deutsch
日本語
한국어
Italiano
Polski
Türkçe
čeština
magyar

Appearance

Sidebar Navigation

Introduction

Why Vitest

Getting Started

Features

Config Reference

API

Test API Reference

Mock Functions

Vi Utility

Expect

ExpectTypeOf

Assert

AssertType

Guides

CLI

Test Filtering

Test Projects

Reporters

Coverage

Snapshot

Mocking

Parallelism

Testing Types

Vitest UI

In-Source Testing

Test Context

Test Annotations

Environment

Extending Matchers

IDE Integration

Debugging

Common Errors

Migration Guide

Migrating to Vitest 3.0

Migrating from Jest

Performance

Profiling Test Performance

Improving Performance

Browser Mode

Node API Reference

Comparisons

On this page

Extending Matchers ​

Since Vitest is compatible with both Chai and Jest, you can use either the chai.use API or expect.extend, whichever you prefer.

This guide will explore extending matchers with expect.extend. If you are interested in Chai's API, check their guide.

To extend default matchers, call expect.extend with an object containing your matchers.

ts
expect.extend({
  toBeFoo(received, expected) {
    const { isNot } = this;
    return {
      // do not alter your "pass" based on isNot. Vitest does it for you
      pass: received === 'foo',
      message: () => `${received} is${isNot ? ' not' : ''} foo`,
    };
  },
});

If you are using TypeScript, you can extend default Assertion interface in an ambient declaration file (e.g: vitest.d.ts) with the code below:

ts
import 'vitest';

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R;
}

declare module 'vitest' {
  interface Matchers<T = any> extends CustomMatchers<T> {}
}
ts
import 'vitest';

interface CustomMatchers<R = unknown> {
  toBeFoo: () => R;
}

declare module 'vitest' {
  interface Assertion<T = any> extends CustomMatchers<T> {}
  interface AsymmetricMatchersContaining extends CustomMatchers {}
}

TIP

Since Vitest 3.2, you can extend the Matchers interface to have type-safe assertions in expect.extend, expect().*, and expect.* methods at the same time. Previously, you had to define separate interfaces for each of them.

WARNING

Don't forget to include the ambient declaration file in your tsconfig.json.

The return value of a matcher should be compatible with the following interface:

ts
interface ExpectationResult {
  pass: boolean;
  message: () => string;
  // If you pass these, they will automatically appear inside a diff when
  // the matcher does not pass, so you don't need to print the diff yourself
  actual?: unknown;
  expected?: unknown;
}

WARNING

If you create an asynchronous matcher, don't forget to await the result (await expect('foo').toBeFoo()) in the test itself::

ts
expect.extend({
  async toBeAsyncAssertion() {
    // ...
  },
});

await expect().toBeAsyncAssertion();

The first argument inside a matcher's function is the received value (the one inside expect(received)). The rest are arguments passed directly to the matcher.

Matcher function has access to this context with the following properties:

isNot ​

Returns true, if matcher was called on not (expect(received).not.toBeFoo()).

promise ​

If matcher was called on resolved/rejected, this value will contain the name of modifier. Otherwise, it will be an empty string.

equals ​

This is a utility function that allows you to compare two values. It will return true if values are equal, false otherwise. This function is used internally for almost every matcher. It supports objects with asymmetric matchers by default.

utils ​

This contains a set of utility functions that you can use to display messages.

this context also contains information about the current test. You can also get it by calling expect.getState(). The most useful properties are:

currentTestName ​

Full name of the current test (including describe block).

testPath ​

Path to the current test.

Pager
Previous pageEnvironment
Next pageIDE Integration

Released under the MIT License.

Copyright (c) 2021-Present Vitest Team

https://vitest.dev/guide/extending-matchers

Released under the MIT License.

Copyright (c) 2021-Present Vitest Team