feat(jest-message-util): Add support for Error cause in test and it

CHANGELOG.md

@@ -3,6 +3,7 @@
 ### Features
 
 - `[jest-cli, jest-config, @jest/core, jest-haste-map, @jest/reporters, jest-runner, jest-runtime, @jest/types]` Add `workerThreads` configuration option to allow using [worker threads](https://nodejs.org/dist/latest/docs/api/worker_threads.html) for parallelization ([#13939](https://github.com/facebook/jest/pull/13939))
+- `[jest-message-util]` Add support for [Error causes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause) in `test` and `it` ([#13935](https://github.com/facebook/jest/pull/13935))
 - `[jest-worker]` Add `start` method to worker farms ([#13937](https://github.com/facebook/jest/pull/13937))
 
 ### Fixes

e2e/__tests__/__snapshots__/failures.test.ts.snap

@@ -404,6 +404,130 @@ exports[`works with async failures 1`] = `
       at Object.test (__tests__/asyncFailures.test.js:22:1)"
 `;
 
+exports[`works with error with cause 1`] = `
+"FAIL __tests__/errorWithCause.test.js
+  ✕ error with cause in test
+  describe block
+    ✕ error with cause in describe/it
+    ✕ error with string cause in describe/it
+
+  ● error with cause in test
+
+    error during f
+
+      10 |
+      11 | function buildErrorWithCause(message: string, opts: {cause: unknown}): Error {
+    > 12 |   const error = new Error(message, opts);
+         |                 ^
+      13 |   if (opts.cause !== error.cause) {
+      14 |     // Error with cause not supported in legacy versions of node, we just polyfill it
+      15 |     Object.assign(error, opts);
+
+      at buildErrorWithCause (__tests__/errorWithCause.test.js:12:17)
+      at buildErrorWithCause (__tests__/errorWithCause.test.js:27:11)
+      at Object.f (__tests__/errorWithCause.test.js:32:3)
+
+    Cause:
+    error during g
+
+      19 |
+      20 | function g() {
+    > 21 |   throw new Error('error during g');
+         |         ^
+      22 | }
+      23 | function f() {
+      24 |   try {
+
+      at g (__tests__/errorWithCause.test.js:21:9)
+      at g (__tests__/errorWithCause.test.js:25:5)
+      at Object.f (__tests__/errorWithCause.test.js:32:3)
+
+  ● describe block › error with cause in describe/it
+
+    error during f
+
+      10 |
+      11 | function buildErrorWithCause(message: string, opts: {cause: unknown}): Error {
+    > 12 |   const error = new Error(message, opts);
+         |                 ^
+      13 |   if (opts.cause !== error.cause) {
+      14 |     // Error with cause not supported in legacy versions of node, we just polyfill it
+      15 |     Object.assign(error, opts);
+
+      at buildErrorWithCause (__tests__/errorWithCause.test.js:12:17)
+      at buildErrorWithCause (__tests__/errorWithCause.test.js:27:11)
+      at Object.f (__tests__/errorWithCause.test.js:37:5)
+
+    Cause:
+    error during g
+
+      19 |
+      20 | function g() {
+    > 21 |   throw new Error('error during g');
+         |         ^
+      22 | }
+      23 | function f() {
+      24 |   try {
+
+      at g (__tests__/errorWithCause.test.js:21:9)
+      at g (__tests__/errorWithCause.test.js:25:5)
+      at Object.f (__tests__/errorWithCause.test.js:37:5)
+
+  ● describe block › error with string cause in describe/it
+
+    with string cause
+
+      10 |
+      11 | function buildErrorWithCause(message: string, opts: {cause: unknown}): Error {
+    > 12 |   const error = new Error(message, opts);
+         |                 ^
+      13 |   if (opts.cause !== error.cause) {
+      14 |     // Error with cause not supported in legacy versions of node, we just polyfill it
+      15 |     Object.assign(error, opts);
+
+      at buildErrorWithCause (__tests__/errorWithCause.test.js:12:17)
+      at Object.buildErrorWithCause (__tests__/errorWithCause.test.js:41:11)
+
+    Cause:
+    here is the cause"
+`;
+
+exports[`works with error with cause thrown outside tests 1`] = `
+"FAIL __tests__/errorWithCauseInDescribe.test.js
+  ● Test suite failed to run
+
+    error during f
+
+      10 |
+      11 | function buildErrorWithCause(message: string, opts: {cause: unknown}): Error {
+    > 12 |   const error = new Error(message, opts);
+         |                 ^
+      13 |   if (opts.cause !== error.cause) {
+      14 |     // Error with cause not supported in legacy versions of node, we just polyfill it
+      15 |     Object.assign(error, opts);
+
+      at buildErrorWithCause (__tests__/errorWithCauseInDescribe.test.js:12:17)
+      at buildErrorWithCause (__tests__/errorWithCauseInDescribe.test.js:27:11)
+      at f (__tests__/errorWithCauseInDescribe.test.js:32:3)
+      at Object.describe (__tests__/errorWithCauseInDescribe.test.js:31:1)
+
+    Cause:
+     error during g
+
+          19 |
+          20 | function g() {
+        > 21 |   throw new Error('error during g');
+             |         ^
+          22 | }
+          23 | function f() {
+          24 |   try {
+
+          at g (__tests__/errorWithCauseInDescribe.test.js:21:9)
+          at g (__tests__/errorWithCauseInDescribe.test.js:25:5)
+          at f (__tests__/errorWithCauseInDescribe.test.js:32:3)
+          at Object.describe (__tests__/errorWithCauseInDescribe.test.js:31:1)"
+`;
+
 exports[`works with node assert 1`] = `
 "FAIL __tests__/assertionError.test.js
   ✕ assert

e2e/__tests__/failures.test.ts

@@ -6,6 +6,7 @@
  */
 
 import * as path from 'path';
+import {isJestJasmineRun} from '@jest/test-utils';
 import {extractSummary, runYarnInstall} from '../Utils';
 import runJest from '../runJest';
 
@@ -90,6 +91,23 @@ test('works with snapshot failures with hint', () => {
   ).toMatchSnapshot();
 });
 
+(isJestJasmineRun() ? test.skip : test)('works with error with cause', () => {
+  const {stderr} = runJest(dir, ['errorWithCause.test.js']);
+  const summary = normalizeDots(cleanStderr(stderr));
+
+  expect(summary).toMatchSnapshot();
+});
+
+(isJestJasmineRun() ? test.skip : test)(
+  'works with error with cause thrown outside tests',
+  () => {
+    const {stderr} = runJest(dir, ['errorWithCauseInDescribe.test.js']);
+    const summary = normalizeDots(cleanStderr(stderr));
+
+    expect(summary).toMatchSnapshot();
+  },
+);
+
 test('errors after test has completed', () => {
   const {stderr} = runJest(dir, ['errorAfterTestComplete.test.js']);
 

e2e/failures/__tests__/errorWithCause.test.js

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+'use strict';
+
+function buildErrorWithCause(message: string, opts: {cause: unknown}): Error {
+  const error = new Error(message, opts);
+  if (opts.cause !== error.cause) {
+    // Error with cause not supported in legacy versions of node, we just polyfill it
+    Object.assign(error, opts);
+  }
+  return error;
+}
+
+function g() {
+  throw new Error('error during g');
+}
+function f() {
+  try {
+    g();
+  } catch (err) {
+    throw buildErrorWithCause('error during f', {cause: err});
+  }
+}
+
+test('error with cause in test', () => {
+  f();
+});
+
+describe('describe block', () => {
+  it('error with cause in describe/it', () => {
+    f();
+  });
+
+  it('error with string cause in describe/it', () => {
+    throw buildErrorWithCause('with string cause', {
+      cause: 'here is the cause',
+    });
+  });
+});

e2e/failures/__tests__/errorWithCauseInDescribe.test.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ */
+
+'use strict';
+
+function buildErrorWithCause(message: string, opts: {cause: unknown}): Error {
+  const error = new Error(message, opts);
+  if (opts.cause !== error.cause) {
+    // Error with cause not supported in legacy versions of node, we just polyfill it
+    Object.assign(error, opts);
+  }
+  return error;
+}
+
+function g() {
+  throw new Error('error during g');
+}
+function f() {
+  try {
+    g();
+  } catch (err) {
+    throw buildErrorWithCause('error during f', {cause: err});
+  }
+}
+
+describe('error with cause in describe', () => {
+  f();
+});

e2e/transform/transform-esm-testrunner/test-runner.mjs

@@ -23,6 +23,7 @@ export default async function testRunner(
       {
         ancestorTitles: [],
         duration: 2,
+        failureDetails: [],
         failureMessages: [],
         fullName: 'sample test',
         location: null,

e2e/transform/transform-testrunner/test-runner.ts

@@ -24,6 +24,7 @@ export default async function testRunner(
       {
         ancestorTitles: [],
         duration: 2,
+        failureDetails: [],
         failureMessages: [],
         fullName: 'sample test',
         location: null,

packages/jest-message-util/src/__tests__/__snapshots__/messages.test.ts.snap

@@ -40,6 +40,46 @@ exports[`formatStackTrace prints code frame and stacktrace 1`] = `
         "
 `;
 
+exports[`formatStackTrace should properly handle deeply nested causes 1`] = `
+"<bold><red>  <bold>● </intensity><bold>Error with cause test</color></intensity>
+
+    intercepted by f
+<dim></intensity>
+<dim>      <dim>at f (</intensity><dim>cause.test.js<dim>:15:11)</intensity><dim></intensity>
+<dim>      <dim>at Object.f (</intensity><dim>cause.test.js<dim>:20:5)</intensity><dim></intensity>
+
+    Cause:
+    intercepted by g
+<dim></intensity>
+<dim>      <dim>at g (</intensity><dim>cause.test.js<dim>:8:11)</intensity><dim></intensity>
+<dim>      <dim>at g (</intensity><dim>cause.test.js<dim>:13:5)</intensity><dim></intensity>
+<dim>      <dim>at Object.f (</intensity><dim>cause.test.js<dim>:20:5)</intensity><dim></intensity>
+
+    Cause:
+    boom
+<dim></intensity>
+<dim>      <dim>at h (</intensity><dim>cause.test.js<dim>:2:9)</intensity><dim></intensity>
+<dim>      <dim>at h (</intensity><dim>cause.test.js<dim>:6:5)</intensity><dim></intensity>
+<dim>      <dim>at g (</intensity><dim>cause.test.js<dim>:13:5)</intensity><dim></intensity>
+<dim>      <dim>at Object.f (</intensity><dim>cause.test.js<dim>:20:5)</intensity><dim></intensity>
+"
+`;
+
+exports[`formatStackTrace should properly handle string causes 1`] = `
+"<bold><red>  <bold>● </intensity><bold>Error with string cause test</color></intensity>
+
+    boom
+<dim></intensity>
+<dim>      <dim>at f (</intensity><dim>cause.test.js<dim>:15:11)</intensity><dim></intensity>
+<dim>      <dim>at Object.f (</intensity><dim>cause.test.js<dim>:20:5)</intensity><dim></intensity>
+
+    Cause:
+    string cause
+<dim></intensity>
+<dim></intensity>
+"
+`;
+
 exports[`formatStackTrace should strip node internals 1`] = `
 "<bold><red>  <bold>● </intensity><bold>Unix test</color></intensity>
 
@@ -118,12 +158,12 @@ exports[`should return the error cause if there is one 1`] = `
 
     Test exception
 
-      <dim>at Object.<anonymous> (</intensity>packages/jest-message-util/src/__tests__/messages.test.ts<dim>:418:17)</intensity>
+      <dim>at Object.<anonymous> (</intensity>packages/jest-message-util/src/__tests__/messages.test.ts<dim>:566:17)</intensity>
 
     Cause:
      Cause Error
 
-          <dim>at Object.<anonymous> (</intensity>packages/jest-message-util/src/__tests__/messages.test.ts<dim>:421:17)</intensity>
+          <dim>at Object.<anonymous> (</intensity>packages/jest-message-util/src/__tests__/messages.test.ts<dim>:569:17)</intensity>
 
 "
 `;