Support error logging before jest retry

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - `[babel-jest]` Export `createTransformer` function ([#12399](https://github.com/facebook/jest/pull/12399))
 - `[expect]` Expose `AsymmetricMatchers`, `MatcherFunction` and `MatcherFunctionWithState` interfaces ([#12363](https://github.com/facebook/jest/pull/12363), [#12376](https://github.com/facebook/jest/pull/12376))
+- `[jest-circus]` Support error logging before retry` ([#12201](https://github.com/facebook/jest/pull/12201))
 - `[jest-circus, jest-jasmine2]` Allowed classes and functions as `describe` and `it`/`test` names ([#12484](https://github.com/facebook/jest/pull/12484))
 - `[jest-cli, jest-config]` [**BREAKING**] Remove `testURL` config, use `testEnvironmentOptions.url` instead ([#10797](https://github.com/facebook/jest/pull/10797))
 - `[jest-cli, jest-core]` Add `--shard` parameter for distributed parallel test execution ([#12546](https://github.com/facebook/jest/pull/12546))

docs/JestObjectAPI.md

@@ -831,9 +831,9 @@ Example:
 jest.setTimeout(1000); // 1 second
 ```
 
-### `jest.retryTimes()`
+### `jest.retryTimes(numRetries, options)`
 
-Runs failed tests n-times until they pass or until the max number of retries is exhausted. This only works with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner! This must live at the top-level of a test file or in a describe block. Retries _will not_ work if `jest.retryTimes()` is called in a `beforeEach` or a `test` block.
+Runs failed tests n-times until they pass or until the max number of retries is exhausted. `options` are optional. This only works with the default [jest-circus](https://github.com/facebook/jest/tree/main/packages/jest-circus) runner! This must live at the top-level of a test file or in a describe block. Retries _will not_ work if `jest.retryTimes()` is called in a `beforeEach` or a `test` block.
 
 Example in a test:
 
@@ -844,4 +844,13 @@ test('will fail', () => {
 });
 ```
 
+If `logErrorsBeforeRetry` is enabled, Jest will log the error(s) that caused the test to fail to the console, providing visibility on why a retry occurred.
+
+```js
+jest.retryTimes(3, {logErrorsBeforeRetry: true});
+test('will fail', () => {
+  expect(true).toBe(false);
+});
+```
+
 Returns the `jest` object for chaining.

e2e/__tests__/testRetries.test.ts

@@ -19,6 +19,8 @@ describe('Test Retries', () => {
     'e2e/test-retries/',
     outputFileName,
   );
+  const logErrorsBeforeRetryErrorMessage =
+    'Errors that caused Jest to retry test: ';
 
   afterAll(() => {
     fs.unlinkSync(outputFilePath);
@@ -29,6 +31,14 @@ describe('Test Retries', () => {
 
     expect(result.exitCode).toEqual(0);
     expect(result.failed).toBe(false);
+    expect(result.stdout).not.toContain(logErrorsBeforeRetryErrorMessage);
+  });
+
+  it('logs error(s) before retry', () => {
+    const result = runJest('test-retries', ['logErrorsBeforeRetries.test.js']);
+    expect(result.exitCode).toEqual(0);
+    expect(result.failed).toBe(false);
+    expect(result.stdout).toContain(logErrorsBeforeRetryErrorMessage);
   });
 
   it('reporter shows more than 1 invocation if test is retried', () => {

e2e/test-retries/__tests__/logErrorsBeforeRetries.test.js

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates. All Rights Reserved.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+'use strict';
+
+let i = 0;
+jest.retryTimes(3, {logErrorsBeforeRetry: true});
+it('retryTimes set', () => {
+  i++;
+  if (i === 2) {
+    expect(true).toBeTruthy();
+  } else {
+    expect(true).toBeFalsy();
+  }
+});

packages/jest-circus/src/eventHandler.ts

@@ -6,11 +6,12 @@
  */
 
 import type {Circus} from '@jest/types';
+import {serialize} from 'jest-serializer';
 import {
   injectGlobalErrorHandlers,
   restoreGlobalErrorHandlers,
 } from './globalErrorHandlers';
-import {TEST_TIMEOUT_SYMBOL} from './types';
+import {LOG_ERRORS_BEFORE_RETRY, TEST_TIMEOUT_SYMBOL} from './types';
 import {
   addErrorToEachTestUnderDescribe,
   describeBlockHasTests,
@@ -205,6 +206,10 @@ const eventHandler: Circus.EventHandler = (event, state) => {
       break;
     }
     case 'test_retry': {
+      const logErrorsBeforeRetry = global[LOG_ERRORS_BEFORE_RETRY] || false;
+      if (logErrorsBeforeRetry) {
+        event.test.retryReasons.push(serialize(event.test.errors));
+      }
       event.test.errors = [];
       break;
     }

packages/jest-circus/src/legacy-code-todo-rewrite/jestAdapterInit.ts

@@ -220,6 +220,7 @@ export const runAndTransformResultsToJestFormat = async ({
         invocations: testResult.invocations,
         location: testResult.location,
         numPassingAsserts: 0,
+        retryReasons: testResult.retryReasons,
         status,
         title: testResult.testPath[testResult.testPath.length - 1],
       };

packages/jest-circus/src/types.ts

@@ -11,13 +11,17 @@ export const STATE_SYM = Symbol('JEST_STATE_SYMBOL');
 export const RETRY_TIMES = Symbol.for('RETRY_TIMES');
 // To pass this value from Runtime object to state we need to use global[sym]
 export const TEST_TIMEOUT_SYMBOL = Symbol.for('TEST_TIMEOUT_SYMBOL');
+export const LOG_ERRORS_BEFORE_RETRY = Symbol.for(
+  'LOG_ERRORS_BEFORE_RETRY',
+);
 
 declare global {
   namespace NodeJS {
     interface Global {
       [STATE_SYM]: Circus.State;
       [RETRY_TIMES]: string;
       [TEST_TIMEOUT_SYMBOL]: number;
+      [LOG_ERRORS_BEFORE_RETRY]: boolean;
     }
   }
 }

packages/jest-circus/src/utils.ts

@@ -70,6 +70,7 @@ export const makeTest = (
   mode,
   name: convertDescriptorToString(name),
   parent,
+  retryReasons: [],
   seenDone: false,
   startedAt: null,
   status: null,
@@ -354,6 +355,7 @@ export const makeSingleTestResult = (
     errorsDetailed,
     invocations: test.invocations,
     location,
+    retryReasons: test.retryReasons,
     status,
     testPath: Array.from(testPath),
   };
@@ -475,6 +477,7 @@ export const parseSingleTestResult = (
     invocations: testResult.invocations,
     location: testResult.location,
     numPassingAsserts: 0,
+    retryReasons: testResult.retryReasons,
     status,
     title: testResult.testPath[testResult.testPath.length - 1],
   };

packages/jest-environment/src/index.ts

@@ -232,10 +232,18 @@ export interface Jest {
    * Runs failed tests n-times until they pass or until the max number of
    * retries is exhausted.
    *
+   * If `logErrorsBeforeRetry` is enabled, Jest will log the error(s) that caused
+   * the test to fail to the console, providing visibility on why a retry occurred.
+   * retries is exhausted.
+   *
    * @remarks
    * Only available with `jest-circus` runner.
    */
-  retryTimes(numRetries: number): Jest;
+  retryTimes(
+    numRetries: number,
+    options?: {logErrorsBeforeRetry?: boolean},
+  ): Jest;
+
   /**
    * Exhausts tasks queued by `setImmediate()`.
    *

packages/jest-reporters/src/DefaultReporter.ts

@@ -14,6 +14,7 @@ import type {
   TestResult,
 } from '@jest/test-result';
 import type {Config} from '@jest/types';
+import {deserialize, } from 'v8';
 import {clearLine, isInteractive} from 'jest-util';
 import BaseReporter from './BaseReporter';
 import Status from './Status';
@@ -185,6 +186,26 @@ export default class DefaultReporter extends BaseReporter {
     config: Config.ProjectConfig,
     result: TestResult,
   ): void {
+    // log retry errors if any exist
+    result.testResults.forEach(testResult => {
+      const testRetryReasons = testResult.retryReasons;
+      if (testRetryReasons && testRetryReasons.length > 0) {
+        this.log(
+          `${chalk.reset.inverse.bold.yellow(
+            ' LOGGING RETRY ERRORS ',
+          )} ${chalk.bold(testResult.fullName)}\n`,
+        );
+        testRetryReasons.forEach((retryReasons, index) => {
+          this.log(
+            `${chalk.reset.inverse.bold.redBright(` RETRY ${index + 1} `)}\n`,
+          );
+          // eslint-disable-next-line no-console
+          console.log(deserialize(retryReasons));
+          this.log('\n');
+        });
+      }
+    });
+
     this.log(getResultHeader(result, this._globalConfig, config));
     if (result.console) {
       this.log(

packages/jest-runtime/src/index.ts

@@ -119,6 +119,7 @@ type ResolveOptions = Parameters<typeof require.resolve>[1] & {
 
 const testTimeoutSymbol = Symbol.for('TEST_TIMEOUT_SYMBOL');
 const retryTimesSymbol = Symbol.for('RETRY_TIMES');
+const logErrorsBeforeRetrySymbol = Symbol.for('LOG_ERRORS_BEFORE_RETRY');
 
 const NODE_MODULES = `${path.sep}node_modules${path.sep}`;
 
@@ -2117,8 +2118,17 @@ export default class Runtime {
       return jestObject;
     };
 
-    const retryTimes = (numTestRetries: number) => {
+    const retryTimes = (
+      numTestRetries: number,
+      options?: {
+        logErrorsBeforeRetry?: boolean;
+      },
+    ) => {
       this._environment.global[retryTimesSymbol] = numTestRetries;
+      // @ts-expect-error: https://github.com/Microsoft/TypeScript/issues/24587
+      this._environment.global[logErrorsBeforeRetrySymbol] =
+        options?.logErrorsBeforeRetry;
+
       return jestObject;
     };
 

packages/jest-types/__typetests__/jest.test.ts

@@ -117,6 +117,7 @@ expectError(jest.unmock());
 
 // Mock Functions
 
+expectType<typeof jest>(jest.retryTimes(3, {logErrorsBeforeRetry: true}));
 expectType<typeof jest>(jest.clearAllMocks());
 expectError(jest.clearAllMocks('moduleName'));
 

packages/jest-types/src/Circus.ts

@@ -183,6 +183,7 @@ export type TestResult = {
   status: TestStatus;
   location?: {column: number; line: number} | null;
   testPath: Array<TestName | BlockName>;
+  retryReasons: Array<Buffer>;
 };
 
 export type RunResult = {
@@ -234,6 +235,7 @@ export type TestEntry = {
   type: 'test';
   asyncError: Exception; // Used if the test failure contains no usable stack trace
   errors: Array<TestError>;
+  retryReasons: Array<Buffer>;
   fn: TestFn;
   invocations: number;
   mode: TestMode;

packages/jest-types/src/TestResult.ts

@@ -26,6 +26,7 @@ export type AssertionResult = {
   numPassingAsserts: number;
   status: Status;
   title: string;
+  retryReasons?: Array<Buffer>;
 };
 
 export type SerializableError = {

packages/jest-util/src/deepCyclicCopy.ts

@@ -17,7 +17,7 @@ export default function deepCyclicCopy<T>(
   options: DeepCyclicCopyOptions = {blacklist: EMPTY, keepPrototype: false},
   cycles: WeakMap<any, any> = new WeakMap(),
 ): T {
-  if (typeof value !== 'object' || value === null) {
+  if (typeof value !== 'object' || value === null || Buffer.isBuffer(value)) {
     return value;
   } else if (cycles.has(value)) {
     return cycles.get(value);