Jest's toBe assertion with custom message (expected value alias)

assertions.test.ts

describe('Assertions with expected value alias', () => {
  it('reports the failure with a meaningul message', async () => {
    expect(7).toBe(42, 'The Answer to the Ultimate Question of Life, the Universe, and Everything');
  });

  it('given no custom value alias, it reports the failure with the standard message', async () => {
    expect(7).toBe(42);
  });
});

customMatchers.ts

import matchers from 'expect/build/matchers.js';
import { printExpected, printReceived } from 'jest-matcher-utils';

const originalToBe = matchers.toBe.bind(matchers);

expect.extend({
  toBe(received, expected, expectedValueAlias) {
    const {
      message: messageFn,
      pass
    } = originalToBe(received, expected);

    if (pass) {
      return {
        pass: true,
        message: messageFn,
      };
    }

    return {
      pass: false,
      message: (): string => expectedValueAlias ?
        `Expected: ${printExpected(`${expectedValueAlias} (${expected})`)}\nGot: ${printReceived(received)}\n\n${messageFn()}` :
        messageFn()
    };
  }
});

jest.config.js

module.exports = {
  transform: {
    '^.+\\.ts?$': 'ts-jest',
  },
  testRegex: '(/__tests__/.*|(\\.|/)(test|spec))\\.ts?$',
  testEnvironment: 'node',
  rootDir: '.',
  setupFilesAfterEnv: ['./customMatchers.ts']
};

jest.d.ts

// src/types/jest.d.ts
declare namespace jest {
  interface Matchers<R> {
    toBe(expectedValue: unknown, expectedValueAlias?: string): CustomMatcherResult;
  }
}

tsonfig.json

{
  "compilerOptions": {
    "module": "commonjs",
    "declaration": true,
    "outDir": "./build",
    "allowJs": true,
    "target": "esnext",
    "esModuleInterop": true,
    "sourceMap": true,
    "emitDecoratorMetadata": true,
    "experimentalDecorators": true
  },
  "include": [
    "src/types/*.d.ts",
    "./src/**/*"
  ],
  "exclude": ["node_modules"]
}