Custom Jest Matchers for More Expressive Tests

Writing clear and maintainable tests is crucial for any software project. While Jest provides a great set of built-in matchers, sometimes we need more specific assertions that better express our testing intentions. Let’s dive into creating custom Jest matchers that can make our tests more readable and maintainable.

Why Custom Matchers?

Imagine you’re testing a shopping cart functionality. You could write:

expect(cart.items.length).toBe(0);
expect(cart.total).toBe(0);

But wouldn’t it be nicer to write:

expect(cart).toBeEmpty();

This is where custom matchers shine – they help us write more expressive and domain-specific tests.

Creating Your First Custom Matcher

Let’s create a custom matcher that checks if an object has specific properties with certain types:

expect.extend({
  toHavePropertyOfType(received, property, expectedType) {
    const hasProperty = received.hasOwnProperty(property);
    const propertyType = typeof received[property];

    return {
      pass: hasProperty && propertyType === expectedType,
      message: () =>
        `Expected object to have property "${property}" of type "${expectedType}", ` +
        `but got ${hasProperty ? `type "${propertyType}"` : 'no such property'}`
    };
  }
});

Now we can use it like this:

expect(user).toHavePropertyOfType('age', 'number');
expect(product).toHavePropertyOfType('description', 'string');

Advanced Matcher Techniques

Let’s explore some advanced techniques for creating more powerful custom matchers.

Async Matchers

Sometimes we need to test asynchronous behavior:

expect.extend({
  async toEventuallyHaveValue(received, expectedValue, timeout = 5000) {
    const start = Date.now();

    while (Date.now() - start < timeout) {
      if (received.value === expectedValue) {
        return {
          pass: true,
          message: () => `Expected value to eventually be ${expectedValue}`
        };
      }
      await new Promise(resolve => setTimeout(resolve, 100));
    }

    return {
      pass: false,
      message: () =>
        `Expected value to be ${expectedValue} within ${timeout}ms, but it wasn't`
    };
  }
});

Chainable Matchers

We can create more flexible assertions by making our matchers chainable:

expect.extend({
  toBeWithinRange(received, floor, ceiling) {
    const pass = received >= floor && received <= ceiling;
    return {
      pass,
      message: () =>
        `Expected ${received} to be within range [${floor}, ${ceiling}]`
    };
  }
});

// Usage
expect(price).toBeWithinRange(10, 20);

Best Practices

1. Keep matchers focused and single-purpose
2. Use clear, descriptive names
3. Provide detailed error messages
4. Document your custom matchers
5. Share common matchers across your team

Conclusion

Custom Jest matchers are a powerful tool for creating more expressive and maintainable tests. By encapsulating complex assertions into simple, readable matchers, we can make our test suites easier to understand and maintain.

Remember, the goal is to make your tests as clear as possible – if you find yourself writing the same complex assertions repeatedly, it might be time to create a custom matcher!