Rename some options before releasing Jest 30.

cpojer · cpojer · commit 8a58fde2cccd · 2025-06-10T09:46:31.000+09:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[*]` Renamed `globalsCleanupMode` to `globalsCleanup` and `--waitNextEventLoopTurnForUnhandledRejectionEvents` to `--waitForUnhandledRejections`
 - `[expect]` Add `ArrayOf` asymmetric matcher for validating array elements. ([#15567](https://github.com/jestjs/jest/pull/15567))
 - `[babel-jest]` Add option `excludeJestPreset` to allow opting out of `babel-preset-jest` ([#15164](https://github.com/jestjs/jest/pull/15164))
 - `[expect]` Revert [#15038](https://github.com/jestjs/jest/pull/15038) to fix `expect(fn).toHaveBeenCalledWith(expect.objectContaining(...))` when there are multiple calls ([#15508](https://github.com/jestjs/jest/pull/15508))
diff --git a/docs/CLI.md b/docs/CLI.md
@@ -524,7 +524,7 @@ Display individual test results with the test suite hierarchy.
 
 Alias: `-v`. Print the version and exit.
 
-### `--waitNextEventLoopTurnForUnhandledRejectionEvents`
+### `--waitForUnhandledRejections`
 
 Gives one event loop turn to handle `rejectionHandled`, `uncaughtException` or `unhandledRejection`.
 
diff --git a/docs/Configuration.md b/docs/Configuration.md
@@ -2413,7 +2413,7 @@ Default: `false` or `true` if there is only one test file to run
 
 Indicates whether each individual test should be reported during the run. All errors will also still be shown on the bottom after execution.
 
-### `waitNextEventLoopTurnForUnhandledRejectionEvents` \[boolean]
+### `waitForUnhandledRejections` \[boolean]
 
 Gives one event loop turn to handle `rejectionHandled`, `uncaughtException` or `unhandledRejection`.
 
diff --git a/docs/UpgradingToJest30.md b/docs/UpgradingToJest30.md
@@ -116,7 +116,7 @@ Jest includes a fix to properly handle promises that are rejected and later caug
 
 :::info
 
-You should see fewer false positives for unhandled promise rejections. Tests that previously failed due to async handled rejections should now pass. However, this change can slightly slow down test completion, especially in tests that intentionally reject promises. To mitigate performance impact, a new configuration flag `waitNextEventLoopTurnForUnhandledRejectionEvents` was introduced. This flag, when disabled, can restore the previous behavior (not waiting) if absolutely needed. Most users should not need to change this – the default now favors correctness by preventing false failures.
+You should see fewer false positives for unhandled promise rejections. Tests that previously failed due to async handled rejections should now pass. However, this change can slightly slow down test completion, especially in tests that intentionally reject promises. To mitigate performance impact, a new configuration flag `waitForUnhandledRejections` was introduced. This flag, when disabled, can restore the previous behavior (not waiting) if absolutely needed. Most users should not need to change this – the default now favors correctness by preventing false failures.
 
 :::
 
diff --git a/e2e/__tests__/__snapshots__/environmentAfterTeardown.test.ts.snap b/e2e/__tests__/__snapshots__/environmentAfterTeardown.test.ts.snap
@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
-exports[`prints useful error for environment methods after test is done w/ \`waitNextEventLoopTurnForUnhandledRejectionEvents\` 1`] = `
+exports[`prints useful error for environment methods after test is done w/ \`waitForUnhandledRejections\` 1`] = `
 "    ReferenceError: You are trying to access a property or method of the Jest environment outside of the scope of the test code.
 
        9 | test('access environment methods after done', () => {
@@ -12,7 +12,7 @@ exports[`prints useful error for environment methods after test is done w/ \`wai
       14 |"
 `;
 
-exports[`prints useful error for environment methods after test is done w/o \`waitNextEventLoopTurnForUnhandledRejectionEvents\` 1`] = `
+exports[`prints useful error for environment methods after test is done w/o \`waitForUnhandledRejections\` 1`] = `
 "ReferenceError: You are trying to access a property or method of the Jest environment after it has been torn down. From __tests__/afterTeardown.test.js.
 
        9 | test('access environment methods after done', () => {
diff --git a/e2e/__tests__/__snapshots__/requireAfterTeardown.test.ts.snap b/e2e/__tests__/__snapshots__/requireAfterTeardown.test.ts.snap
@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
-exports[`prints useful error for requires after test is done w/ \`waitNextEventLoopTurnForUnhandledRejectionEvents\` 1`] = `
+exports[`prints useful error for requires after test is done w/ \`waitForUnhandledRejections\` 1`] = `
 "    ReferenceError: You are trying to \`import\` a file outside of the scope of the test code.
 
        9 | test('require after done', () => {
@@ -12,7 +12,7 @@ exports[`prints useful error for requires after test is done w/ \`waitNextEventL
       14 |   }, 0);"
 `;
 
