Rename "moduleLoader" to "runtime" and "extraGlobals" to "sandboxInjectedGlobals" configuration options

CHANGELOG.md

@@ -8,6 +8,8 @@
 - `[jest-config]` [**BREAKING**] Stop shipping `jest-environment-jsdom` by default ([#12354](https://github.com/facebook/jest/pull/12354))
 - `[jest-config]` [**BREAKING**] Stop shipping `jest-jasmine2` by default ([#12355](https://github.com/facebook/jest/pull/12355))
 - `[jest-config, @jest/types]` Add `ci` to `GlobalConfig` ([#12378](https://github.com/facebook/jest/pull/12378))
+- `[jest-config]` [**BREAKING**] Rename `moduleLoader` to `runtime` ([#10817](https://github.com/facebook/jest/pull/10817))
+- `[jest-config]` [**BREAKING**] Rename `extraGlobals` to `sandboxInjectedGlobals` ([#10817](https://github.com/facebook/jest/pull/10817))
 - `[jest-core]` Pass project config to `globalSetup`/`globalTeardown` function as second argument ([#12440](https://github.com/facebook/jest/pull/12440))
 - `[jest-environment-jsdom]` [**BREAKING**] Upgrade jsdom to 19.0.0 ([#12290](https://github.com/facebook/jest/pull/12290))
 - `[jest-environment-jsdom]` [**BREAKING**] Add default `browser` condition to `exportConditions` for `jsdom` environment ([#11924](https://github.com/facebook/jest/pull/11924))

docs/Configuration.md

@@ -375,23 +375,6 @@ Jest will run `.mjs` and `.js` files with nearest `package.json`'s `type` field
 }
 ```
 
-### `extraGlobals` \[array<string>]
-
-Default: `undefined`
-
-Test files run inside a [vm](https://nodejs.org/api/vm.html), which slows calls to global context properties (e.g. `Math`). With this option you can specify extra properties to be defined inside the vm for faster lookups.
-
-For example, if your tests call `Math` often, you can pass it by setting `extraGlobals`.
-
-```json
-{
-  ...
-  "jest": {
-    "extraGlobals": ["Math"]
-  }
-}
-```
-
 ### `forceCoverageMatch` \[array<string>]
 
 Default: `['']`
@@ -907,6 +890,35 @@ async function runTests(
 
 If you need to restrict your test-runner to only run in serial rather than being executed in parallel your class should have the property `isSerial` to be set as `true`.
 
+### `sandboxInjectedGlobals` \[array<string>]
+
+:::tip
+
+Renamed from `extraGlobals` in Jest 28.
+
+:::
+
+Default: `undefined`
+
+Test files run inside a [vm](https://nodejs.org/api/vm.html), which slows calls to global context properties (e.g. `Math`). With this option you can specify extra properties to be defined inside the vm for faster lookups.
+
+For example, if your tests call `Math` often, you can pass it by setting `sandboxInjectedGlobals`.
+
+```json
+{
+  ...
+  "jest": {
+    "sandboxInjectedGlobals": ["Math"]
+  }
+}
+```
+
+:::note
+
+This option has no effect if you use [native ESM](ECMAScriptModules.md).
+
+:::
+
 ### `setupFiles` \[array]
 
 Default: `[]`

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

@@ -16,7 +16,6 @@ exports[`--showConfig outputs config info and exits 1`] = `
       "detectOpenHandles": false,
       "errorOnDeprecated": false,
       "extensionsToTreatAsEsm": [],
-      "extraGlobals": [],
       "forceCoverageMatch": [],
       "globals": {},
       "haste": {
@@ -49,6 +48,7 @@ exports[`--showConfig outputs config info and exits 1`] = `
         "<<REPLACED_ROOT_DIR>>"
       ],
       "runner": "<<REPLACED_JEST_PACKAGES_DIR>>/jest-runner/build/index.js",
+      "sandboxInjectedGlobals": [],
       "setupFiles": [],
       "setupFilesAfterEnv": [],
       "skipFilter": false,

e2e/__tests__/extraGlobals.test.ts → e2e/__tests__/sandboxInjectedGlobals.test.ts

@@ -14,7 +14,7 @@ const DIR = path.resolve(tmpdir(), 'extra-globals');
 
 beforeEach(() => {
   cleanup(DIR);
-  createEmptyPackage(DIR, {jest: {extraGlobals: ['Math']}});
+  createEmptyPackage(DIR, {jest: {sandboxInjectedGlobals: ['Math']}});
 });
 
 afterAll(() => cleanup(DIR));

packages/jest-config/src/Deprecated.ts

@@ -17,6 +17,18 @@ const deprecatedOptions: DeprecatedOptions = {
       '"browser"',
     )} has been deprecated. Please install "browser-resolve" and use the "resolver" option in Jest configuration as shown in the documentation: https://jestjs.io/docs/configuration#resolver-string`,
 
+  extraGlobals: (_options: {extraGlobals?: string}) => `  Option ${chalk.bold(
+    '"extraGlobals"',
+  )} was replaced by ${chalk.bold('"sandboxInjectedGlobals"')}.
+
+  Please update your configuration.`,
+
+  moduleLoader: (_options: {moduleLoader?: string}) => `  Option ${chalk.bold(
+    '"moduleLoader"',
+  )} was replaced by ${chalk.bold('"runtime"')}.
+
+  Please update your configuration.`,
+
   preprocessorIgnorePatterns: (options: {
     preprocessorIgnorePatterns?: Array<string>;
   }) => `  Option ${chalk.bold(

packages/jest-config/src/ValidConfig.ts

@@ -49,7 +49,6 @@ const initialOptions: Config.InitialOptions = {
   errorOnDeprecated: false,
   expand: false,
   extensionsToTreatAsEsm: [],
-  extraGlobals: [],
   filter: '<rootDir>/filter.js',
   forceCoverageMatch: ['**/*.t.js'],
   forceExit: false,
@@ -76,7 +75,6 @@ const initialOptions: Config.InitialOptions = {
   maxWorkers: '50%',
   moduleDirectories: ['node_modules'],
   moduleFileExtensions: ['js', 'json', 'jsx', 'ts', 'tsx', 'node'],
-  moduleLoader: '<rootDir>',
   moduleNameMapper: {
     '^React$': '<rootDir>/node_modules/react',
   },
@@ -105,6 +103,8 @@ const initialOptions: Config.InitialOptions = {
   roots: ['<rootDir>'],
   runTestsByPath: false,
   runner: 'jest-runner',
+  runtime: '<rootDir>',
+  sandboxInjectedGlobals: [],
   setupFiles: ['<rootDir>/setup.js'],
   setupFilesAfterEnv: ['<rootDir>/testSetupFile.js'],
   silent: true,

packages/jest-config/src/__tests__/__snapshots__/normalize.test.ts.snap

@@ -132,6 +132,54 @@ exports[`extensionsToTreatAsEsm throws on .mjs 1`] = `
 <red></>"
 `;
 
+exports[`extraGlobals logs a deprecation warning when \`extraGlobals\` is used 1`] = `
+[MockFunction] {
+  "calls": Array [
+    Array [
+      "<yellow><bold><bold>●</><bold> Deprecation Warning</>:</>
+<yellow></>
+<yellow>  Option <bold>"extraGlobals"</> was replaced by <bold>"sandboxInjectedGlobals"</>.</>
+<yellow></>
+<yellow>  Please update your configuration.</>
+<yellow></>
+<yellow>  <bold>Configuration Documentation:</></>
+<yellow>  https://jestjs.io/docs/configuration</>
+<yellow></>",
+    ],
+  ],
+  "results": Array [
+    Object {
+      "type": "return",
+      "value": undefined,
+    },
+  ],
+}
+`;
+
+exports[`moduleLoader logs a deprecation warning when \`moduleLoader\` is used 1`] = `
+[MockFunction] {
+  "calls": Array [
+    Array [
+      "<yellow><bold><bold>●</><bold> Deprecation Warning</>:</>
+<yellow></>
+<yellow>  Option <bold>"moduleLoader"</> was replaced by <bold>"runtime"</>.</>
+<yellow></>
+<yellow>  Please update your configuration.</>
+<yellow></>
+<yellow>  <bold>Configuration Documentation:</></>
+<yellow>  https://jestjs.io/docs/configuration</>
+<yellow></>",
+    ],
+  ],
+  "results": Array [
+    Object {
+      "type": "return",
+      "value": undefined,
+    },
+  ],
+}
+`;
+
 exports[`preset throws when module was found but no "jest-preset.js" or "jest-preset.json" files 1`] = `
 "<red><bold><bold>● </><bold>Validation Error</>:</>
 <red></>

packages/jest-config/src/__tests__/normalize.test.ts

@@ -1936,3 +1936,39 @@ describe('testURL', () => {
     expect(console.warn).toMatchSnapshot();
   });
 });
+
+describe('extraGlobals', () => {
+  beforeEach(() => {
+    jest.mocked(console.warn).mockImplementation(() => {});
+  });
+
+  it('logs a deprecation warning when `extraGlobals` is used', async () => {
+    await normalize(
+      {
+        extraGlobals: ['Math'],
+        rootDir: '/root/',
+      },
+      {} as Config.Argv,
+    );
+
+    expect(console.warn).toMatchSnapshot();
+  });
+});
+
+describe('moduleLoader', () => {
+  beforeEach(() => {
+    jest.mocked(console.warn).mockImplementation(() => {});
+  });
+
+  it('logs a deprecation warning when `moduleLoader` is used', async () => {
+    await normalize(
+      {
+        moduleLoader: '<rootDir>/runtime.js',
+        rootDir: '/root/',
+      },
+      {} as Config.Argv,
+    );
+
+    expect(console.warn).toMatchSnapshot();
+  });
+});

packages/jest-config/src/index.ts

@@ -184,7 +184,6 @@ const groupOptions = (
     displayName: options.displayName,
     errorOnDeprecated: options.errorOnDeprecated,
     extensionsToTreatAsEsm: options.extensionsToTreatAsEsm,
-    extraGlobals: options.extraGlobals,
     filter: options.filter,
     forceCoverageMatch: options.forceCoverageMatch,
     globalSetup: options.globalSetup,
@@ -194,7 +193,6 @@ const groupOptions = (
     injectGlobals: options.injectGlobals,
     moduleDirectories: options.moduleDirectories,
     moduleFileExtensions: options.moduleFileExtensions,
-    moduleLoader: options.moduleLoader,
     moduleNameMapper: options.moduleNameMapper,
     modulePathIgnorePatterns: options.modulePathIgnorePatterns,
     modulePaths: options.modulePaths,
@@ -207,6 +205,8 @@ const groupOptions = (
     rootDir: options.rootDir,
     roots: options.roots,
     runner: options.runner,
+    runtime: options.runtime,
+    sandboxInjectedGlobals: options.sandboxInjectedGlobals,
     setupFiles: options.setupFiles,
     setupFilesAfterEnv: options.setupFilesAfterEnv,
     skipFilter: options.skipFilter,

packages/jest-config/src/normalize.ts

@@ -734,7 +734,7 @@ export default async function normalize(
       case 'dependencyExtractor':
       case 'globalSetup':
       case 'globalTeardown':
-      case 'moduleLoader':
+      case 'runtime':
       case 'snapshotResolver':
       case 'testResultsProcessor':
       case 'testRunner':
@@ -979,7 +979,6 @@ export default async function normalize(
       case 'errorOnDeprecated':
       case 'expand':
       case 'extensionsToTreatAsEsm':
-      case 'extraGlobals':
       case 'globals':
       case 'findRelatedTests':
       case 'forceCoverageMatch':
@@ -1004,6 +1003,7 @@ export default async function normalize(
       case 'restoreMocks':
       case 'rootDir':
       case 'runTestsByPath':
+      case 'sandboxInjectedGlobals':
       case 'silent':
       case 'skipFilter':
       case 'skipNodeResolution':
@@ -1209,8 +1209,8 @@ export default async function normalize(
     newOptions.projects = [];
   }
 
-  if (!newOptions.extraGlobals) {
-    newOptions.extraGlobals = [];
+  if (!newOptions.sandboxInjectedGlobals) {
+    newOptions.sandboxInjectedGlobals = [];
   }
 
   if (!newOptions.forceExit) {

packages/jest-core/src/lib/__tests__/__snapshots__/logDebugMessages.test.ts.snap

@@ -13,7 +13,6 @@ exports[`prints the config object 1`] = `
     "detectOpenHandles": false,
     "errorOnDeprecated": false,
     "extensionsToTreatAsEsm": [],
-    "extraGlobals": [],
     "forceCoverageMatch": [],
     "globals": {},
     "haste": {},
@@ -22,7 +21,6 @@ exports[`prints the config object 1`] = `
     "moduleFileExtensions": [
       "js"
     ],
-    "moduleLoader": "/test_module_loader_path",
     "moduleNameMapper": [],
     "modulePathIgnorePatterns": [],
     "modulePaths": [],
@@ -36,6 +34,8 @@ exports[`prints the config object 1`] = `
       "path/to/dir/test"
     ],
     "runner": "jest-runner",
+    "runtime": "/test_module_loader_path",
+    "sandboxInjectedGlobals": [],
     "setupFiles": [],
     "setupFilesAfterEnv": [],
     "skipFilter": false,

packages/jest-environment/src/index.ts

@@ -25,7 +25,7 @@ export type ModuleWrapper = (
   __dirname: string,
   __filename: Module['filename'],
   jest?: Jest,
-  ...extraGlobals: Array<Global.Global[keyof Global.Global]>
+  ...sandboxInjectedGlobals: Array<Global.Global[keyof Global.Global]>
 ) => unknown;
 
 export interface JestEnvironmentConfig {

packages/jest-runner/src/runTest.ts

@@ -115,8 +115,8 @@ async function runTestInternal(
         : projectConfig.testRunner,
     );
   const Runtime: typeof RuntimeClass = interopRequireDefault(
-    projectConfig.moduleLoader
-      ? require(projectConfig.moduleLoader)
+    projectConfig.runtime
+      ? require(projectConfig.runtime)
       : require('jest-runtime'),
   ).default;
 

packages/jest-runtime/src/__tests__/runtime_wrap.js

@@ -23,7 +23,9 @@ describe('Runtime', () => {
     });
 
     it('injects "extra globals"', async () => {
-      const runtime = await createRuntime(__filename, {extraGlobals: ['Math']});
+      const runtime = await createRuntime(__filename, {
+        sandboxInjectedGlobals: ['Math'],
+      });
 
       expect(
         runtime.wrapCodeInModuleWrapper('module.exports = "Hello!"'),

packages/jest-runtime/src/index.ts

@@ -1472,15 +1472,17 @@ export default class Runtime {
 
     const lastArgs: [Jest | undefined, ...Array<Global.Global>] = [
       this._config.injectGlobals ? jestObject : undefined, // jest object
-      ...this._config.extraGlobals.map<Global.Global>(globalVariable => {
-        if (this._environment.global[globalVariable]) {
-          return this._environment.global[globalVariable];
-        }
+      ...this._config.sandboxInjectedGlobals.map<Global.Global>(
+        globalVariable => {
+          if (this._environment.global[globalVariable]) {
+            return this._environment.global[globalVariable];
+          }
 
-        throw new Error(
-          `You have requested '${globalVariable}' as a global variable, but it was not present. Please check your config or your global environment.`,
-        );
-      }),
+          throw new Error(
+            `You have requested '${globalVariable}' as a global variable, but it was not present. Please check your config or your global environment.`,
+          );
+        },
+      ),
     ];
 
     if (!this._mainModule && filename === this._testPath) {
@@ -2221,7 +2223,7 @@ export default class Runtime {
       '__dirname',
       '__filename',
       this._config.injectGlobals ? 'jest' : undefined,
-      ...this._config.extraGlobals,
+      ...this._config.sandboxInjectedGlobals,
     ].filter(notEmpty);
   }