Writing Tests for Custom Matchers in Jest

TLDR: Here's an example of how to write a test for a custom matcher:

describe("toHaveDevDependency", () => {
  it("fails when given a number", () => {
    expect(() => {
      expect(2).toHaveDevDependency("node");
    }).toThrow("Expected 2 to be a YeomanTest.RunResult");
  );
});

Motivation

In the spirit of TDD, I found myself wanting to write tests to ensure my Jest custom matchers work properly.

A quick Google Search for "Jest write tests for custom matcher" only produced results about writing custom matchers themselves when really I wanted to see examples of how to write tests that exercise my custom matchers.

After figuring out how to do this on my own, I thought I'd write the missing article :).

Background

If you're familiar with Jest, you're likely also familiar with custom matchers.

If not, here's the summary version: custom matchers allow you to add your own matching assertions for expect statements. This can be super useful when you find yourself writing the same testing code over and over again and want to DRY up your tests.

Example Situation

This happened recently when writing a Yeoman generator to quickly scaffold new projects. I wanted to write something like expect(result).toHaveDevDependency("typescript") to assert that the package.json file generated with the project includes a specified package in its devDependencies.

The testing helpers provided by Yeoman in yeoman-test include a useful assertJsonFileContent(fileName: string, content: any) method, but as I found myself writing things like

result.assertJsonFileContent(
  "package.json",
  { 
    devDependencies: {
      typescript: "4.7.4"
    }
  },
);

over and over I got tired of the verbosity and realized that this line doesn't state my intent as clearly as it could.

I wanted something like this instead:

expect(result).toHaveDevDependency("typescript", "4.7.4");

Simple, clear, and clean.

My toHaveDevDependency custom matcher ended up being reasonably complicated, including checks to ensure that the received object in the expect call was, indeed, a YeomanTest.RunResult object, and then wrapping the result.assertJsonFileContent() call with a try/catch to translate that result into either a passing or failing jest.CustomMatcherResult with a useful message.

Ironically, the custom matcher ended up showing up in my code coverage reports as the least tested part of my codebase.

The Solution

I wrote myself a test suite for toHaveDevDependency and in the process, I had to figure out how to test an expect statement itself. Rather meta.

First Attempt: wrap expect call in a try/catch

My first attempt looked something like this:

describe("toHaveDevDependency", () => {
  it("fails when given a number", () => {
    try {
      expect(2).toHaveDevDependency("node");
    } catch (error) {
      expect(error.message).toContain("JestAssertionError");
    }
  );
});

The idea being that Jest is likely throwing some kind of error when an expect assertion fails, and perhaps I can catch that error and then do something with it.

Unfortunately, this does not work. Jest seems to be smart enough to fail the test immediately, and while I can catch the error, I couldn't find an easy way to stop the test from failing down this path. There might be a way, but I gave up before I found it.

Second Attempt: wrap raw expect call with expect().toThrow()

My next idea was to use the expect().toThrow() method to tell Jest explicitly that I'm expecting an error throw. It looked like this:

describe("toHaveDevDependency", () => {
  it("fails when given a number", () => {
    expect(
      expect(2).toHaveDevDependency("node");
    ).toThrow("Expected 2 to be a YeomanTest.RunResult");
  );
});

This didn't work, either. The test failed immediately.

Final Working Attempt: wrap expect call in an arrow function and wrap that in an expect().toThrow()

I had one more idea: what if I wrap the expect call in an arrow function first?

This looked like this:

describe("toHaveDevDependency", () => {
  it("fails when given a number", () => {
    expect(() => {
      expect(2).toHaveDevDependency("node");
    }).toThrow("Expected 2 to be a YeomanTest.RunResult");
  );
});

This works! I haven't looked into the Jest internals enough to understand exactly why, but intuitively this makes sense: the arrow function insulates the inner call to expect from the Jest test context, and prevents the function call from being executed immediately within the it block.

Now I can happily write test suites for my custom matchers and test everything with confidence!