Skip to main content

Vitest Expect Matchers

Vitest provides a powerful expect function that allows you to make assertions in your tests using a variety of matchers. This guide covers commonly used matchers with examples to help you write clear and effective tests.

Equality Matchers​

toBe​

Checks strict equality between two values.

expect(1 + 1).toBe(2);

toEqual​

Checks deep equality between objects or arrays.

expect([1, 2, 3]).toEqual([1, 2, 3]);
expect({ a: 1 }).toEqual({ a: 1 });

not.toBe​

Ensures values are not strictly equal.

expect(1 + 1).not.toBe(3);

not.toEqual​

Ensures deep inequality between objects or arrays.

expect([1, 2, 3]).not.toEqual([3, 2, 1]);

Null and Undefined Matchers​

toBeNull​

Checks if a value is null.

expect(null).toBeNull();

toBeDefined​

Verifies if a value is defined.

expect(undefined).not.toBeDefined();
expect({}).toBeDefined();

toBeUndefined​

Checks if a value is undefined.

expect(undefined).toBeUndefined();

Truthiness Matchers​

toBeTruthy​

Asserts that a value is truthy.

expect(true).toBeTruthy();
expect(1).toBeTruthy();

toBeFalsy​

Asserts that a value is falsy.

expect(false).toBeFalsy();
expect(0).toBeFalsy();

Numeric Comparisons​

toBeGreaterThan​

Checks if a value is greater than another.

expect(5).toBeGreaterThan(3);

toBeGreaterThanOrEqual​

Checks if a value is greater than or equal to another.

expect(5).toBeGreaterThanOrEqual(5);

toBeLessThan​

Checks if a value is less than another.

expect(3).toBeLessThan(5);

toBeLessThanOrEqual​

Checks if a value is less than or equal to another.

expect(3).toBeLessThanOrEqual(3);

toBeCloseTo​

Ensures floating-point numbers are close to each other.

expect(0.1 + 0.2).toBeCloseTo(0.3);

String and Array Matchers​

toMatch​

Validates if a string matches a given regular expression.

expect('hello world').toMatch(/world/);

toContain​

Checks if an array or string contains a specific value.

expect([1, 2, 3]).toContain(2);
expect('hello world').toContain('world');

Exception Matchers​

toThrow​

Ensures a function throws an error.

expect(() => {
  throw new Error('error');
}).toThrow('error');

Object Matchers​

toHaveLength​

Verifies the length of an array or string.

expect([1, 2, 3]).toHaveLength(3);
expect('hello').toHaveLength(5);

toHaveProperty​

Checks if an object has a specific property.

expect({ a: 1 }).toHaveProperty('a');
expect({ a: 1 }).toHaveProperty('a', 1);

toBeInstanceOf​

Ensures an object is an instance of a specific class.

class MyClass {}
const instance = new MyClass();
expect(instance).toBeInstanceOf(MyClass);

Mock Function Matchers​

toHaveBeenCalled​

Checks if a mock function has been called.

const mockFn = vi.fn();
mockFn();
expect(mockFn).toHaveBeenCalled();

toHaveBeenCalledWith​

Verifies if a mock function has been called with specific arguments.

const mockFn = vi.fn();
mockFn(1, 2);
expect(mockFn).toHaveBeenCalledWith(1, 2);

toHaveReturnedWith​

Checks if a mock function has returned a specific value.

const mockFn = vi.fn().mockReturnValue(42);
const result = mockFn();
expect(mockFn).toHaveReturnedWith(42);

Snapshot Testing​

toMatchSnapshot​

Compares a value to a stored snapshot.

expect({ a: 1 }).toMatchSnapshot();