expect.fail(...)

Explicitly forces failure.

expect.fail();

Explicit failure

expect.fail('Custom failure message');

Custom failure message

expect.fail('{0} was expected to be {1}', 0, 'zero');

0 was expected to be 'zero'

In case you want to rethrow an error, you should always use expect.fail, as it ensures that the error message will be correct for the different error modes.

const error = new Error('throw me');
expect.fail(new Error(error));

Error: throw me

When you want to build a completely custom output, you can call expect.fail with a callback and receive a magicpen instance that the output can be written to.

expect.fail(function (output) {
  'You have been a very bad boy!'.split(/ /).forEach(function (word, index) {
    if (index > 0) {
      output.sp();
    }
    const style = index % 2 === 0 ? 'jsPrimitive' : 'jsString';
    output[style](word);
  });
});

You have been a very bad boy!

If you want to build an error containing a diff you can call expect.fail with a error definition.

expect.fail({
  message: function (output) {
    'You have been a very bad boy!'.split(/ /).forEach(function (word, index) {
      if (index > 0) {
        output.sp();
      }
      const style = index % 2 === 0 ? 'jsPrimitive' : 'jsString';
      output[style](word);
    });
  },
  diff: function (output, diff, inspect, equal) {
    return diff(
      'You have been a very bad boy!',
      'You have been a very mad boy!'
    );
  },
});

You have been a very bad boy!
 
You have been a very bad boy!
You have been a very mad boy!

The message can be either a string a magicpen instance or a function that will recieve a magicpen instance.

If you are using the default error mode, you don't have to specify the error message as it is just thrown away.

The diff is a method that will create a custom diff lazily. To get a better understanding of the diff method see the type documentation.