test_runner: add global setup and teardown functionality

PR-URL: #57438 Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Marco Ippolito <[email protected]> Reviewed-By: Chemi Atlow <[email protected]>

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
+asyncfunctionglobalSetup(){
+// Setup shared resources, state, or environment
+console.log('Global setup executed');
+// Run servers, create files, prepare databases, etc.
+}
+
+asyncfunctionglobalTeardown(){
+// 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
+exportasyncfunctionglobalSetup(){
+// Setup shared resources, state, or environment
+console.log('Global setup executed');
+// Run servers, create files, prepare databases, etc.
+}
+
+exportasyncfunctionglobalTeardown(){
+// 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.
 .
+.ItFl-test-global-setup
+Specifies a module containing global setup and teardown functions for the test runner.
+.
 .ItFl-test-isolationNs=NsArmode
 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;
-constresolvedPromise=PromiseResolve();
 consttestResources=newSafeMap();
 letglobalRoot;
+letglobalSetupExecuted=false;
 
 testResources.set(reporterScope.asyncId(),reporterScope);
 
 functioncreateTestTree(rootTestOptions,globalOptions){
 constbuildPhaseDeferred=PromiseWithResolvers();
 constisFilteringByName=globalOptions.testNamePatterns||
-globalOptions.testSkipPatterns;
+globalOptions.testSkipPatterns;
 constisFilteringByOnly=(globalOptions.isolation==='process'||process.env.NODE_TEST_CONTEXT) ?
 globalOptions.only : true;
 constharness={
 __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,
+asyncrunBootstrap(){
+if(globalSetupExecuted){
+returnPromiseResolve();
+}
+globalSetupExecuted=true;
+constglobalSetupFunctions=awaitsetupGlobalSetupTeardownFunctions(
+globalOptions.globalSetupPath,
+globalOptions.cwd,
+);
+harness.globalTeardownFunction=globalSetupFunctions.globalTeardownFunction;
+if(typeofglobalSetupFunctions.globalSetupFunction==='function'){
+returnglobalSetupFunctions.globalSetupFunction();
+}
+returnPromiseResolve();
+},
 asyncwaitForBuildPhase(){
 if(harness.buildSuites.length>0){
 awaitSafePromiseAllReturnVoid(harness.buildSuites);
@@ -81,6 +96,7 @@ function createTestTree(rootTestOptions, globalOptions){
 };
 
 harness.resetCounters();
+harness.bootstrapPromise=harness.runBootstrap();
 globalRoot=newTest({
 __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){
+awaitroot.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),
+]);
 }
 returnglobalRoot;
 }

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');
+}
+
 constrootTestOptions={__proto__: null, concurrency, timeout, signal };
 constglobalOptions={
 __proto__: null,
@@ -682,6 +688,7 @@ function run(options = kEmptyObject){
 branchCoverage: branchCoverage,
 functionCoverage: functionCoverage,
  cwd,
+ globalSetupPath,
 };
 constroot=createTestTree(rootTestOptions,globalOptions);
 lettestFiles=files??createTestFileList(globPatterns,cwd);
@@ -754,7 +761,9 @@ function run(options = kEmptyObject){
 constcascadedLoader=esmLoader.getOrInitializeCascadedLoader();
 lettopLevelTestCount=0;
 
-root.harness.bootstrapPromise=promise;
+root.harness.bootstrapPromise=root.harness.bootstrapPromise ?
+SafePromiseAllReturnVoid([root.harness.bootstrapPromise,promise]) :
+promise;
 
 constuserImports=getOptionValue('--import');
 for(leti=0;i<userImports.length;i++){
@@ -799,12 +808,15 @@ function run(options = kEmptyObject){
 debug('beginning test execution');
 root.entryFile=null;
 finishBootstrap();
-root.processPendingSubtests();
+returnroot.processPendingSubtests();
 };
 }
 }
 
 construnChain=async()=>{
+if(root.harness?.bootstrapPromise){
+awaitroot.harness.bootstrapPromise;
+}
 if(typeofsetup==='function'){
 awaitsetup(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');
 
 constcoverageColors={
 __proto__: null,
@@ -199,6 +204,7 @@ function parseCommandLine(){
 consttimeout=getOptionValue('--test-timeout')||Infinity;
 constisChildProcess=process.env.NODE_TEST_CONTEXT==='child';
 constisChildProcessV8=process.env.NODE_TEST_CONTEXT==='child-v8';
+letglobalSetupPath;
 letconcurrency;
 letcoverageExcludeGlobs;
 letcoverageIncludeGlobs;
@@ -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){
 returnreport;
 }
 
+asyncfunctionsetupGlobalSetupTeardownFunctions(globalSetupPath,cwd){
+letglobalSetupFunction;
+letglobalTeardownFunction;
+if(globalSetupPath){
+validatePath(globalSetupPath,'options.globalSetupPath');
+constfileURL=pathToFileURL(resolve(cwd,globalSetupPath));
+constcascadedLoader=require('internal/modules/esm/loader').getOrInitializeCascadedLoader();
+constglobalSetupModule=awaitcascadedLoader
+.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';
+
+consttest=require('node:test');
+constassert=require('node:assert');
+constfs=require('node:fs');
+
+test('Another test that verifies setup flag existance',(t)=>{
+constsetupFlagPath=process.env.SETUP_FLAG_PATH;
+assert.ok(fs.existsSync(setupFlagPath),'Setup flag file should exist');
+
+constcontent=fs.readFileSync(setupFlagPath,'utf8');
+assert.strictEqual(content,'Setup was executed');
+});