feat: add `@jest/globals` package for importing globals explici… (#9849)

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Features
 
+- `[@jest/globals]` New package so Jest's globals can be explicitly imported ([#9801](https://github.com/facebook/jest/pull/9801))
 - `[jest-runtime]` Populate `require.cache` ([#9841](https://github.com/facebook/jest/pull/9841))
 
 ### Fixes

docs/GlobalAPI.md

@@ -3,7 +3,7 @@ id: api
 title: Globals
 ---
 
-In your test files, Jest puts each of these methods and objects into the global environment. You don't have to require or import anything to use them.
+In your test files, Jest puts each of these methods and objects into the global environment. You don't have to require or import anything to use them. However, if you prefer explicit imports, you can do `import {describe, expect, it} from '@jest/globals'`.
 
 ## Methods
 

docs/JestObjectAPI.md

@@ -3,7 +3,7 @@ id: jest-object
 title: The Jest Object
 ---
 
-The `jest` object is automatically in scope within every test file. The methods in the `jest` object help create mocks and let you control Jest's overall behavior.
+The `jest` object is automatically in scope within every test file. The methods in the `jest` object help create mocks and let you control Jest's overall behavior. It can also be imported explicitly by via `import {jest} from '@jest/globals'`.
 
 ## Mock Modules
 

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

@@ -2,7 +2,7 @@
 
 exports[`on node >=12.16.0 runs test with native ESM 1`] = `
 Test Suites: 1 passed, 1 total
-Tests:       9 passed, 9 total
+Tests:       10 passed, 10 total
 Snapshots:   0 total
 Time:        <<REPLACED>>
 Ran all test suites.

e2e/__tests__/importedGlobals.test.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+
+import runJest from '../runJest';
+
+test('imported globals', () => {
+  const result = runJest('imported-globals');
+  expect(result.exitCode).toBe(0);
+});

e2e/imported-globals/__tests__/env.test.js

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+
+import {
+  expect as importedExpect,
+  jest as importedJest,
+  test as importedTest,
+} from '@jest/globals';
+
+importedTest('they match the globals', () => {
+  importedExpect(importedExpect).toBe(expect);
+  importedExpect(importedJest).toBe(jest);
+  importedExpect(importedTest).toBe(test);
+
+  expect(importedExpect).toBe(expect);
+  expect(importedJest).toBe(jest);
+  expect(importedTest).toBe(test);
+});

e2e/imported-globals/babel.config.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+module.exports = require('../../babel.config');

e2e/imported-globals/package.json

@@ -0,0 +1,5 @@
+{
+  "jest": {
+    "testEnvironment": "node"
+  }
+}

e2e/native-esm/__tests__/native-esm.test.js

@@ -9,6 +9,7 @@ import {readFileSync} from 'fs';
 import {createRequire} from 'module';
 import {dirname, resolve} from 'path';
 import {fileURLToPath} from 'url';
+import {jest as jestObject} from '@jest/globals';
 import staticImportedStateful from '../stateful.mjs';
 import staticImportedStatefulFromCjs from '../fromCjs.mjs';
 import {double} from '../index';
@@ -90,3 +91,7 @@ test('handle unlinked dynamic imports', async () => {
 
   expect(deepDouble(4)).toBe(8);
 });
+
+test('can import `jest` object', () => {
+  expect(jestObject).toBeDefined();
+});

packages/jest-globals/.npmignore

@@ -0,0 +1,5 @@
+**/__mocks__/**
+**/__tests__/**
+src
+tsconfig.json
+tsconfig.tsbuildinfo

packages/jest-globals/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@jest/globals",
+  "version": "25.4.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/facebook/jest.git",
+    "directory": "packages/jest-globals"
+  },
+  "engines": {
+    "node": ">= 8.3"
+  },
+  "license": "MIT",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "typesVersions": {
+    "<3.8": {
+      "build/*": [
+        "build/ts3.4/*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@jest/environment": "^25.4.0",
+    "@jest/types": "^25.4.0",
+    "expect": "^25.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

packages/jest-globals/src/__tests__/index.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+test('throw when directly imported', () => {
+  expect(() => require('../')).toThrowError(
+    'Do not import `@jest/globals` outside of the Jest test environment',
+  );
+});

packages/jest-globals/src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+
+import importedExpect = require('expect');
+import type {Jest} from '@jest/environment';
+import type {Global} from '@jest/types';
+
+export declare type jest = Jest;
+
+export declare type expect = typeof importedExpect;
+
+export declare type it = Global.GlobalAdditions['it'];
+export declare type test = Global.GlobalAdditions['test'];
+export declare type fit = Global.GlobalAdditions['fit'];
+export declare type xit = Global.GlobalAdditions['xit'];
+export declare type xtest = Global.GlobalAdditions['xtest'];
+export declare type describe = Global.GlobalAdditions['describe'];
+export declare type xdescribe = Global.GlobalAdditions['xdescribe'];
+export declare type fdescribe = Global.GlobalAdditions['fdescribe'];
+export declare type beforeAll = Global.GlobalAdditions['beforeAll'];
+export declare type beforeEach = Global.GlobalAdditions['beforeEach'];
+export declare type afterEach = Global.GlobalAdditions['afterEach'];
+export declare type afterAll = Global.GlobalAdditions['afterAll'];
+
+throw new Error(
+  'Do not import `@jest/globals` outside of the Jest test environment',
+);

packages/jest-globals/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    // we don't want `@types/jest` to be referenced
+    "types": ["node"],
+    "rootDir": "src",
+    "outDir": "build"
+  },
+  "references": [
+    {"path": "../expect"},
+    {"path": "../jest-environment"},
+    {"path": "../jest-types"}
+  ]
+}

packages/jest-runtime/package.json

@@ -19,6 +19,7 @@
   "dependencies": {
     "@jest/console": "^25.4.0",
     "@jest/environment": "^25.4.0",
+    "@jest/globals": "^25.4.0",
     "@jest/source-map": "^25.2.6",
     "@jest/test-result": "^25.4.0",
     "@jest/transform": "^25.4.0",

packages/jest-runtime/src/index.ts

@@ -19,7 +19,7 @@ import {
   compileFunction,
 } from 'vm';
 import * as nativeModule from 'module';
-import type {Config} from '@jest/types';
+import type {Config, Global} from '@jest/types';
 import type {
   Jest,
   JestEnvironment,
@@ -27,6 +27,7 @@ import type {
   Module,
   ModuleWrapper,
 } from '@jest/environment';
+import type * as JestGlobals from '@jest/globals';
 import type {SourceMapRegistry} from '@jest/source-map';
 import {formatStackTrace, separateMessageFromStack} from 'jest-message-util';
 import {createDirectory, deepCyclicCopy} from 'jest-util';
@@ -52,6 +53,11 @@ import Resolver = require('jest-resolve');
 import Snapshot = require('jest-snapshot');
 import stripBOM = require('strip-bom');
 
+interface JestGlobalsValues extends Global.TestFrameworkGlobals {
+  jest: JestGlobals.jest;
+  expect: JestGlobals.expect;
+}
+
 type HasteMapOptions = {
   console?: Console;
   maxWorkers: number;
@@ -148,6 +154,7 @@ class Runtime {
   private _unmockList: RegExp | undefined;
   private _virtualMocks: BooleanObject;
   private _moduleImplementation?: typeof nativeModule.Module;
+  private jestObjectCaches: Map<string, Jest>;
 
   constructor(
     config: Config.ProjectConfig,
@@ -185,6 +192,7 @@ class Runtime {
     this._sourceMapRegistry = Object.create(null);
     this._fileTransforms = new Map();
     this._virtualMocks = Object.create(null);
+    this.jestObjectCaches = new Map();
 
     this._mockMetaDataCache = Object.create(null);
     this._shouldMockModuleCache = Object.create(null);
@@ -317,13 +325,6 @@ class Runtime {
     modulePath: Config.Path,
     query = '',
   ): Promise<VMModule> {
-    if (modulePath === '@jest/globals') {
-      // TODO: create a Synthetic Module for this. Will need to create a `jest` object without a `LocalModuleRequire`
-      throw new Error(
-        'Importing `@jest/globals` is not supported from ESM yet',
-      );
-    }
-
     const cacheKey = modulePath + query;
 
     if (!this._esmoduleRegistry.has(cacheKey)) {
@@ -371,11 +372,27 @@ class Runtime {
     return module;
   }
 
-  private async linkModules(specifier: string, referencingModule: VMModule) {
+  private linkModules(specifier: string, referencingModule: VMModule) {
+    if (specifier === '@jest/globals') {
+      const fromCache = this._esmoduleRegistry.get('@jest/globals');
+
+      if (fromCache) {
+        return fromCache;
+      }
+      const globals = this.getGlobalsForEsm(
+        referencingModule.identifier,
+        referencingModule.context,
+      );
+      this._esmoduleRegistry.set('@jest/globals', globals);
+
+      return globals;
+    }
+
     const resolved = this._resolveModule(
       referencingModule.identifier,
       specifier,
     );
+
     if (
       this._resolver.isCoreModule(resolved) ||
       this.unstable_shouldLoadAsEsm(resolved)
@@ -649,12 +666,18 @@ class Runtime {
     };
   }
 
-  requireModuleOrMock(from: Config.Path, moduleName: string): unknown {
+  requireModuleOrMock<T = unknown>(from: Config.Path, moduleName: string): T {
+    // this module is unmockable
+    if (moduleName === '@jest/globals') {
+      // @ts-ignore: we don't care that it's not assignable to T
+      return this.getGlobalsForCjs(from);
+    }
+
     try {
       if (this._shouldMock(from, moduleName)) {
-        return this.requireMock(from, moduleName);
+        return this.requireMock<T>(from, moduleName);
       } else {
-        return this.requireModule(from, moduleName);
+        return this.requireModule<T>(from, moduleName);
       }
     } catch (e) {
       const moduleNotFound = Resolver.tryCastModuleNotFoundError(e);
@@ -981,6 +1004,10 @@ class Runtime {
       return;
     }
 
+    const jestObject = this._createJestObjectFor(filename);
+
+    this.jestObjectCaches.set(filename, jestObject);
+
     try {
       compiledFunction.call(
         localModule.exports,
@@ -990,7 +1017,7 @@ class Runtime {
         dirname, // __dirname
         filename, // __filename
         this._environment.global, // global object
-        this._createJestObjectFor(filename), // jest object
+        jestObject, // jest object
         ...this._config.extraGlobals.map(globalVariable => {
           if (this._environment.global[globalVariable]) {
             return this._environment.global[globalVariable];
@@ -1520,6 +1547,69 @@ class Runtime {
 
     throw e;
   }
+
+  private getGlobalsForCjs(from: Config.Path): JestGlobalsValues {
+    const jest = this.jestObjectCaches.get(from);
+
+    invariant(jest, 'There should always be a Jest object already');
+
+    return {...this.getGlobalsFromEnvironment(), jest};
+  }
+
+  private async getGlobalsForEsm(
+    from: Config.Path,
+    context: VMContext,
+  ): Promise<VMModule> {
+    let jest = this.jestObjectCaches.get(from);
+
+    if (!jest) {
+      jest = this._createJestObjectFor(from);
+
+      this.jestObjectCaches.set(from, jest);
+    }
+
+    const globals: JestGlobalsValues = {
+      ...this.getGlobalsFromEnvironment(),
+      jest,
+    };
+
+    const module = new SyntheticModule(
+      Object.keys(globals),
+      function () {
+        Object.entries(globals).forEach(([key, value]) => {
+          // @ts-ignore: TS doesn't know what `this` is
+          this.setExport(key, value);
+        });
+      },
+      {context, identifier: '@jest/globals'},
+    );
+
+    await module.link(() => {
+      throw new Error('This should never happen');
+    });
+
+    await module.evaluate();
+
+    return module;
+  }
+
+  private getGlobalsFromEnvironment(): Omit<JestGlobalsValues, 'jest'> {
+    return {
+      afterAll: this._environment.global.afterAll,
+      afterEach: this._environment.global.afterEach,
+      beforeAll: this._environment.global.beforeAll,
+      beforeEach: this._environment.global.beforeEach,
+      describe: this._environment.global.describe,
+      expect: this._environment.global.expect,
+      fdescribe: this._environment.global.fdescribe,
+      fit: this._environment.global.fit,
+      it: this._environment.global.it,
+      test: this._environment.global.test,
+      xdescribe: this._environment.global.xdescribe,
+      xit: this._environment.global.xit,
+      xtest: this._environment.global.xtest,
+    };
+  }
 }
 
 function invariant(condition: unknown, message?: string): asserts condition {

packages/jest-runtime/tsconfig.json

@@ -9,6 +9,7 @@
     {"path": "../jest-console"},
     {"path": "../jest-environment"},
     {"path": "../jest-environment-node"},
+    {"path": "../jest-globals"},
     {"path": "../jest-haste-map"},
     {"path": "../jest-message-util"},
     {"path": "../jest-mock"},