Testing is a crucial part of software development, and Jest has become a popular choice for many developers. But let’s face it, writing tests can sometimes feel like a chore. That’s where custom matchers come in to save the day!
Custom matchers are like your secret weapon for creating cleaner, more expressive tests. They allow you to define your own assertions that match your specific use cases. This means you can write tests that are not only easier to read but also more maintainable in the long run.
I remember when I first discovered custom matchers – it was a game-changer for my testing workflow. Suddenly, my tests became more intuitive and less cluttered with boilerplate code. It’s like having a superhero sidekick for your test suite!
Let’s dive into how you can leverage custom matchers to supercharge your Jest tests. We’ll start with a simple example:
expect.extend({
toBeWithinRange(received, floor, ceiling) {
const pass = received >= floor && received <= ceiling;
if (pass) {
return {
message: () => `expected ${received} not to be within range ${floor} - ${ceiling}`,
pass: true,
};
} else {
return {
message: () => `expected ${received} to be within range ${floor} - ${ceiling}`,
pass: false,
};
}
},
});
test('number is within range', () => {
expect(100).toBeWithinRange(90, 110);
});
In this example, we’ve created a custom matcher called toBeWithinRange. It checks if a number falls within a specified range. Now, instead of writing multiple assertions, we can use this single, expressive matcher.
But custom matchers aren’t just for simple comparisons. They really shine when dealing with complex objects or specific domain logic. Let’s say you’re working on an e-commerce platform and want to test if a product object is valid:
expect.extend({
toBeValidProduct(received) {
const isValid =
received.id &&
received.name &&
received.price > 0 &&
Array.isArray(received.categories);
if (isValid) {
return {
message: () => `expected ${JSON.stringify(received)} not to be a valid product`,
pass: true,
};
} else {
return {
message: () => `expected ${JSON.stringify(received)} to be a valid product`,
pass: false,
};
}
},
});
test('product is valid', () => {
const product = {
id: '123',
name: 'Cool Gadget',
price: 99.99,
categories: ['electronics', 'gadgets'],
};
expect(product).toBeValidProduct();
});
This custom matcher encapsulates all the logic for validating a product object. It’s much cleaner than writing out all those individual checks every time you need to test a product.
One of the coolest things about custom matchers is that they’re reusable. Once you’ve defined them, you can use them across your entire test suite. This promotes consistency and reduces duplication in your tests.
But wait, there’s more! Custom matchers can also be async. This is super helpful when you’re dealing with promises or async operations. Here’s an example:
expect.extend({
async toBeResolvedWithin(promise, timeout) {
let error;
const start = Date.now();
try {
await Promise.race([
promise,
new Promise((_, reject) =>
setTimeout(() => reject(new Error('Timeout')), timeout)
),
]);
} catch (e) {
error = e;
}
const duration = Date.now() - start;
const pass = !error && duration <= timeout;
if (pass) {
return {
message: () => `expected promise not to resolve within ${timeout}ms`,
pass: true,
};
} else {
return {
message: () => `expected promise to resolve within ${timeout}ms`,
pass: false,
};
}
},
});
test('API call resolves quickly', async () => {
const apiCall = fetch('https://api.example.com/data');
await expect(apiCall).toBeResolvedWithin(1000);
});
This async custom matcher checks if a promise resolves within a specified timeout. It’s a great way to ensure your API calls or other async operations are performing as expected.
Now, you might be wondering, “Can I use custom matchers with TypeScript?” Absolutely! In fact, custom matchers play really nicely with TypeScript, giving you all that type-safety goodness. Here’s how you can define a custom matcher with TypeScript:
declare global {
namespace jest {
interface Matchers<R> {
toBeEvenNumber(): R;
}
}
}
expect.extend({
toBeEvenNumber(received: number) {
const pass = received % 2 === 0;
if (pass) {
return {
message: () => `expected ${received} not to be an even number`,
pass: true,
};
} else {
return {
message: () => `expected ${received} to be an even number`,
pass: false,
};
}
},
});
test('number is even', () => {
expect(4).toBeEvenNumber();
});
By declaring the matcher in the global namespace, TypeScript will recognize it and provide autocomplete and type checking. It’s like having a safety net for your tests!
Custom matchers are also great for improving the readability of your test output. When a test fails, Jest will use the message you’ve defined in your custom matcher. This means you can provide clear, context-specific error messages that make debugging a breeze.
One thing I’ve found super useful is creating custom matchers for common patterns in my codebase. For example, if you’re working with a lot of date manipulations, you might create matchers like toBeWeekend(), toBeBusinessDay(), or toBeSameMonthAs(). These domain-specific matchers can make your tests read almost like natural language.
test('delivery date is a business day', () => {
const deliveryDate = new Date('2023-06-05'); // A Monday
expect(deliveryDate).toBeBusinessDay();
});
test('selected date is in the same month as today', () => {
const selectedDate = new Date('2023-06-15');
expect(selectedDate).toBeSameMonthAs(new Date());
});
Custom matchers can also be a great way to enforce coding standards or best practices. For instance, you could create a matcher to ensure that all your React components have a data-testid attribute:
expect.extend({
toHaveTestId(received) {
const pass = received.props && received.props['data-testid'];
if (pass) {
return {
message: () => `expected component not to have a data-testid`,
pass: true,
};
} else {
return {
message: () => `expected component to have a data-testid`,
pass: false,
};
}
},
});
test('component has a test id', () => {
const component = <MyComponent data-testid="my-component" />;
expect(component).toHaveTestId();
});
This kind of matcher can help maintain consistency across your codebase and make future testing easier.
When creating custom matchers, it’s important to remember the principle of single responsibility. Each matcher should do one thing and do it well. This makes your matchers more reusable and easier to maintain.
Another pro tip: document your custom matchers well. If you’re working in a team, clear documentation can help other developers understand and use your matchers effectively. You might even consider creating a shared library of custom matchers for your team or organization.
Custom matchers can also be a great tool for testing edge cases. Instead of writing complex conditionals in your tests, you can encapsulate that logic in a custom matcher. This not only makes your tests cleaner but also ensures that you’re consistently checking for those edge cases across your test suite.
Let’s say you’re working on a financial application and need to test for monetary values. You might create a custom matcher like this:
expect.extend({
toBeValidMonetaryValue(received) {
const isValid = typeof received === 'number' &&
received >= 0 &&
received.toFixed(2) === received.toString();
if (isValid) {
return {
message: () => `expected ${received} not to be a valid monetary value`,
pass: true,
};
} else {
return {
message: () => `expected ${received} to be a valid monetary value`,
pass: false,
};
}
},
});
test('value is a valid monetary amount', () => {
expect(10.50).toBeValidMonetaryValue();
expect(10.5).not.toBeValidMonetaryValue(); // This would fail
expect(-5).not.toBeValidMonetaryValue();
});
This matcher ensures that a value is not only a positive number but also has exactly two decimal places, which is a common requirement for monetary values.
Custom matchers can also be incredibly useful when working with external libraries or APIs. They can help abstract away the complexity of testing these integrations. For example, if you’re working with a GraphQL API, you might create a matcher to check if a query result matches a certain shape:
expect.extend({
toMatchGraphQLShape(received, expected) {
const match = (obj, shape) => {
for (let key in shape) {
if (!(key in obj)) return false;
if (typeof shape[key] === 'object') {
if (!match(obj[key], shape[key])) return false;
}
}
return true;
};
const pass = match(received, expected);
if (pass) {
return {
message: () => `expected ${JSON.stringify(received)} not to match GraphQL shape ${JSON.stringify(expected)}`,
pass: true,
};
} else {
return {
message: () => `expected ${JSON.stringify(received)} to match GraphQL shape ${JSON.stringify(expected)}`,
pass: false,
};
}
},
});
test('GraphQL query result matches expected shape', () => {
const result = {
user: {
id: '123',
name: 'John Doe',
posts: [
{ id: '1', title: 'Hello World' },
{ id: '2', title: 'Custom Matchers Rock' },
],
},
};
expect(result).toMatchGraphQLShape({
user: {
id: expect.any(String),
name: expect.any(String),
posts: expect.arrayContaining([
expect.objectContaining({
id: expect.any(String),
title: expect.any(String),
}),
]),
},
});
});
This matcher checks if the result matches the expected shape, without being too strict about the exact values. It’s a flexible way to test API responses.
Remember, the goal of custom matchers is to make your tests more expressive and easier to understand. They should make your test code read more like natural language and less like complex programming logic.
In conclusion, custom matchers are a powerful tool in your testing arsenal. They can help you write cleaner, more expressive, and more maintainable tests. By encapsulating complex assertions into reusable matchers, you can make your tests easier to write and easier to read. So go ahead, get creative, and start supercharging your Jest tests with custom matchers!