.toThrow(error)

Also under the alias: .toThrowError(error)

Use .toThrow to test that a function throws when it is called. For example, if we want to test that drinkFlavor('octopus') throws, because octopus flavor is too disgusting to drink, we could write:

test('throws on octopus', () => {
  expect(() => {
    drinkFlavor('octopus');
  }).toThrow();
});

To test that a specific error is thrown, you can provide an argument:

• regular expression: error message matches the pattern
• string: error message includes the substring
• error object: error message is equal to the message property of the object
• error class: error object is instance of class
  For example, let's say that drinkFlavor is coded like this:

function drinkFlavor(flavor) {
  if (flavor == 'octopus') {
    throw new DisgustingFlavorError('yuck, octopus flavor');
  }
  // Do some other stuff
}

We could test this error gets thrown in several ways:

test('throws on octopus', () => {
  function drinkOctopus() {
    drinkFlavor('octopus');
  }
  // Test that the error message says "yuck" somewhere: these are equivalent
  expect(drinkOctopus).toThrowError(/yuck/);
  expect(drinkOctopus).toThrowError('yuck');
  // Test the exact error message
  expect(drinkOctopus).toThrowError(/^yuck, octopus flavor$/);
  expect(drinkOctopus).toThrowError(new Error('yuck, octopus flavor'));
  // Test that we get a DisgustingFlavorError
  expect(drinkOctopus).toThrowError(DisgustingFlavorError);
});

Note: You must wrap the code in a function, otherwise the error will not be caught and the assertion will fail.