Using Matchers in Jest

Jest enables you to test values in different ways by using matchers. We will introduce you to some of the matchers that are commonly used.

Common Matchers

Using exact equality is the simplest way to test a value.

test('three plus three is six', () => {
  expect(3 + 3).toBe(6);
});

In the code above example, expect (3 + 3) will return an expectation object. Most times, all you need to do with these expectation objects is to call members with them. In the code example above, .toBe(6) is the matcher. When we run Jest, it will track all the falling matchers, so that it can print out nice error for us.

toBe will make use of Object.is to test exact equality. If you need to check the value of an object, you should use toEqual instead:

test('object assignment', () => {
  const data = {two: 2};
  data['three'] = 3;
  expect(data).toEqual({two: 2, three: 3});
});

toEqual will recursively checks every field of an object or array.

You may also test for the opposite of a matcher:

test('adds positive numbers is not zero', () => {
  for (let a = 1; a < 10; a++) {
    for (let b = 1; b < 10; b++) {
      expect(a + b).not.toBe(0);
    }
  }
});

Truthiness

In tests you sometimes may need to distinguish between undefined, null, and false, and there are times when you do not want to treat these differently. Jest has helpers that let you be explicit about what you want.

• toBeNull will match only null
• toBeUndefined only matches undefined
• toBeDefined is the opposite of toBeUndefined
• toBeTruthy will match anything that an if statement treats as true
• toBeFalsy will match anything that an if statement treats as false

For instance:

test('null', () => {
  const n = null;
  expect(n).toBeNull();
  expect(n).toBeDefined();
  expect(n).not.toBeUndefined();
  expect(n).not.toBeTruthy();
  expect(n).toBeFalsy();
});

test('zero', () => {
  const z = 0;
  expect(z).not.toBeNull();
  expect(z).toBeDefined();
  expect(z).not.toBeUndefined();
  expect(z).not.toBeTruthy();
  expect(z).toBeFalsy();
});

You have to use the matcher that most precisely corresponds to what you want your code to be doing.

Numbers

Most of the ways of comparing numbers have matcher equivalents.

test('two plus two', () => {
  const value = 2 + 2;
  expect(value).toBeGreaterThan(3);
  expect(value).toBeGreaterThanOrEqual(3.5);
  expect(value).toBeLessThan(5);
  expect(value).toBeLessThanOrEqual(4.5);

  // toEqual and toBe are equivalent for numbers
  expect(value).toBe(4);
  expect(value).toEqual(4);
});

When working with floating point equality, you have to use toBeCloseTo instead of toEqual, because you do not want a test to depend on a tiny rounding error.

test('adds floating point numbers', () => {
  const value = 0.1 + 0.2;
  //expect(value).toBe(0.3);           This will not work because of rounding error
  expect(value).toBeCloseTo(0.3); // This will work.
});

Strings

You can check strings against regular expressions using toMatch:

test('there is no L in team', () => {
  expect('team').not.toMatch(/L/);
});
test('but there is a "comma" in Christoph', () => {
  expect('Christoph').toMatch(/comma/);
});

Arrays and iterables

You can check whether an array or iterable contains a particular item with toContain:

const shoppingList = [
  'diapers',
  'kleenex',
  'trash bags',
  'paper towels',
  'candy',
];

test('the shopping list has candy on it', () => {
  expect(shoppingList).toContain('candy');
  expect(new Set(shoppingList)).toContain('candy');
});

Exceptions

In the case where you want to test that a particular function throws an error when it's called, you need to use toThrow.

function compileAndroidCode() {
  throw new ConfigError('the JDK you are using is wrong');
}

test('compiling android will go as expected', () => {
  expect(compileAndroidCode).toThrow();
  expect(compileAndroidCode).toThrow(ConfigError);

  // You may also use the exact error message or a regexp
  expect(compileAndroidCode).toThrow('the JDK you are using is wrong');
  expect(compileAndroidCode).toThrow(/JDK/);
});

And More

Having learnt the matchers that are available, the next step will be to check out how we can use Jest to test asynchronous code.

Previous: Getting Started with Jest
Next: Testing Asynchronous Code in Jest.