test_runner: pass setup context to global teardown

Allow globalSetup() to return data consumed by globalTeardown(). This resolves the long-standing TODO and documents the context-passing behavior for test global hooks.

Author: Han5991

doc/api/test.md

@@ -510,6 +510,9 @@ 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
 
+If `globalSetup` returns a value, that value is passed as the first argument to
+`globalTeardown`.
+
 The module is specified using the `--test-global-setup` flag when running tests from the command line.
 
 ```cjs
@@ -520,9 +523,10 @@ async function globalSetup() {
   // Run servers, create files, prepare databases, etc.
 }
 
-async function globalTeardown() {
+async function globalTeardown(context) {
   // Clean up resources, state, or environment
   console.log('Global teardown executed');
+  console.log(context);
   // Close servers, remove files, disconnect from databases, etc.
 }
 
@@ -537,9 +541,10 @@ export async function globalSetup() {
   // Run servers, create files, prepare databases, etc.
 }
 
-export async function globalTeardown() {
+export async function globalTeardown(context) {
   // Clean up resources, state, or environment
   console.log('Global teardown executed');
+  console.log(context);
   // Close servers, remove files, disconnect from databases, etc.
 }
 ```

lib/internal/test_runner/harness.js

@@ -71,6 +71,7 @@ function createTestTree(rootTestOptions, globalOptions) {
     counters: null,
     shouldColorizeTestFiles: shouldColorizeTestFiles(globalOptions.destinations),
     teardown: null,
+    globalSetupContext: undefined,
     snapshotManager: null,
     previousRuns: null,
     isFilteringByName,
@@ -86,7 +87,7 @@ function createTestTree(rootTestOptions, globalOptions) {
       );
       harness.globalTeardownFunction = globalSetupFunctions.globalTeardownFunction;
       if (typeof globalSetupFunctions.globalSetupFunction === 'function') {
-        return globalSetupFunctions.globalSetupFunction();
+        harness.globalSetupContext = await globalSetupFunctions.globalSetupFunction();
       }
       return PromiseResolve();
     },
@@ -275,8 +276,9 @@ function setupProcessState(root, globalOptions) {
       kCancelledByParent));
 
     if (root.harness.globalTeardownFunction) {
-      await root.harness.globalTeardownFunction();
+      await root.harness.globalTeardownFunction(root.harness.globalSetupContext);
       root.harness.globalTeardownFunction = null;
+      root.harness.globalSetupContext = undefined;
     }
 
     hook.disable();

test/fixtures/test-runner/global-setup-teardown/context-setup-teardown.js

@@ -0,0 +1,17 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const contextFlagPath = process.env.CONTEXT_FLAG_PATH;
+
+async function globalSetup() {
+  return {
+    value: 'context from setup',
+  };
+}
+
+async function globalTeardown(context) {
+  fs.writeFileSync(contextFlagPath, context?.value ?? 'missing context');
+}
+
+module.exports = { globalSetup, globalTeardown };

test/parallel/test-runner-global-setup-teardown.mjs

@@ -205,8 +205,29 @@ async function runTest(
       assert.strictEqual(content, 'Teardown-only was executed');
     });
 
-    // TODO(pmarchini): We should be able to share context between setup and teardown
-    it.todo('should share context between setup and teardown');
+    it('should share context between setup and teardown', async () => {
+      const contextFlagPath = tmpdir.resolve('context-shared.tmp');
+      const setupFlagPath = tmpdir.resolve('setup-for-context.tmp');
+
+      // Create a setup file for test-file.js to find
+      fs.writeFileSync(setupFlagPath, 'Setup was executed');
+
+      const { stdout } = await runTest({
+        isolation,
+        globalSetupFile: 'context-setup-teardown.js',
+        env: {
+          CONTEXT_FLAG_PATH: contextFlagPath,
+          SETUP_FLAG_PATH: setupFlagPath,
+        },
+        runnerEnabled,
+      });
+
+      assert.match(stdout, /pass 2/);
+      assert.match(stdout, /fail 0/);
+      assert.ok(fs.existsSync(contextFlagPath), 'Context flag file should exist');
+      const content = fs.readFileSync(contextFlagPath, 'utf8');
+      assert.strictEqual(content, 'context from setup');
+    });
 
     it('should handle async setup and teardown', async () => {
       const asyncFlagPath = tmpdir.resolve('async-executed.tmp');

test/parallel/test-runner-run-global-hooks.mjs

@@ -138,8 +138,28 @@ describe('require(\'node:test\').run with global hooks', { concurrency: false },
         assert.strictEqual(content, 'Teardown-only was executed');
       });
 
-      // TODO(pmarchini): We should be able to share context between setup and teardown
-      it.todo('should share context between setup and teardown');
+      it('should share context between setup and teardown', async () => {
+        const contextFlagPath = tmpdir.resolve('context-shared.tmp');
+        const setupFlagPath = tmpdir.resolve('setup-for-context.tmp');
+
+        // Create a setup file for test-file.js to find
+        fs.writeFileSync(setupFlagPath, 'Setup was executed');
+
+        const { results } = await runTestWithGlobalHooks({
+          globalSetupFile: 'context-setup-teardown.js',
+          runnerEnv: {
+            CONTEXT_FLAG_PATH: contextFlagPath,
+            SETUP_FLAG_PATH: setupFlagPath,
+          },
+          isolation,
+        });
+
+        assert.strictEqual(results.passed, 2);
+        assert.strictEqual(results.failed, 0);
+        assert.ok(fs.existsSync(contextFlagPath), 'Context flag file should exist');
+        const content = fs.readFileSync(contextFlagPath, 'utf8');
+        assert.strictEqual(content, 'context from setup');
+      });
 
       it('should handle async setup and teardown', async () => {
         const asyncFlagPath = tmpdir.resolve('async-executed.tmp');