Matchers and Assertions

Matchers are the building blocks of test assertions. Both Jest and Vitest share the same matcher API (Vitest was designed as a drop-in replacement), so learning these matchers applies to both test runners. Choosing the right matcher makes tests more readable and produces better error messages when tests fail.

Equality Matchers

toBe(value) uses Object.is() for strict equality (similar to ===). Use it for primitives (numbers, strings, booleans) and reference checks. It fails for objects with the same content but different references.

toEqual(value) performs deep equality comparison, recursively checking object properties and array elements. Use it for objects and arrays where you care about the content, not the reference.

expect(2 + 2).toBe(4);                    // primitive: use toBe
expect({ a: 1 }).toEqual({ a: 1 });        // object: use toEqual
expect({ a: 1 }).not.toBe({ a: 1 });       // different references!

toStrictEqual(value) is like toEqual but also checks that objects have the same type (class instance vs plain object) and that there are no undefined properties. Prefer this over toEqual when you want stricter validation.

Truthiness Matchers

• toBeTruthy(): Passes if the value is truthy (not false, 0, '', null, undefined, NaN)
• toBeFalsy(): Passes if the value is falsy
• toBeNull(): Passes only for null
• toBeUndefined(): Passes only for undefined
• toBeDefined(): Passes for any value that is not undefined

Use specific matchers (toBeNull, toBeUndefined) over generic ones (toBeFalsy) for clearer intent and better error messages.

Number Matchers

• toBeGreaterThan(n) / toBeLessThan(n): Strict comparison
• toBeGreaterThanOrEqual(n) / toBeLessThanOrEqual(n): Inclusive comparison
• toBeCloseTo(n, digits): Floating-point comparison that avoids precision issues. Use this instead of toBe for decimal math: expect(0.1 + 0.2).toBeCloseTo(0.3)

String Matchers

toMatch(pattern) accepts a regex or string. Use it for partial string matching or pattern validation:

expect('hello world').toMatch(/world/);
expect(errorMessage).toMatch('not found');

Array and Iterable Matchers

• toContain(item): Checks if an array or string contains the item (uses ===)
• toContainEqual(item): Like toContain but uses deep equality for objects in arrays
• toHaveLength(n): Checks the .length property

Object Matchers

• toHaveProperty(path, value?): Checks nested properties using dot notation or array paths
• toMatchObject(subset): Checks that the object contains at least the specified properties (allows extra properties)
• expect.objectContaining({}): Asymmetric matcher for partial object matching inside other matchers

Exception Matchers

toThrow(error?) verifies that a function throws. The function must be wrapped in another function:

expect(() => divide(1, 0)).toThrow('Cannot divide by zero');
expect(() => parseJSON('{')).toThrow(SyntaxError);

Negation

Any matcher can be negated with .not: expect(value).not.toBe(other).

Asymmetric Matchers

For flexible matching inside complex structures:

• expect.any(Constructor): Matches any instance of the constructor
• expect.stringContaining(str): Matches strings containing the substring
• expect.arrayContaining(arr): Matches arrays containing at least those elements

These are powerful for testing objects with dynamic fields like timestamps or IDs.