Support error logging before jest retry

CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ### Features
 
+- `[jest-circus]` Support error logging before retry` ([#12201](https://github.com/facebook/jest/pull/12201))
+
+
 ### Fixes
 
 - `[@jest/transform]` Update dependency package `pirates` to 4.0.4 ([#12136](https://github.com/facebook/jest/pull/12136))

docs/JestObjectAPI.md

@@ -714,9 +714,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!
+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!
 
 Example in a test:
 
@@ -727,4 +727,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,16 @@ describe('Test Retries', () => {
 
     expect(result.exitCode).toEqual(0);
     expect(result.failed).toBe(false);
+    expect(result.stdout.includes(logErrorsBeforeRetryErrorMessage)).toBe(
+      false,
+    );
+  });
+
+  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.includes(logErrorsBeforeRetryErrorMessage)).toBe(true);
   });
 
   it('reporter shows more than 1 invocation if test is retried', () => {
@@ -55,7 +67,6 @@ describe('Test Retries', () => {
         `Can't parse the JSON result from ${outputFileName}, ${err.toString()}`,
       );
     }
-
     expect(jsonResult.numPassedTests).toBe(0);
     expect(jsonResult.numFailedTests).toBe(1);
     expect(jsonResult.numPendingTests).toBe(0);

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/run.ts

@@ -7,7 +7,7 @@
 
 import type {Circus} from '@jest/types';
 import {dispatch, getState} from './state';
-import {RETRY_TIMES} from './types';
+import {LOG_ERRORS_BEFORE_RETRY, RETRY_TIMES} from './types';
 import {
   callAsyncCircusFn,
   getAllHooksForDescribe,
@@ -44,6 +44,7 @@ const _runTestsForDescribeBlock = async (
 
   // Tests that fail and are retried we run after other tests
   const retryTimes = parseInt(global[RETRY_TIMES], 10) || 0;
+  const logErrorsBeforeRetry = global[LOG_ERRORS_BEFORE_RETRY] || false;
   const deferredRetryTests = [];
 
   for (const child of describeBlock.children) {
@@ -73,6 +74,9 @@ const _runTestsForDescribeBlock = async (
     let numRetriesAvailable = retryTimes;
 
     while (numRetriesAvailable > 0 && test.errors.length > 0) {
+      if (logErrorsBeforeRetry) {
+        console.error('Errors that caused Jest to retry test: ', test.errors);
+      }
       // Clear errors so retries occur
       await dispatch({name: 'test_retry', test});
 

packages/jest-circus/src/types.ts

@@ -19,13 +19,16 @@ export const RETRY_TIMES = Symbol.for(
 export const TEST_TIMEOUT_SYMBOL = Symbol.for(
   'TEST_TIMEOUT_SYMBOL',
 ) as unknown as 'TEST_TIMEOUT_SYMBOL';
-
+export const LOG_ERRORS_BEFORE_RETRY = Symbol.for(
+  'LOG_ERRORS_BEFORE_RETRY',
+) as unknown as 'LOG_ERRORS_BEFORE_RETRY';
 declare global {
   namespace NodeJS {
     interface Global {
       STATE_SYM_SYMBOL: Circus.State;
       RETRY_TIMES_SYMBOL: string;
       TEST_TIMEOUT_SYMBOL: number;
+      LOG_ERRORS_BEFORE_RETRY: boolean;
       expect: typeof expect;
     }
   }

packages/jest-environment/src/index.ts

@@ -193,11 +193,19 @@ export interface Jest {
    */
   restoreAllMocks(): Jest;
   mocked: typeof JestMockMocked;
+
   /**
    * Runs failed tests n-times until they pass or until the max number of
    * retries is exhausted. This only works with `jest-circus`!
+   *
+   * 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.
    */
-  retryTimes(numRetries: number): Jest;
+  retryTimes(
+    numRetries: number,
+    options?: {logErrorsBeforeRetry?: boolean},
+  ): Jest;
+
   /**
    * Exhausts tasks queued by setImmediate().
    *

packages/jest-runtime/src/index.ts

@@ -114,6 +114,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;
 
@@ -1936,9 +1937,18 @@ export default class Runtime {
       return jestObject;
     };
 
-    const retryTimes = (numTestRetries: number) => {
+    const retryTimes = (
+      numTestRetries: number,
+      options?: {
+        logErrorsBeforeRetry?: boolean;
+      },
+    ) => {
       // @ts-expect-error: https://github.com/Microsoft/TypeScript/issues/24587
       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/__typechecks__/jest.test.ts

@@ -33,6 +33,7 @@ expectType<typeof jest>(jest.mock('moduleName', jest.fn(), {virtual: true}));
 expectType<typeof jest>(jest.resetModules());
 expectType<typeof jest>(jest.isolateModules(() => {}));
 expectType<typeof jest>(jest.retryTimes(3));
+expectType<typeof jest>(jest.retryTimes(3, {logErrorsBeforeRetry: true}));
 expectType<Mock<Promise<string>, []>>(
   jest
     .fn(() => Promise.resolve('string value'))