[Feature]: Support for Error.cause in jest.Matchers

[SimonSiefke]

🚀 Feature Proposal

Error.cause has been freshly added to the JavaScript language (https://tc39.es/ecma262/#sec-error-message) and makes chaining errors easier than ever.

Motivation

Error.cause is a very useful feature. It would be very useful if it would be possible to test Error.cause with jest

Related: #11935

Example

toThrowError could accept cause as an additional property:

test('getJson - error', async () => {
  const mockError = new SyntaxError('Unexpected token')
  Ajax.getJson = jest.fn(() => {
    throw mockError
  })
  await expect(Ajax.getJson('https://example.com')).rejects.toThrowError({
    message: 'Failed to fetch "https://example.com"',
    cause: mockError, // support this
  })
})

Pitch

It is a core feature of the javascript language and would be very useful.

[slorber]

It would also be great to support asserting all the chained error-cause messages at once, maybe with toThrowErrorMatchingInlineSnapshot?

I wrote this temporarily (facebook/docusaurus#8234) because I'm not sure how to assert this with Jest in a better way:

  it('docs with invalid id', async () => {
    const error = await testUtils.getProcessDocFileError("some/fake/path");

    expect(error.message).toMatchInlineSnapshot(
      `"Can't process doc metadata for doc at path path=some/fake/path in version name=current"`,
    );
    expect(error.cause).toBeDefined();
    expect(error.cause!.message).toMatchInlineSnapshot(
      `"Document id "Hello/world" cannot include slash."`,
    );
  });

[SimenB]

PR very much welcome for this! 🙂

Some discussion in #13260 as well

[ibuibu]

I will try this ✋

[SimenB]

https://github.com/facebook/jest/releases/tag/v29.4.3

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.
Please note this issue tracker is not a help forum. We recommend using StackOverflow or our discord channel for questions.