fix: remove support for runScript

CHANGELOG.md

@@ -37,6 +37,7 @@
 - `[jest-console]` `console.dir` now respects the second argument correctly ([#10638](https://github.com/facebook/jest/pull/10638))
 - `[jest-core]` Don't report PerformanceObserver as open handle ([#11123](https://github.com/facebook/jest/pull/11123))
 - `[jest-each]` [**BREAKING**] Ignore excess words in headings ([#8766](https://github.com/facebook/jest/pull/8766))
+- `[jest-environment]` [**BREAKING**] Deprecate usage of `runScript` for test environments ([#11155](https://github.com/facebook/jest/pull/11155))
 - `[jest-environment-jsdom]` Use inner realm’s `ArrayBuffer` constructor ([#10885](https://github.com/facebook/jest/pull/10885))
 - `[jest-globals]` [**BREAKING**] Disallow return values other than a `Promise` from hooks and tests ([#10512](https://github.com/facebook/jest/pull/10512))
 - `[jest-globals]` [**BREAKING**] Disallow mixing a done callback and returning a `Promise` from hooks and tests ([#10512](https://github.com/facebook/jest/pull/10512))

docs/Configuration.md

@@ -1030,7 +1030,7 @@ test('use jsdom in this test file', () => {
 });
 ```
 
-You can create your own module that will be used for setting up the test environment. The module must export a class with `setup`, `teardown` and `runScript` methods. You can also pass variables from this module to your test suites by assigning them to `this.global` object – this will make them available in your test suites as global variables.
+You can create your own module that will be used for setting up the test environment. The module must export a class with `setup`, `teardown` and `getVmContext` methods. You can also pass variables from this module to your test suites by assigning them to `this.global` object – this will make them available in your test suites as global variables.
 
 The class may optionally expose an asynchronous `handleTestEvent` method to bind to events fired by [`jest-circus`](https://github.com/facebook/jest/tree/master/packages/jest-circus). Normally, `jest-circus` test runner would pause until a promise returned from `handleTestEvent` gets fulfilled, **except for the next events**: `start_describe_definition`, `finish_describe_definition`, `add_hook`, `add_test` or `error` (for the up-to-date list you can look at [SyncEvent type in the types definitions](https://github.com/facebook/jest/tree/master/packages/jest-types/src/Circus.ts)). That is caused by backward compatibility reasons and `process.on('unhandledRejection', callback)` signature, but that usually should not be a problem for most of the use cases.
 
@@ -1076,8 +1076,8 @@ class CustomEnvironment extends NodeEnvironment {
     await super.teardown();
   }
 
-  runScript(script) {
-    return super.runScript(script);
+  getVmContext() {
+    return super.getVmContext();
   }
 
   async handleTestEvent(event, state) {

docs/Puppeteer.md

@@ -110,8 +110,8 @@ class PuppeteerEnvironment extends NodeEnvironment {
     await super.teardown();
   }
 
-  runScript(script) {
-    return super.runScript(script);
+  getVmContext() {
+    return super.getVmContext();
   }
 }
 

e2e/test-environment-async/TestEnvironment.js

@@ -34,8 +34,8 @@ class TestEnvironment extends JSDOMEnvironment {
     });
   }
 
-  runScript(script) {
-    return super.runScript(script);
+  getVmContext() {
+    return super.getVmContext();
   }
 }
 

examples/mongodb/mongo-environment.js

@@ -29,8 +29,8 @@ class MongoEnvironment extends NodeEnvironment {
     await super.teardown();
   }
 
-  runScript(script) {
-    return super.runScript(script);
+  getVmContext() {
+    return super.getVmContext();
   }
 }
 

packages/jest-environment-jsdom/src/index.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {Context, Script} from 'vm';
+import type {Context} from 'vm';
 import {JSDOM, VirtualConsole} from 'jsdom';
 import type {EnvironmentContext, JestEnvironment} from '@jest/environment';
 import {LegacyFakeTimers, ModernFakeTimers} from '@jest/fake-timers';
@@ -30,12 +30,12 @@ class JSDOMEnvironment implements JestEnvironment {
   errorEventListener: ((event: Event & {error: Error}) => void) | null;
   moduleMocker: ModuleMocker | null;
 
-  constructor(config: Config.ProjectConfig, options: EnvironmentContext = {}) {
+  constructor(config: Config.ProjectConfig, options?: EnvironmentContext) {
     this.dom = new JSDOM('<!DOCTYPE html>', {
       pretendToBeVisual: true,
       runScripts: 'dangerously',
       url: config.testURL,
-      virtualConsole: new VirtualConsole().sendTo(options.console || console),
+      virtualConsole: new VirtualConsole().sendTo(options?.console || console),
       ...config.testEnvironmentOptions,
     });
     const global = (this.global = (this.dom.window.document
@@ -125,13 +125,6 @@ class JSDOMEnvironment implements JestEnvironment {
     this.fakeTimersModern = null;
   }
 
-  runScript<T = unknown>(script: Script): T | null {
-    if (this.dom) {
-      return script.runInContext(this.dom.getInternalVMContext());
-    }
-    return null;
-  }
-
   getVmContext(): Context | null {
     if (this.dom) {
       return this.dom.getInternalVMContext();

packages/jest-environment-node/src/index.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Context, Script, createContext, runInContext} from 'vm';
+import {Context, createContext, runInContext} from 'vm';
 import type {JestEnvironment} from '@jest/environment';
 import {LegacyFakeTimers, ModernFakeTimers} from '@jest/fake-timers';
 import type {Config, Global} from '@jest/types';
@@ -104,15 +104,6 @@ class NodeEnvironment implements JestEnvironment {
     this.fakeTimersModern = null;
   }
 
-  // TS infers the return type to be `any`, since that's what `runInContext`
-  // returns.
-  runScript<T = unknown>(script: Script): T | null {
-    if (this.context) {
-      return script.runInContext(this.context);
-    }
-    return null;
-  }
-
   getVmContext(): Context | null {
     return this.context;
   }

packages/jest-environment/src/index.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import type {Context, Script} from 'vm';
+import type {Context} from 'vm';
 import type {LegacyFakeTimers, ModernFakeTimers} from '@jest/fake-timers';
 import type {Circus, Config, Global} from '@jest/types';
 import type {
@@ -14,13 +14,11 @@ import type {
   ModuleMocker,
 } from 'jest-mock';
 
-// In Jest 25, remove `Partial` since it's incorrect. The properties are always
-// passed, or not. The context itself is optional, not properties within it.
-export type EnvironmentContext = Partial<{
+export type EnvironmentContext = {
   console: Console;
   docblockPragmas: Record<string, string | Array<string>>;
   testPath: Config.Path;
-}>;
+};
 
 // Different Order than https://nodejs.org/api/modules.html#modules_the_module_wrapper , however needs to be in the form [jest-transform]ScriptTransformer accepts
 export type ModuleWrapper = (
@@ -40,11 +38,7 @@ export declare class JestEnvironment {
   fakeTimers: LegacyFakeTimers<unknown> | null;
   fakeTimersModern: ModernFakeTimers | null;
   moduleMocker: ModuleMocker | null;
-  /**
-   * @deprecated implement getVmContext instead
-   */
-  runScript<T = unknown>(script: Script): T | null;
-  getVmContext?(): Context | null;
+  getVmContext(): Context | null;
   setup(): Promise<void>;
   teardown(): Promise<void>;
   handleTestEvent?(

packages/jest-runner/src/runTest.ts

@@ -142,6 +142,13 @@ async function runTestInternal(
     docblockPragmas,
     testPath: path,
   });
+
+  if (typeof environment.getVmContext !== 'function') {
+    throw new Error(
+      `Test environment found at "testEnvironment" does not export a "getVmContext" method, which is mandatory from Jest 27`,
+    );
+  }
+
   const leakDetector = config.detectLeaks
     ? new LeakDetector(environment)
     : null;

packages/jest-runtime/src/index.ts

@@ -1104,15 +1104,10 @@ export default class Runtime {
 
     let runScript: RunScriptEvalResult | null = null;
 
-    // Use this if available instead of deprecated `JestEnvironment.runScript`
-    if (typeof this._environment.getVmContext === 'function') {
-      const vmContext = this._environment.getVmContext();
+    const vmContext = this._environment.getVmContext();
 
-      if (vmContext) {
-        runScript = script.runInContext(vmContext, {filename});
-      }
-    } else {
-      runScript = this._environment.runScript<RunScriptEvalResult>(script);
+    if (vmContext) {
+      runScript = script.runInContext(vmContext, {filename});
     }
 
     if (runScript !== null) {