-exports[`prints useful error for requires after test is done w/o \`waitNextEventLoopTurnForUnhandledRejectionEvents\` 1`] = `
+exports[`prints useful error for requires after test is done w/o \`waitForUnhandledRejections\` 1`] = `
 "ReferenceError: You are trying to \`import\` a file after the Jest environment has been torn down. From __tests__/lateRequire.test.js.
 
        9 | test('require after done', () => {
diff --git a/e2e/__tests__/__snapshots__/showConfig.test.ts.snap b/e2e/__tests__/__snapshots__/showConfig.test.ts.snap
@@ -97,7 +97,7 @@ exports[`--showConfig outputs config info and exits 1`] = `
         "/node_modules/",
         "<<REPLACED_PNP_PATH>>"
       ],
-      "waitNextEventLoopTurnForUnhandledRejectionEvents": false,
+      "waitForUnhandledRejections": false,
       "watchPathIgnorePatterns": []
     }
   ],
@@ -150,7 +150,7 @@ exports[`--showConfig outputs config info and exits 1`] = `
     "testSequencer": "<<REPLACED_JEST_PACKAGES_DIR>>/jest-test-sequencer/build/index.js",
     "updateSnapshot": "none",
     "useStderr": false,
-    "waitNextEventLoopTurnForUnhandledRejectionEvents": false,
+    "waitForUnhandledRejections": false,
     "watch": false,
     "watchAll": false,
     "watchman": true,
diff --git a/e2e/__tests__/environmentAfterTeardown.test.ts b/e2e/__tests__/environmentAfterTeardown.test.ts
@@ -10,7 +10,7 @@ import runJest from '../runJest';
 
 skipSuiteOnJasmine();
 
-test('prints useful error for environment methods after test is done w/o `waitNextEventLoopTurnForUnhandledRejectionEvents`', () => {
+test('prints useful error for environment methods after test is done w/o `waitForUnhandledRejections`', () => {
   const {stderr} = runJest('environment-after-teardown');
   const interestingLines = stderr.split('\n').slice(9, 18).join('\n');
 
@@ -20,9 +20,9 @@ test('prints useful error for environment methods after test is done w/o `waitNe
   );
 });
 
