#15638 Change default behavior of 'node' test environment to 'soft' delete globals at teardown

eyalroth · eyalroth · commit 3a0afa05f2e9 · 2025-06-03T18:57:06.000+03:00
This commit adds three configurable options to the globals cleanup at teardown:
 - 'off': no cleanup whatsoever
 - 'soft': "deleted" properties will emit a deprecation warning if accessed
 - 'hard': actually delete the properties

The default behavior is 'soft'.
diff --git a/e2e/console-debugging/jest.config.js b/e2e/console-debugging/jest.config.js
@@ -10,5 +10,8 @@ require('./stdout-spy');
 
 module.exports = {
   testEnvironment: 'node',
+  testEnvironmentOptions: {
+    globalsCleanupMode: 'hard',
+  },
   verbose: true,
 };
diff --git a/e2e/esm-config/cjs/jest.config.cjs b/e2e/esm-config/cjs/jest.config.cjs
@@ -8,4 +8,7 @@
 module.exports = {
   displayName: 'Config from cjs file',
   testEnvironment: 'node',
+  testEnvironmentOptions: {
+    globalsCleanupMode: 'hard',
+  },
 };
diff --git a/e2e/esm-config/js/jest.config.js b/e2e/esm-config/js/jest.config.js
@@ -10,4 +10,7 @@ const displayName = await Promise.resolve('Config from js file');
 export default {
   displayName,
   testEnvironment: 'node',
+  testEnvironmentOptions: {
+    globalsCleanupMode: 'hard',
+  },
 };
diff --git a/e2e/esm-config/mjs/jest.config.mjs b/e2e/esm-config/mjs/jest.config.mjs
@@ -10,4 +10,7 @@ const displayName = await Promise.resolve('Config from mjs file');
 export default {
   displayName,
   testEnvironment: 'node',
+  testEnvironmentOptions: {
+    globalsCleanupMode: 'hard',
+  },
 };
diff --git a/e2e/esm-config/ts/jest.config.ts b/e2e/esm-config/ts/jest.config.ts
@@ -10,11 +10,17 @@
 type DummyConfig = {
   displayName: string;
   testEnvironment: string;
+  testEnvironmentOptions?: {
+    globalsCleanupMode: 'hard' | 'soft' | 'off';
+  };
 };
 
 const config: DummyConfig = {
   displayName: 'Config from ts file',
   testEnvironment: 'node',
+  testEnvironmentOptions: {
+    globalsCleanupMode: 'hard',
+  },
 };
 
 export default () => config;
