---

Problem

In many testing libraries it is possible to supply a custom message for a given expectation, this is currently not possible in Jest.

For example:

1test('returns 2 when adding 1 and 1', () => {
2  expect(1 + 1, 'Woah this should be 2!').toBe(3);
3});

This will throw the following error in Jest:

1Expect takes at most one argument.

Solution

jest-expect-message allows you to call expect with a second argument of a String message.

For example the same test as above:

1test('returns 2 when adding 1 and 1', () => {
2  expect(1 + 1, 'Woah this should be 2!').toBe(3);
3});

With jest-expect-message this will fail with your custom error message:

1  ● returns 2 when adding 1 and 1
2
3    Custom message:
4      Woah this should be 2!
5
6    expect(received).toBe(expected) // Object.is equality
7
8    Expected: 3
9    Received: 2

Installation

With npm:

1npm install --save-dev jest-expect-message

With yarn:

1yarn add -D jest-expect-message

Setup

Add jest-expect-message to your Jest setupFilesAfterEnv configuration. See for help

Jest v24+

1"jest": {
2  "setupFilesAfterEnv": ["jest-expect-message"]
3}

Jest v23-

1"jest": {
2  "setupTestFrameworkScriptFile": "jest-expect-message"
3}

If you have a custom setup file and want to use this library then add the following to your setup file.

1import 'jest-expect-message';

Configure Typescript

Add the following entry to your tsconfig to enable Typescript support.

1  "files": ["node_modules/jest-expect-message/types/index.d.ts"],

Example

Custom message example with typescript

Configure ESlint

1"rules": {
2  "jest/valid-expect": [
3    "error",
4    {
5      "maxArgs": 2
6    }
7  ]
8}

Usage

• expect(actual, message, options?)
  • actual: The value you would normally pass into an expect to assert against with a given matcher.
  • message: String, the custom message you want to be printed should the expect fail.
  • options: An optional object that controls what is shown as part of the custom message.
    • showPrefix: boolean: If false will not show the Custom message: prefix. Default: true
    • showMatcherMessage: boolean: If false will not show the matchers original error message. Default: true
    • showStack: boolean: If false will not show the matchers stack trace. Default: true

1test('returns 2 when adding 1 and 1', () => {
2  expect(1 + 1, 'Woah this should be 2!').toBe(3);
3});
4// ↓ ↓ ↓ ↓ ↓ ↓
5/*
6  ● returns 2 when adding 1 and 1
7
8    Custom message:
9      Woah this should be 2!
10
11    expect(received).toBe(expected) // Object.is equality
12
13    Expected: 3
14    Received: 2
15
16  1 |   test('returns 2 when adding 1 and 1', () => {
17> 2 |     expect(1 + 1, 'Woah this should be 2!').toBe(3);
18    |                                             ^
19  3 |   });
20*/

showPrefix: false

1test('returns 2 when adding 1 and 1', () => {
2  expect(1 + 1, 'Woah this should be 2!', { showPrefix: false }).toBe(3);
3});
4// ↓ ↓ ↓ ↓ ↓ ↓
5/*
6  ● returns 2 when adding 1 and 1
7
8    Woah this should be 2!
9
10    expect(received).toBe(expected) // Object.is equality
11
12    Expected: 3
13    Received: 2
14
15  1 |   test('returns 2 when adding 1 and 1', () => {
16> 2 |     expect(1 + 1, 'Woah this should be 2!', { showPrefix: false }).toBe(3);
17    |                                                                    ^
18  3 |   });
19*/

showMatcherMessage: false

1test('returns 2 when adding 1 and 1', () => {
2  expect(1 + 1, 'Woah this should be 2!', { showMatcherMessage: false }).toBe(3);
3});
4// ↓ ↓ ↓ ↓ ↓ ↓
5/*
6  ● returns 2 when adding 1 and 1
7
8    Custom message:
9      Woah this should be 2!
10
11  1 |   test('returns 2 when adding 1 and 1', () => {
12> 2 |     expect(1 + 1, 'Woah this should be 2!', { showMatcherMessage: false }).toBe(3);
13    |                                                                            ^
14  3 |   });
15*/

showStack: false

1test('returns 2 when adding 1 and 1', () => {
2  expect(1 + 1, 'Woah this should be 2!', { showStack: false }).toBe(3);
3});
4// ↓ ↓ ↓ ↓ ↓ ↓
5/*
6  ● returns 2 when adding 1 and 1
7
8    Custom message:
9      Woah this should be 2!
10
11    expect(received).toBe(expected) // Object.is equality
12
13    Expected: 3
14    Received: 2
15*/

LICENSE

MIT