feat(jest-runner): allow setupFiles module to export an async function

CHANGELOG.md

@@ -29,6 +29,7 @@
 - `[jest-resolve]` [**BREAKING**] Add support for `package.json` `exports` ([#11961](https://github.com/facebook/jest/pull/11961), [#12373](https://github.com/facebook/jest/pull/12373))
 - `[jest-resolve, jest-runtime]` Add support for `data:` URI import and mock ([#12392](https://github.com/facebook/jest/pull/12392))
 - `[jest-resolve, jest-runtime]` Add support for async resolver ([#11540](https://github.com/facebook/jest/pull/11540))
+- `[jest-runner]` Allow `setupFiles` module to export an async function ([#12042](https://github.com/facebook/jest/pull/12042))
 - `[jest-runner]` Allow passing `testEnvironmentOptions` via docblocks ([#12470](https://github.com/facebook/jest/pull/12470))
 - `[jest-runtime]` [**BREAKING**] `Runtime.createHasteMap` now returns a promise ([#12008](https://github.com/facebook/jest/pull/12008))
 - `[@jest/schemas]` New module for JSON schemas for Jest's config ([#12384](https://github.com/facebook/jest/pull/12384))

docs/Configuration.md

@@ -925,6 +925,12 @@ Default: `[]`
 
 A list of paths to modules that run some code to configure or set up the testing environment. Each setupFile will be run once per test file. Since every test runs in its own environment, these scripts will be executed in the testing environment before executing [`setupFilesAfterEnv`](#setupfilesafterenv-array) and before the test code itself.
 
+:::note
+
+If your setup script is a CJS module, it may export an async function. Jest will call the function and will await for the result. This might be useful to fetch some data asynchronously. In case of ESM module, simply use top-level await to achieve the same result.
+
+:::
+
 ### `setupFilesAfterEnv` \[array]
 
 Default: `[]`

e2e/__tests__/setupFiles.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('invokes async function exported from `setupFiles` module', () => {
+  const result = runJest('setup-files');
+  expect(result.exitCode).toBe(0);
+});

e2e/setup-files/__tests__/setup.test.js

@@ -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.
+ */
+
+const fetchedData = require('../fetched-data');
+
+test('fetches mock data', () => {
+  expect(fetchedData.RESPONSE).toBe('mock-fetched-data');
+});

e2e/setup-files/fetched-data.js

@@ -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.
+ */
+
+module.exports = {
+  RESPONSE: 'not-yet-received',
+};

e2e/setup-files/package.json

@@ -0,0 +1,7 @@
+{
+  "jest": {
+    "setupFiles": [
+      "./setup-fetchdata.js"
+    ]
+  }
+}

e2e/setup-files/setup-fetchdata.js

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+
+const fetchedData = require('./fetched-data');
+
+function mockFetchData(mockData) {
+  return new Promise(resolve => {
+    setTimeout(() => {
+      resolve(mockData);
+    }, 2000);
+  });
+}
+
+module.exports = async () => {
+  const response = await mockFetchData('mock-fetched-data');
+  fetchedData.RESPONSE = response;
+};

packages/jest-repl/src/cli/runtime-cli.ts

@@ -116,8 +116,13 @@ export async function run(
         await runtime.unstable_importModule(path);
       } else {
         runtime.requireModule(path);
+        const setupFile = runtime.requireModule(path);
+        if (typeof setupFile === 'function') {
+          await setupFile();
+        }
       }
     }
+
     const esm = runtime.unstable_shouldLoadAsEsm(filePath);
 
     if (esm) {

packages/jest-runner/src/runTest.ts

@@ -207,7 +207,10 @@ async function runTestInternal(
     if (esm) {
       await runtime.unstable_importModule(path);
     } else {
-      runtime.requireModule(path);
+      const setupFile = runtime.requireModule(path);
+      if (typeof setupFile === 'function') {
+        await setupFile();
+      }
     }
   }