diff --git a/e2e/typescript-config/modern-module-resolution/jest.config.ts b/e2e/typescript-config/modern-module-resolution/jest.config.ts
@@ -8,5 +8,8 @@
 const config = {
   displayName: 'Config from modern ts file',
   testEnvironment: 'node',
+  testEnvironmentOptions: {
+    globalsCleanupMode: 'hard',
+  },
 };
 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: {
-    disableGlobalsCleanup: 'true',
+    globalsCleanupMode: '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
@@ -37,6 +37,9 @@ export default {
     printBasicPrototype: true,
   },
   snapshotSerializers: [require.resolve('jest-serializer-ansi-escapes')],
+  testEnvironmentOptions: {
+    globalsCleanupMode: 'hard',
+  },
   testPathIgnorePatterns: [
     '/__arbitraries__/',
     '/__benchmarks__/',
diff --git a/packages/jest-environment-node/package.json b/packages/jest-environment-node/package.json
@@ -24,7 +24,8 @@
     "@jest/types": "workspace:*",
     "@types/node": "*",
     "jest-mock": "workspace:*",
-    "jest-util": "workspace:*"
+    "jest-util": "workspace:*",
+    "jest-validate": "workspace:*"
   },
   "devDependencies": {
     "@jest/test-utils": "workspace:*",
diff --git a/packages/jest-environment-node/src/index.ts b/packages/jest-environment-node/src/index.ts
@@ -15,11 +15,13 @@ import {LegacyFakeTimers, ModernFakeTimers} from '@jest/fake-timers';
 import type {Global} from '@jest/types';
 import {ModuleMocker} from 'jest-mock';
 import {
+  type DeletionMode,
   canDeleteProperties,
   deleteProperties,
   installCommonGlobals,
   protectProperties,
 } from 'jest-util';
+import {logValidationWarning} from 'jest-validate';
 
 type Timer = {
   id: number;
@@ -86,7 +88,7 @@ export default class NodeEnvironment implements JestEnvironment<Timer> {
   customExportConditions = ['node', 'node-addons'];
   private readonly _configuredExportConditions?: Array<string>;
   private _globalProxy: GlobalProxy;
-  private _clearGlobalsAtShutdown: boolean;
+  private _globalsCleanupMode: 'off' | DeletionMode;
 
   // while `context` is unused, it should always be passed
   constructor(config: JestEnvironmentConfig, _context: EnvironmentContext) {
@@ -204,9 +206,27 @@ export default class NodeEnvironment implements JestEnvironment<Timer> {
     });
 
     this._globalProxy.envSetupCompleted();
-    this._clearGlobalsAtShutdown = ![true, 'true'].includes(
-      projectConfig.testEnvironmentOptions['disableGlobalsCleanup'] as any,
-    );
+    this._globalsCleanupMode = (() => {
+      const rawConfig =
+        projectConfig.testEnvironmentOptions['globalsCleanupMode'];
+      const config = rawConfig?.toString()?.toLowerCase();
+      switch (config) {
+        case 'hard':
+        case 'soft':
+        case 'off':
+          return config;
+        default: {
+          if (config !== undefined) {
+            logValidationWarning(
+              'testEnvironmentOptions.globalsCleanupMode',
+              `Unknown value given: ${rawConfig}`,
+              'Available options are: [hard, soft, off]',
+            );
+          }
+          return 'soft';
+        }
+      }
+    })();
   }
 
   // eslint-disable-next-line @typescript-eslint/no-empty-function
@@ -222,8 +242,8 @@ export default class NodeEnvironment implements JestEnvironment<Timer> {
     this.context = null;
     this.fakeTimers = null;
     this.fakeTimersModern = null;
-    if (this._clearGlobalsAtShutdown) {
-      this._globalProxy.clear();
+    if (this._globalsCleanupMode !== 'off') {
+      this._globalProxy.clear(this._globalsCleanupMode);
     }
   }
 
@@ -274,16 +294,18 @@ class GlobalProxy implements ProxyHandler<typeof globalThis> {
    * Deletes any property that was set on the global object, except for:
    * 1. Properties that were set before {@link #envSetupCompleted} was invoked.
    * 2. Properties protected by {@link #protectProperties}.
+   *
+   * @param mode determines whether to soft or hard delete the properties.
    */
-  clear(): void {
+  clear(mode: DeletionMode): void {
     for (const {value} of [
       ...[...this.propertyToValue.entries()].map(([property, value]) => ({
         property,
         value,
       })),
       ...this.leftovers,
     ]) {
-      deleteProperties(value);
+      deleteProperties(value, mode);
     }
     this.propertyToValue.clear();
     this.leftovers = [];
diff --git a/packages/jest-environment-node/tsconfig.json b/packages/jest-environment-node/tsconfig.json
@@ -12,6 +12,7 @@
     {"path": "../jest-fake-timers"},
     {"path": "../jest-mock"},
     {"path": "../jest-types"},
-    {"path": "../jest-util"}
+    {"path": "../jest-util"},
+    {"path": "../jest-validate"}
   ]
 }
diff --git a/packages/jest-util/src/garbage-collection-utils.ts b/packages/jest-util/src/garbage-collection-utils.ts
@@ -7,21 +7,24 @@
 
 const PROTECT_SYMBOL = Symbol.for('$$jest-protect-from-deletion');
 
+export type DeletionMode = 'soft' | 'hard';
+
 /**
  * Deletes all the properties from the given value (if it's an object),
  * unless the value was protected via {@link #protectProperties}.
  *
  * @param value the given value.
+ * @param mode the deletion mode (see {@link #deleteProperty}).
  */
-export function deleteProperties(value: unknown): void {
+export function deleteProperties(value: unknown, mode: DeletionMode): void {
   if (canDeleteProperties(value)) {
     const protectedKeys = getProtectedKeys(
       value,
       Reflect.get(value, PROTECT_SYMBOL),
     );
     for (const key of Reflect.ownKeys(value)) {
       if (!protectedKeys.includes(key) && key !== PROTECT_SYMBOL) {
-        Reflect.deleteProperty(value, key);
+        deleteProperty(value, key, mode);
       }
     }
   }
@@ -43,31 +46,34 @@ export function protectProperties<T>(
   properties: Array<keyof T> = [],
   depth = 2,
 ): boolean {
-  if (
-    depth >= 0 &&
-    canDeleteProperties(value) &&
-    !Reflect.has(value, PROTECT_SYMBOL)
-  ) {
-    const result = Reflect.set(value, PROTECT_SYMBOL, properties);
-    for (const key of getProtectedKeys(value, properties)) {
-      const originalEmitWarning = process.emitWarning;
-      try {
-        // Reflect.get may cause deprecation warnings, so we disable them temporarily
-        // eslint-disable-next-line @typescript-eslint/no-empty-function
-        process.emitWarning = () => {};
-
-        const nested = Reflect.get(value, key);
-        protectProperties(nested, [], depth - 1);
-      } catch {
-        // Reflect.get might fail in certain edge-cases
-        // Instead of failing the entire process, we will skip the property.
-      } finally {
-        process.emitWarning = originalEmitWarning;
+  // Reflect.get may cause deprecation warnings, so we disable them temporarily
+
+  const originalEmitWarning = process.emitWarning;
+
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    process.emitWarning = () => {};
+    if (
+      depth >= 0 &&
+      canDeleteProperties(value) &&
+      !Reflect.has(value, PROTECT_SYMBOL)
+    ) {
+      const result = Reflect.set(value, PROTECT_SYMBOL, properties);
+      for (const key of getProtectedKeys(value, properties)) {
+        try {
+          const nested = Reflect.get(value, key);
+          protectProperties(nested, [], depth - 1);
+        } catch {
+          // Reflect.get might fail in certain edge-cases
+          // Instead of failing the entire process, we will skip the property.
+        }
       }
+      return result;
     }
-    return result;
+    return false;
+  } finally {
+    process.emitWarning = originalEmitWarning;
   }
-  return false;
 }
 
 /**
@@ -84,6 +90,77 @@ export function canDeleteProperties(value: unknown): value is object {
   return false;
 }
 
+/**
+ * Deletes the property of the given key from the given object.
+ *
+ * @param obj the given object.
+ * @param key the given key.
+ * @param mode there are two possible modes of deletion:
+ *  - <b>soft</b>: doesn't delete the object, but instead wraps its getter/setter with a deprecation warning.
+ *  - <b>hard</b>: actually deletes the object (`delete`).
+ *
+ * @returns whether the deletion was successful or not.
+ */
+function deleteProperty(
+  obj: object,
+  key: string | symbol,
+  mode: DeletionMode,
+): boolean {
+  const descriptor = Reflect.getOwnPropertyDescriptor(obj, key);
+  if (!descriptor?.configurable) {
+    return false;
+  }
+
+  if (mode === 'hard') {
+    return Reflect.deleteProperty(obj, key);
+  }
+
+  const originalGetter = descriptor.get ?? (() => descriptor.value);
+  const originalSetter =
+    descriptor.set ?? (value => Reflect.set(obj, key, value));
+
+  return Reflect.defineProperty(obj, key, {
+    configurable: true,
+    enumerable: descriptor.enumerable,
+    get() {
+      emitAccessWarning(obj, key);
+      return originalGetter();
+    },
+    set(value) {
+      emitAccessWarning(obj, key);
+      return originalSetter(value);
+    },
+  });
+}
+
+const warningCache = new WeakSet<object>();
+
+function emitAccessWarning(obj: object, key: string | symbol): void {
+  if (warningCache.has(obj)) {
+    return;
+  }
+  const objName = obj?.constructor?.name
+    ? `[class ${obj.constructor.name}]`
+    : obj.toString();
+  const propertyName = typeof key === 'symbol' ? key.description : key;
+
+  process.emitWarning(
+    `'${propertyName}' property was accessed on ${objName} after it was soft deleted`,
+    {
+      code: 'JEST-01',
+      detail: [
+        'Jest "soft" deletes objects that were set on the global scope between test files.',
+        'This warning is emitted if those objects were accessed after their soft deletion.',
+        'In future versions of Jest, the default behavior will change to hard (actual) delete, which will likely fail tests.',
+      ]
+        .map(s => `  ${s}`)
+        .join('\n'),
+      type: 'DeprecationWarning',
+    },
+  );
+  warningCache.add(obj);
+}
+
 function getProtectedKeys<T extends object>(
   value: T,
   properties: Array<keyof T> | undefined,
diff --git a/packages/jest-util/src/index.ts b/packages/jest-util/src/index.ts
@@ -30,6 +30,7 @@ export {default as requireOrImportModule} from './requireOrImportModule';
 export {default as invariant} from './invariant';
 export {default as isNonNullable} from './isNonNullable';
 export {
+  type DeletionMode,
   canDeleteProperties,
   protectProperties,
   deleteProperties,
diff --git a/yarn.lock b/yarn.lock
@@ -13872,6 +13872,7 @@ __metadata:
     clsx: ^2.0.0
     jest-mock: "workspace:*"
     jest-util: "workspace:*"
+    jest-validate: "workspace:*"
   languageName: unknown
   linkType: soft
 
