test_runner: add global setup and teardown functionality

PR-URL: #57438
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Author: pmarchini

doc/api/cli.md

@@ -2452,6 +2452,19 @@ added:
 Configures the test runner to exit the process once all known tests have
 finished executing even if the event loop would otherwise remain active.
 
+### `--test-global-setup=module`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+Specify a module that will be evaluated before all tests are executed and
+can be used to setup global state or fixtures for tests.
+
+See the documentation on [global setup and teardown][] for more details.
+
 ### `--test-isolation=mode`
 
 <!-- YAML
@@ -3347,6 +3360,7 @@ one is included in the list below.
 * `--test-coverage-functions`
 * `--test-coverage-include`
 * `--test-coverage-lines`
+* `--test-global-setup`
 * `--test-isolation`
 * `--test-name-pattern`
 * `--test-only`
@@ -3898,6 +3912,7 @@ node --stack-trace-limit=12 -p -e "Error.stackTraceLimit" # prints 12
 [emit_warning]: process.md#processemitwarningwarning-options
 [environment_variables]: #environment-variables
 [filtering tests by name]: test.md#filtering-tests-by-name
+[global setup and teardown]: test.md#global-setup-and-teardown
 [jitless]: https://v8.dev/blog/jitless
 [libuv threadpool documentation]: https://docs.libuv.org/en/latest/threadpool.html
 [module compile cache]: module.md#module-compile-cache

doc/api/test.md

@@ -397,6 +397,60 @@ their dependencies. When a change is detected, the test runner will
 rerun the tests affected by the change.
 The test runner will continue to run until the process is terminated.
 
+## Global setup and teardown
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1.0 - Early development
+
+The test runner supports specifying a module that will be evaluated before all tests are executed and
+can be used to setup global state or fixtures for tests. This is useful for preparing resources or setting up
+shared state that is required by multiple tests.
+
+This module can export any of the following:
+
+* A `globalSetup` function which runs once before all tests start
+* A `globalTeardown` function which runs once after all tests complete
+
+The module is specified using the `--test-global-setup` flag when running tests from the command line.
+
+```cjs
+// setup-module.js
+async function globalSetup() {
+  // Setup shared resources, state, or environment
+  console.log('Global setup executed');
+  // Run servers, create files, prepare databases, etc.
+}
+
+async function globalTeardown() {
+  // Clean up resources, state, or environment
+  console.log('Global teardown executed');
+  // Close servers, remove files, disconnect from databases, etc.
+}
+
+module.exports = { globalSetup, globalTeardown };
+```
+
+```mjs
+// setup-module.mjs
+export async function globalSetup() {
+  // Setup shared resources, state, or environment
+  console.log('Global setup executed');
+  // Run servers, create files, prepare databases, etc.
+}
+
+export async function globalTeardown() {
+  // Clean up resources, state, or environment
+  console.log('Global teardown executed');
+  // Close servers, remove files, disconnect from databases, etc.
+}
+```
+
+If the global setup function throws an error, no tests will be run and the process will exit with a non-zero exit code.
+The global teardown function will not be called in this case.
+
 ## Running tests from the command line
 
 The Node.js test runner can be invoked from the command line by passing the

doc/node-config-schema.json

@@ -392,6 +392,9 @@
         "test-coverage-lines": {
           "type": "number"
         },
+        "test-global-setup": {
+          "type": "string"
+        },
         "test-isolation": {
           "type": "string"
         },

doc/node.1

@@ -464,6 +464,9 @@ Require a minimum threshold for line coverage (0 - 100).
 Configures the test runner to exit the process once all known tests have
 finished executing even if the event loop would otherwise remain active.
 .
+.It Fl -test-global-setup
+Specifies a module containing global setup and teardown functions for the test runner.
+.
 .It Fl -test-isolation Ns = Ns Ar mode
 Configures the type of test isolation used in the test runner.
 .

lib/internal/test_runner/harness.js

@@ -25,29 +25,29 @@ const {
   parseCommandLine,
   reporterScope,
   shouldColorizeTestFiles,
+  setupGlobalSetupTeardownFunctions,
 } = require('internal/test_runner/utils');
 const { queueMicrotask } = require('internal/process/task_queues');
 const { TIMEOUT_MAX } = require('internal/timers');
 const { clearInterval, setInterval } = require('timers');
 const { bigint: hrtime } = process.hrtime;
-const resolvedPromise = PromiseResolve();
 const testResources = new SafeMap();
 let globalRoot;
