feat: support files other than js to be ESM (#10823)

Author: SimenB

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 - `[jest-config]` [**BREAKING**] Default to Node testing environment instead of browser (JSDOM) ([#9874](https://github.com/facebook/jest/pull/9874))
 - `[jest-config]` [**BREAKING**] Use `jest-circus` as default test runner ([#10686](https://github.com/facebook/jest/pull/10686))
+- `[jest-config, jest-runtime]` Support ESM for files other than `.js` and `.mjs` ([#10823](https://github.com/facebook/jest/pull/10823))
 - `[jest-repl, jest-runner]` [**BREAKING**] Run transforms over environment ([#8751](https://github.com/facebook/jest/pull/8751))
 - `[jest-runner]` [**BREAKING**] set exit code to 1 if test logs after teardown ([#10728](https://github.com/facebook/jest/pull/10728))
 - `[jest-snapshot]` [**BREAKING**] Make prettier optional for inline snapshots - fall back to string replacement ([#7792](https://github.com/facebook/jest/pull/7792))

docs/Configuration.md

@@ -353,6 +353,23 @@ Default: `false`
 
 Make calling deprecated APIs throw helpful error messages. Useful for easing the upgrade process.
 
+### `extensionsToTreatAsEsm` [array\<string>]
+
+Default: `[]`
+
+Jest will run `.mjs` and `.js` files with nearest `package.json`'s `type` field set to `module` as ECMAScript Modules. If you have any other files that should run with native ESM, you need to specify their file extension here.
+
+> Note: Jest's ESM support is still experimental, see [its docs for more details](ECMAScriptModules.md).
+
+```json
+{
+  ...
+  "jest": {
+    "extensionsToTreatAsEsm": [".ts"]
+  }
+}
+```
+
 ### `extraGlobals` [array\<string>]
 
 Default: `undefined`

docs/ECMAScriptModules.md

@@ -12,8 +12,9 @@ Jest ships with _experimental_ support for ECMAScript Modules (ESM).
 With the warnings out of the way, this is how you activate ESM support in your tests.
 
 1. Ensure you either disable [code transforms](./configuration#transform-objectstring-pathtotransformer--pathtotransformer-object) by passing `transform: {}` or otherwise configure your transformer to emit ESM rather than the default CommonJS (CJS).
-1. Execute `node` with `--experimental-vm-modules`, e.g. `node --experimental-vm-modules node_modules/.bin/jest` or `NODE_OPTIONS=--experimental-vm-modules npx jest` etc.. On Windows, you can use [`cross-env`](https://github.com/kentcdodds/cross-env) to be able to set environment variables
-1. Beyond that, we attempt to follow `node`'s logic for activating "ESM mode" (such as looking at `type` in `package.json` or `mjs` files), see [their docs](https://nodejs.org/api/esm.html#esm_enabling) for details
+1. Execute `node` with `--experimental-vm-modules`, e.g. `node --experimental-vm-modules node_modules/.bin/jest` or `NODE_OPTIONS=--experimental-vm-modules npx jest` etc.. On Windows, you can use [`cross-env`](https://github.com/kentcdodds/cross-env) to be able to set environment variables.
+1. Beyond that, we attempt to follow `node`'s logic for activating "ESM mode" (such as looking at `type` in `package.json` or `mjs` files), see [their docs](https://nodejs.org/api/esm.html#esm_enabling) for details.
+1. If you want to treat other file extensions (such as `ts`) as ESM, please use the [`extensionsToTreatAsEsm` option](Configuration.md#extensionstotreatasesm-arraystring).
 
 ## Differences between ESM and CommonJS
 

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

@@ -15,6 +15,7 @@ exports[`--showConfig outputs config info and exits 1`] = `
       "detectLeaks": false,
       "detectOpenHandles": false,
       "errorOnDeprecated": false,
+      "extensionsToTreatAsEsm": [],
       "extraGlobals": [],
       "forceCoverageMatch": [],
       "globals": {},

e2e/__tests__/nativeEsmTypescript.test.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 {resolve} from 'path';
+import {onNodeVersions} from '@jest/test-utils';
+import {json as runJest} from '../runJest';
+
+const DIR = resolve(__dirname, '../native-esm-typescript');
+
+// The versions where vm.Module exists and commonjs with "exports" is not broken
+onNodeVersions('^12.16.0 || >=13.7.0', () => {
+  test('runs TS test with native ESM', () => {
+    const {exitCode, json} = runJest(DIR, [], {
+      nodeOptions: '--experimental-vm-modules',
+    });
+
+    expect(exitCode).toBe(0);
+
+    expect(json.numTotalTests).toBe(2);
+    expect(json.numPassedTests).toBe(2);
+  });
+});

e2e/native-esm-typescript/__tests__/double.test.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 {double} from '../double';
+
+test('test double', () => {
+  expect(double(2)).toBe(4);
+});
+
+test('test import.meta', () => {
+  expect(typeof import.meta.url).toBe('string');
+});

e2e/native-esm-typescript/babel.config.js

@@ -0,0 +1,11 @@
+/**
+ * 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 = {
+  // importantly this does _not_ include `preset-env`
+  presets: ['@babel/preset-typescript'],
+};

e2e/native-esm-typescript/double.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+
+export function double(num: number): number {
+  return num * 2;
+}

e2e/native-esm-typescript/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "native-esm-typescript",
+  "version": "1.0.0",
+  "jest": {
+    "extensionsToTreatAsEsm": [".ts"],
+    "testEnvironment": "node"
+  }
+}

packages/jest-circus/src/legacy-code-todo-rewrite/jestAdapter.ts

@@ -72,18 +72,15 @@ const jestAdapter = async (
   });
 
   for (const path of config.setupFilesAfterEnv) {
-    // TODO: remove ? in Jest 26
-    const esm = runtime.unstable_shouldLoadAsEsm?.(path);
+    const esm = runtime.unstable_shouldLoadAsEsm(path);
 
     if (esm) {
       await runtime.unstable_importModule(path);
     } else {
       runtime.requireModule(path);
     }
   }
-
-  // TODO: remove ? in Jest 26
-  const esm = runtime.unstable_shouldLoadAsEsm?.(testPath);
+  const esm = runtime.unstable_shouldLoadAsEsm(testPath);
 
   if (esm) {
     await runtime.unstable_importModule(testPath);