Jest Custom Matchers in TypeScript: A Comprehensive Guide

Jest is a popular JavaScript testing framework, known for its simplicity and powerful features. Custom matchers in Jest allow developers to extend the built - in assertion capabilities, making test code more readable and expressive. When combined with TypeScript, we can leverage its static typing to catch errors early and ensure type safety in our tests. This blog post will explore the fundamental concepts, usage methods, common practices, and best practices of Jest custom matchers in TypeScript.

Table of Contents#

  1. Fundamental Concepts
  2. Usage Methods
  3. Common Practices
  4. Best Practices
  5. Conclusion
  6. References

Fundamental Concepts#

What are Jest Custom Matchers?#

Jest comes with a set of built - in matchers like toBe, toEqual, etc. Custom matchers are user - defined functions that can be used to perform custom assertions. They take the received value and optionally an expected value as parameters and return an object with a pass property indicating whether the assertion passed or failed, and a message property that provides an error message in case of failure.

TypeScript Integration#

In TypeScript, we need to define the types for our custom matchers. This involves extending the Jest global namespace to include the new matcher. By doing so, TypeScript can understand the new matcher and provide type checking and autocompletion support.

Usage Methods#

Defining a Custom Matcher#

Let's start by defining a simple custom matcher that checks if a number is even.

// customMatchers.ts
export const toBeEven = (received: number) => {
    const pass = received % 2 === 0;
    return {
        pass,
        message: () =>
            pass
                ? `Expected ${received} not to be even.`
                : `Expected ${received} to be even.`
    };
};

Extending the Jest Global Namespace#

To use the custom matcher in TypeScript, we need to extend the Jest global namespace.

// customMatchers.d.ts
import { toBeEven } from './customMatchers';
 
declare global {
    namespace jest {
        interface Matchers<R> {
            toBeEven(): R;
        }
    }
}
 
expect.extend({
    toBeEven
});

Using the Custom Matcher in Tests#

Now we can use the custom matcher in our tests.

// test.ts
describe('Custom Matcher Test', () => {
    test('should pass when number is even', () => {
        expect(4).toBeEven();
    });
 
    test('should fail when number is odd', () => {
        expect(5).not.toBeEven();
    });
});

Common Practices#

Parameterized Matchers#

We can create matchers that accept additional parameters. For example, a matcher that checks if a string contains a specific substring.

// customMatchers.ts
export const toContainSubstring = (received: string, expected: string) => {
    const pass = received.includes(expected);
    return {
        pass,
        message: () =>
            pass
                ? `Expected ${received} not to contain ${expected}.`
                : `Expected ${received} to contain ${expected}.`
    };
};
 
// customMatchers.d.ts
import { toContainSubstring } from './customMatchers';
 
declare global {
    namespace jest {
        interface Matchers<R> {
            toContainSubstring(expected: string): R;
        }
    }
}
 
expect.extend({
    toContainSubstring
});
 
// test.ts
describe('Parameterized Matcher Test', () => {
    test('should pass when string contains substring', () => {
        expect('hello world').toContainSubstring('world');
    });
 
    test('should fail when string does not contain substring', () => {
        expect('hello world').not.toContainSubstring('foo');
    });
});

Grouping Matchers#

It's a good practice to group related matchers in a single file or module. This makes the code more organized and easier to maintain.

Best Practices#

Error Messages#

Provide clear and descriptive error messages for each matcher. This helps in quickly identifying the cause of test failures.

Testing the Matchers#

Just like any other code, custom matchers should be tested. Write unit tests for your custom matchers to ensure they work as expected.

// customMatchers.test.ts
import { toBeEven } from './customMatchers';
 
describe('toBeEven Matcher', () => {
    test('should return pass true for even numbers', () => {
        const result = toBeEven(4);
        expect(result.pass).toBe(true);
    });
 
    test('should return pass false for odd numbers', () => {
        const result = toBeEven(5);
        expect(result.pass).toBe(false);
    });
});

Documentation#

Document your custom matchers. Explain what they do, what parameters they accept, and when they should be used. This helps other developers understand and use the matchers correctly.

Conclusion#

Jest custom matchers in TypeScript are a powerful tool for enhancing the readability and expressiveness of test code. By understanding the fundamental concepts, following the usage methods, and applying common and best practices, developers can create robust and maintainable test suites. TypeScript's static typing ensures type safety and early error detection, making the testing process more reliable.

References#

2025-10