Jest Matchers: Asserting Values in Your Tests

Why it exists

Writing tests requires a way to check that the values your code produces are correct. Without a structured way to make these checks, or "assertions," tests would be a messy collection of if/else statements, making it hard to see what failed and why.

The mental model

The expect function gives you access to a library of "matchers." A matcher is a function that performs a specific comparison. The pattern is always expect(value_from_your_code).matcher(expected_value). This reads like a sentence in English: "I expect the result of myFunction() to be true."

How it works

When you call expect(value), Jest returns an object containing all possible matcher functions. You chain one of these matchers, like .toBe() or .toEqual(), to perform the check. For example, .toBe() uses strict equality (===) for primitives, while .toEqual() recursively checks all properties of an object. Modifiers like .not can be chained before the matcher to invert the assertion. For asynchronous code, you can use .resolves or .rejects with async/await to test the outcome of a Promise.

When to use it

Use matchers in every Jest test you write, as they are the core mechanism for validating behavior. Common use cases include checking if a function returns a specific string with .toBe('some-string'), verifying an array contains an item with .toContain(item), ensuring an object has a certain shape with .toMatchObject({ key: value }), or testing that a function throws an error with .toThrow().

When not to use it

The primary footgun is not about when to avoid matchers, but how to use them correctly. The most common error is putting the expected value in expect() and the actual value in the matcher. For example, expect('grapefruit').toBe(bestLaCroixFlavor()) is wrong. While the test might pass, a failure will produce a confusing message like "Expected: 'pamplemousse', Received: 'grapefruit'". The correct form is expect(bestLaCroixFlavor()).toBe('grapefruit').

One canonical example

Imagine testing an async function fetchUser(id) that returns a user object. To test the success case, you would write: await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: 'Leanne' });. This uses the .resolves modifier to handle the promise and .toEqual to deeply compare the resulting object. To test the failure case, you would write: await expect(fetchUser(99)).rejects.toThrow('User not found');. This asserts that the promise rejects and that the error message matches.