+let globalSetupExecuted = false;
 
 testResources.set(reporterScope.asyncId(), reporterScope);
 
 function createTestTree(rootTestOptions, globalOptions) {
   const buildPhaseDeferred = PromiseWithResolvers();
   const isFilteringByName = globalOptions.testNamePatterns ||
-                            globalOptions.testSkipPatterns;
+    globalOptions.testSkipPatterns;
   const isFilteringByOnly = (globalOptions.isolation === 'process' || process.env.NODE_TEST_CONTEXT) ?
     globalOptions.only : true;
   const harness = {
     __proto__: null,
     buildPromise: buildPhaseDeferred.promise,
     buildSuites: [],
     isWaitingForBuildPhase: false,
-    bootstrapPromise: resolvedPromise,
     watching: false,
     config: globalOptions,
     coverage: null,
@@ -71,6 +71,21 @@ function createTestTree(rootTestOptions, globalOptions) {
     snapshotManager: null,
     isFilteringByName,
     isFilteringByOnly,
+    async runBootstrap() {
+      if (globalSetupExecuted) {
+        return PromiseResolve();
+      }
+      globalSetupExecuted = true;
+      const globalSetupFunctions = await setupGlobalSetupTeardownFunctions(
+        globalOptions.globalSetupPath,
+        globalOptions.cwd,
+      );
+      harness.globalTeardownFunction = globalSetupFunctions.globalTeardownFunction;
+      if (typeof globalSetupFunctions.globalSetupFunction === 'function') {
+        return globalSetupFunctions.globalSetupFunction();
+      }
+      return PromiseResolve();
+    },
     async waitForBuildPhase() {
       if (harness.buildSuites.length > 0) {
         await SafePromiseAllReturnVoid(harness.buildSuites);
@@ -81,6 +96,7 @@ function createTestTree(rootTestOptions, globalOptions) {
   };
 
   harness.resetCounters();
+  harness.bootstrapPromise = harness.runBootstrap();
   globalRoot = new Test({
     __proto__: null,
     ...rootTestOptions,
@@ -232,6 +248,11 @@ function setupProcessState(root, globalOptions) {
       'Promise resolution is still pending but the event loop has already resolved',
       kCancelledByParent));
 
+    if (root.harness.globalTeardownFunction) {
+      await root.harness.globalTeardownFunction();
+      root.harness.globalTeardownFunction = null;
+    }
+
     hook.disable();
     process.removeListener('uncaughtException', exceptionHandler);
     process.removeListener('unhandledRejection', rejectionHandler);
@@ -278,7 +299,10 @@ function lazyBootstrapRoot() {
         process.exitCode = kGenericUserError;
       }
     });
-    globalRoot.harness.bootstrapPromise = globalOptions.setup(globalRoot.reporter);
+    globalRoot.harness.bootstrapPromise = SafePromiseAllReturnVoid([
+      globalRoot.harness.bootstrapPromise,
+      globalOptions.setup(globalRoot.reporter),
+    ]);
   }
   return globalRoot;
 }

lib/internal/test_runner/runner.js

@@ -87,6 +87,7 @@ const {
 } = require('internal/test_runner/utils');
 const { Glob } = require('internal/fs/glob');
 const { once } = require('events');
+const { validatePath } = require('internal/fs/utils');
 const {
   triggerUncaughtException,
   exitCodes: { kGenericUserError },
@@ -559,6 +560,7 @@ function run(options = kEmptyObject) {
     isolation = 'process',
     watch,
     setup,
+    globalSetupPath,
     only,
     globPatterns,
     coverage = false,
@@ -668,6 +670,10 @@ function run(options = kEmptyObject) {
   validateStringArray(argv, 'options.argv');
   validateStringArray(execArgv, 'options.execArgv');
 
+  if (globalSetupPath != null) {
+    validatePath(globalSetupPath, 'options.globalSetupPath');
+  }
+
   const rootTestOptions = { __proto__: null, concurrency, timeout, signal };
   const globalOptions = {
     __proto__: null,
@@ -682,6 +688,7 @@ function run(options = kEmptyObject) {
     branchCoverage: branchCoverage,
     functionCoverage: functionCoverage,
     cwd,
+    globalSetupPath,
   };
   const root = createTestTree(rootTestOptions, globalOptions);
   let testFiles = files ?? createTestFileList(globPatterns, cwd);
@@ -754,7 +761,9 @@ function run(options = kEmptyObject) {
           const cascadedLoader = esmLoader.getOrInitializeCascadedLoader();
           let topLevelTestCount = 0;
 
-          root.harness.bootstrapPromise = promise;
+          root.harness.bootstrapPromise = root.harness.bootstrapPromise ?
+            SafePromiseAllReturnVoid([root.harness.bootstrapPromise, promise]) :
+            promise;
 
           const userImports = getOptionValue('--import');
           for (let i = 0; i < userImports.length; i++) {
@@ -799,12 +808,15 @@ function run(options = kEmptyObject) {
         debug('beginning test execution');
         root.entryFile = null;
         finishBootstrap();
-        root.processPendingSubtests();
+        return root.processPendingSubtests();
       };
     }
   }
 
   const runChain = async () => {
+    if (root.harness?.bootstrapPromise) {
+      await root.harness.bootstrapPromise;
+    }
     if (typeof setup === 'function') {
       await setup(root.reporter);
     }

lib/internal/test_runner/utils.js

@@ -27,7 +27,7 @@ const {
 } = primordials;
 
 const { AsyncResource } = require('async_hooks');
-const { relative, sep } = require('path');
+const { relative, sep, resolve } = require('path');
 const { createWriteStream } = require('fs');
 const { pathToFileURL } = require('internal/url');
 const { getOptionValue } = require('internal/options');
@@ -41,7 +41,12 @@ const {
   kIsNodeError,
 } = require('internal/errors');
 const { compose } = require('stream');
-const { validateInteger } = require('internal/validators');
+const {
+  validateInteger,
+  validateFunction,
+} = require('internal/validators');
+const { validatePath } = require('internal/fs/utils');
+const { kEmptyObject } = require('internal/util');
 
 const coverageColors = {
   __proto__: null,
@@ -199,6 +204,7 @@ function parseCommandLine() {
   const timeout = getOptionValue('--test-timeout') || Infinity;
   const isChildProcess = process.env.NODE_TEST_CONTEXT === 'child';
   const isChildProcessV8 = process.env.NODE_TEST_CONTEXT === 'child-v8';
+  let globalSetupPath;
   let concurrency;
   let coverageExcludeGlobs;
   let coverageIncludeGlobs;
@@ -223,6 +229,7 @@ function parseCommandLine() {
   } else {
     destinations = getOptionValue('--test-reporter-destination');
     reporters = getOptionValue('--test-reporter');
+    globalSetupPath = getOptionValue('--test-global-setup');
     if (reporters.length === 0 && destinations.length === 0) {
       ArrayPrototypePush(reporters, kDefaultReporter);
     }
@@ -328,6 +335,7 @@ function parseCommandLine() {
     only,
     reporters,
     setup,
+    globalSetupPath,
     shard,
     sourceMaps,
     testNamePatterns,
@@ -597,6 +605,27 @@ function getCoverageReport(pad, summary, symbol, color, table) {
   return report;
 }
 
+async function setupGlobalSetupTeardownFunctions(globalSetupPath, cwd) {
+  let globalSetupFunction;
+  let globalTeardownFunction;
+  if (globalSetupPath) {
+    validatePath(globalSetupPath, 'options.globalSetupPath');
+    const fileURL = pathToFileURL(resolve(cwd, globalSetupPath));
+    const cascadedLoader = require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+    const globalSetupModule = await cascadedLoader
+      .import(fileURL, pathToFileURL(cwd + sep).href, kEmptyObject);
+    if (globalSetupModule.globalSetup) {
+      validateFunction(globalSetupModule.globalSetup, 'globalSetupModule.globalSetup');
+      globalSetupFunction = globalSetupModule.globalSetup;
+    }
+    if (globalSetupModule.globalTeardown) {
+      validateFunction(globalSetupModule.globalTeardown, 'globalSetupModule.globalTeardown');
+      globalTeardownFunction = globalSetupModule.globalTeardown;
+    }
+  }
+  return { __proto__: null, globalSetupFunction, globalTeardownFunction };
+}
+
 module.exports = {
   convertStringToRegExp,
   countCompletedTest,
@@ -607,4 +636,5 @@ module.exports = {
   reporterScope,
   shouldColorizeTestFiles,
   getCoverageReport,
+  setupGlobalSetupTeardownFunctions,
 };

src/node_options.cc

@@ -761,6 +761,10 @@ EnvironmentOptionsParser::EnvironmentOptionsParser() {
             "exclude files from coverage report that match this glob pattern",
             &EnvironmentOptions::coverage_exclude_pattern,
             kAllowedInEnvvar);
+  AddOption("--test-global-setup",
+            "specifies the path to the global setup file",
+            &EnvironmentOptions::test_global_setup_path,
+            kAllowedInEnvvar);
   AddOption("--test-udp-no-try-send", "",  // For testing only.
             &EnvironmentOptions::test_udp_no_try_send);
   AddOption("--throw-deprecation",

src/node_options.h

@@ -197,6 +197,7 @@ class EnvironmentOptions : public Options {
   std::vector<std::string> test_name_pattern;
   std::vector<std::string> test_reporter;
   std::vector<std::string> test_reporter_destination;
+  std::string test_global_setup_path;
   bool test_only = false;
   bool test_udp_no_try_send = false;
   std::string test_isolation = "process";

test/fixtures/test-runner/global-setup-teardown/another-test-file.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+
+test('Another test that verifies setup flag existance', (t) => {
+  const setupFlagPath = process.env.SETUP_FLAG_PATH;
+  assert.ok(fs.existsSync(setupFlagPath), 'Setup flag file should exist');
+
+  const content = fs.readFileSync(setupFlagPath, 'utf8');
+  assert.strictEqual(content, 'Setup was executed');
+});