-test('prints useful error for environment methods after test is done w/ `waitNextEventLoopTurnForUnhandledRejectionEvents`', () => {
+test('prints useful error for environment methods after test is done w/ `waitForUnhandledRejections`', () => {
   const {stderr} = runJest('environment-after-teardown', [
-    '--waitNextEventLoopTurnForUnhandledRejectionEvents',
+    '--waitForUnhandledRejections',
   ]);
   const interestingLines = stderr.split('\n').slice(5, 14).join('\n');
 
diff --git a/e2e/__tests__/environmentAfterTeardownJasmine.test.ts b/e2e/__tests__/environmentAfterTeardownJasmine.test.ts
@@ -13,7 +13,7 @@ skipSuiteOnJestCircus();
 test.each`
   jestArgs
   ${[]}
-  ${['--waitNextEventLoopTurnForUnhandledRejectionEvents']}
+  ${['--waitForUnhandledRejections']}
 `(
   'prints useful error for environment methods after test is done',
   ({jestArgs}) => {
diff --git a/e2e/__tests__/fakeTimersLegacy.test.ts b/e2e/__tests__/fakeTimersLegacy.test.ts
@@ -39,19 +39,19 @@ describe('requestAnimationFrame', () => {
 });
 
 describe('setImmediate', () => {
-  test('fakes setImmediate w/o `waitNextEventLoopTurnForUnhandledRejectionEvents`', () => {
+  test('fakes setImmediate w/o `waitForUnhandledRejections`', () => {
     const result = runJest('fake-timers-legacy/set-immediate');
 
     expect(result.stderr).toMatch('setImmediate test');
     expect(result.exitCode).toBe(0);
   });
 
-  test('fakes setImmediate w/ `waitNextEventLoopTurnForUnhandledRejectionEvents`', () => {
+  test('fakes setImmediate w/ `waitForUnhandledRejections`', () => {
     // Jasmine runner does not handle unhandled promise rejections that are causing the test to fail in Jest circus
     const expectedExitCode = isJestJasmineRun() ? 0 : 1;
 
     const result = runJest('fake-timers-legacy/set-immediate', [
-      '--waitNextEventLoopTurnForUnhandledRejectionEvents',
+      '--waitForUnhandledRejections',
     ]);
 
     expect(result.stderr).toMatch('setImmediate test');
diff --git a/e2e/__tests__/requireAfterTeardown.test.ts b/e2e/__tests__/requireAfterTeardown.test.ts
@@ -10,7 +10,7 @@ import runJest from '../runJest';
 
 skipSuiteOnJasmine();
 
-test('prints useful error for requires after test is done w/o `waitNextEventLoopTurnForUnhandledRejectionEvents`', () => {
+test('prints useful error for requires after test is done w/o `waitForUnhandledRejections`', () => {
   const {stderr} = runJest('require-after-teardown');
 
   const interestingLines = stderr.split('\n').slice(9, 18).join('\n');
@@ -21,9 +21,9 @@ test('prints useful error for requires after test is done w/o `waitNextEventLoop
   );
 });
 
-test('prints useful error for requires after test is done w/ `waitNextEventLoopTurnForUnhandledRejectionEvents`', () => {
+test('prints useful error for requires after test is done w/ `waitForUnhandledRejections`', () => {
   const {stderr} = runJest('require-after-teardown', [
-    '--waitNextEventLoopTurnForUnhandledRejectionEvents',
+    '--waitForUnhandledRejections',
   ]);
 
   const interestingLines = stderr.split('\n').slice(5, 14).join('\n');
diff --git a/e2e/__tests__/requireAfterTeardownJasmine.test.ts b/e2e/__tests__/requireAfterTeardownJasmine.test.ts
@@ -13,7 +13,7 @@ skipSuiteOnJestCircus();
 test.each`
   jestArgs
   ${[]}
-  ${['--waitNextEventLoopTurnForUnhandledRejectionEvents']}
+  ${['--waitForUnhandledRejections']}
 `('prints useful error for requires after test is done', ({jestArgs}) => {
   const {stderr} = runJest('require-after-teardown', jestArgs);
 
diff --git a/e2e/console-debugging/jest.config.js b/e2e/console-debugging/jest.config.js
@@ -11,7 +11,7 @@ require('./stdout-spy');
 module.exports = {
   testEnvironment: 'node',
   testEnvironmentOptions: {
-    globalsCleanupMode: 'hard',
+    globalsCleanup: 'on',
   },
   verbose: true,
 };
diff --git a/e2e/esm-config/cjs/jest.config.cjs b/e2e/esm-config/cjs/jest.config.cjs
@@ -9,6 +9,6 @@ module.exports = {
   displayName: 'Config from cjs file',
   testEnvironment: 'node',
   testEnvironmentOptions: {
-    globalsCleanupMode: 'hard',
+    globalsCleanup: 'on',
   },
 };
diff --git a/e2e/esm-config/js/jest.config.js b/e2e/esm-config/js/jest.config.js
@@ -11,6 +11,6 @@ export default {
   displayName,
   testEnvironment: 'node',
   testEnvironmentOptions: {
-    globalsCleanupMode: 'hard',
+    globalsCleanup: 'on',
   },
 };
diff --git a/e2e/esm-config/mjs/jest.config.mjs b/e2e/esm-config/mjs/jest.config.mjs
@@ -11,6 +11,6 @@ export default {
   displayName,
   testEnvironment: 'node',
   testEnvironmentOptions: {
-    globalsCleanupMode: 'hard',
+    globalsCleanup: 'on',
   },
 };
diff --git a/e2e/esm-config/ts/jest.config.ts b/e2e/esm-config/ts/jest.config.ts
@@ -11,15 +11,15 @@ type DummyConfig = {
   displayName: string;
   testEnvironment: string;
   testEnvironmentOptions?: {
-    globalsCleanupMode: 'hard' | 'soft' | 'off';
+    globalsCleanup: 'on' | 'soft' | 'off';
   };
 };
 
 const config: DummyConfig = {
   displayName: 'Config from ts file',
   testEnvironment: 'node',
   testEnvironmentOptions: {
-    globalsCleanupMode: 'hard',
+    globalsCleanup: 'on',
   },
 };
 
diff --git a/e2e/promise-async-handling/package.json b/e2e/promise-async-handling/package.json
@@ -1,6 +1,6 @@
 {
   "jest": {
     "testEnvironment": "node",
-    "waitNextEventLoopTurnForUnhandledRejectionEvents": true
+    "waitForUnhandledRejections": true
   }
 }
diff --git a/e2e/typescript-config/modern-module-resolution/jest.config.ts b/e2e/typescript-config/modern-module-resolution/jest.config.ts
@@ -9,7 +9,7 @@ const config = {
   displayName: 'Config from modern ts file',
   testEnvironment: 'node',
   testEnvironmentOptions: {
-    globalsCleanupMode: 'hard',
+    globalsCleanup: 'on',
   },
 };
 export default config;
diff --git a/examples/react-native/jest.config.js b/examples/react-native/jest.config.js
@@ -3,7 +3,7 @@ const {resolve} = require('path');
 module.exports = {
   preset: 'react-native',
   testEnvironmentOptions: {
-    globalsCleanupMode: 'soft',
+    globalsCleanup: 'soft',
   },
   // this is specific to the Jest repo, not generally needed (the files we ignore will be in node_modules which is ignored by default)
   transformIgnorePatterns: [resolve(__dirname, '../../packages')],
diff --git a/jest.config.mjs b/jest.config.mjs
@@ -38,7 +38,7 @@ export default {
   },
   snapshotSerializers: [require.resolve('jest-serializer-ansi-escapes')],
   testEnvironmentOptions: {
-    globalsCleanupMode: 'hard',
+    globalsCleanup: 'on',
   },
   testPathIgnorePatterns: [
     '/__arbitraries__/',
diff --git a/packages/jest-circus/src/legacy-code-todo-rewrite/jestAdapterInit.ts b/packages/jest-circus/src/legacy-code-todo-rewrite/jestAdapterInit.ts
@@ -133,10 +133,7 @@ export const initialize = async ({
   }
 
   addEventHandler(
-    unhandledRejectionHandler(
-      runtime,
-      globalConfig.waitNextEventLoopTurnForUnhandledRejectionEvents,
-    ),
+    unhandledRejectionHandler(runtime, globalConfig.waitForUnhandledRejections),
   );
 
   // Return it back to the outer scope (test runner outside the VM).
diff --git a/packages/jest-circus/src/unhandledRejectionHandler.ts b/packages/jest-circus/src/unhandledRejectionHandler.ts
@@ -22,15 +22,15 @@ const untilNextEventLoopTurn = async () => {
 
 export const unhandledRejectionHandler = (
   runtime: Runtime,
-  waitNextEventLoopTurnForUnhandledRejectionEvents: boolean,
+  waitForUnhandledRejections: boolean,
 ): Circus.EventHandler => {
   return async (event, state) => {
     if (event.name === 'hook_start') {
       runtime.enterTestCode();
     } else if (event.name === 'hook_success' || event.name === 'hook_failure') {
       runtime.leaveTestCode();
 
-      if (waitNextEventLoopTurnForUnhandledRejectionEvents) {
+      if (waitForUnhandledRejections) {
         // We need to give event loop the time to actually execute `rejectionHandled`, `uncaughtException` or `unhandledRejection` events
         await untilNextEventLoopTurn();
       }
@@ -63,7 +63,7 @@ export const unhandledRejectionHandler = (
     ) {
       runtime.leaveTestCode();
 
-      if (waitNextEventLoopTurnForUnhandledRejectionEvents) {
+      if (waitForUnhandledRejections) {
         // We need to give event loop the time to actually execute `rejectionHandled`, `uncaughtException` or `unhandledRejection` events
         await untilNextEventLoopTurn();
       }
@@ -75,7 +75,7 @@ export const unhandledRejectionHandler = (
         test.errors.push([error, event.test.asyncError]);
       }
     } else if (event.name === 'teardown') {
-      if (waitNextEventLoopTurnForUnhandledRejectionEvents) {
+      if (waitForUnhandledRejections) {
         // We need to give event loop the time to actually execute `rejectionHandled`, `uncaughtException` or `unhandledRejection` events
         await untilNextEventLoopTurn();
       }
diff --git a/packages/jest-cli/src/args.ts b/packages/jest-cli/src/args.ts
@@ -739,7 +739,7 @@ export const options: {[key: string]: Options} = {
       'Display individual test results with the test suite hierarchy.',
     type: 'boolean',
   },
-  waitNextEventLoopTurnForUnhandledRejectionEvents: {
+  waitForUnhandledRejections: {
     description:
       'Gives one event loop turn to handle `rejectionHandled`, ' +
       '`uncaughtException` or `unhandledRejection`.',
diff --git a/packages/jest-config/src/Defaults.ts b/packages/jest-config/src/Defaults.ts
@@ -91,7 +91,7 @@ const defaultOptions: Config.DefaultOptions = {
   testSequencer: '@jest/test-sequencer',
   transformIgnorePatterns: [NODE_MODULES_REGEXP, `\\.pnp\\.[^\\${sep}]+$`],
   useStderr: false,
-  waitNextEventLoopTurnForUnhandledRejectionEvents: false,
+  waitForUnhandledRejections: false,
   watch: false,
   watchPathIgnorePatterns: [],
   watchman: true,
diff --git a/packages/jest-config/src/ValidConfig.ts b/packages/jest-config/src/ValidConfig.ts
@@ -181,7 +181,7 @@ export const initialOptions: Config.InitialOptions = {
   updateSnapshot: true,
   useStderr: false,
   verbose: false,
-  waitNextEventLoopTurnForUnhandledRejectionEvents: false,
+  waitForUnhandledRejections: false,
   watch: false,
   watchAll: false,
   watchPathIgnorePatterns: ['<rootDir>/e2e/'],
@@ -328,7 +328,7 @@ export const initialProjectOptions: Config.InitialProjectOptions = {
   },
   transformIgnorePatterns: [NODE_MODULES_REGEXP],
   unmockedModulePathPatterns: ['mock'],
-  waitNextEventLoopTurnForUnhandledRejectionEvents: false,
+  waitForUnhandledRejections: false,
   watchPathIgnorePatterns: ['<rootDir>/e2e/'],
   workerIdleMemoryLimit: multipleValidOptions(0.2, '50%'),
 };
diff --git a/packages/jest-config/src/index.ts b/packages/jest-config/src/index.ts
@@ -138,8 +138,7 @@ const groupOptions = (
     updateSnapshot: options.updateSnapshot,
     useStderr: options.useStderr,
     verbose: options.verbose,
-    waitNextEventLoopTurnForUnhandledRejectionEvents:
-      options.waitNextEventLoopTurnForUnhandledRejectionEvents,
+    waitForUnhandledRejections: options.waitForUnhandledRejections,
     watch: options.watch,
     watchAll: options.watchAll,
     watchPlugins: options.watchPlugins,
@@ -208,8 +207,7 @@ const groupOptions = (
     transform: options.transform,
     transformIgnorePatterns: options.transformIgnorePatterns,
     unmockedModulePathPatterns: options.unmockedModulePathPatterns,
-    waitNextEventLoopTurnForUnhandledRejectionEvents:
-      options.waitNextEventLoopTurnForUnhandledRejectionEvents,
+    waitForUnhandledRejections: options.waitForUnhandledRejections,
     watchPathIgnorePatterns: options.watchPathIgnorePatterns,
   }),
 });
diff --git a/packages/jest-config/src/normalize.ts b/packages/jest-config/src/normalize.ts
@@ -936,7 +936,7 @@ export default async function normalize(
       case 'testNamePattern':
       case 'useStderr':
       case 'verbose':
-      case 'waitNextEventLoopTurnForUnhandledRejectionEvents':
+      case 'waitForUnhandledRejections':
       case 'watch':
       case 'watchAll':
       case 'watchman':
diff --git a/packages/jest-core/src/lib/__tests__/__snapshots__/logDebugMessages.test.ts.snap b/packages/jest-core/src/lib/__tests__/__snapshots__/logDebugMessages.test.ts.snap
@@ -75,7 +75,7 @@ exports[`prints the config object 1`] = `
     "testTimeout": 5000,
     "transform": [],
     "transformIgnorePatterns": [],
-    "waitNextEventLoopTurnForUnhandledRejectionEvents": false,
+    "waitForUnhandledRejections": false,
     "watchPathIgnorePatterns": []
   },
   "globalConfig": {
@@ -128,7 +128,7 @@ exports[`prints the config object 1`] = `
     "updateSnapshot": "none",
     "useStderr": false,
     "verbose": false,
-    "waitNextEventLoopTurnForUnhandledRejectionEvents": false,
+    "waitForUnhandledRejections": false,
     "watch": true,
     "watchAll": false,
     "watchPlugins": [],
diff --git a/packages/jest-environment-node/src/index.ts b/packages/jest-environment-node/src/index.ts
diff --git a/packages/jest-schemas/src/raw-types.ts b/packages/jest-schemas/src/raw-types.ts
diff --git a/packages/jest-transform/src/__tests__/__snapshots__/ScriptTransformer.test.ts.snap b/packages/jest-transform/src/__tests__/__snapshots__/ScriptTransformer.test.ts.snap
diff --git a/packages/jest-types/src/Config.ts b/packages/jest-types/src/Config.ts
diff --git a/packages/jest-util/src/garbage-collection-utils.ts b/packages/jest-util/src/garbage-collection-utils.ts
diff --git a/packages/test-utils/src/config.ts b/packages/test-utils/src/config.ts
