test_runner: share setup context with teardown

Pass a shared context object to both global hooks so setup and teardown
can exchange state without return-value coupling.

This keeps the API extensible and aligns the docs and fixtures with the
ctx.server lifecycle pattern.

Author: Han5991

doc/api/test.md

@@ -510,19 +510,24 @@ 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 same context object is passed as the first argument to both `globalSetup`
+and `globalTeardown`.
+
 The module is specified using the `--test-global-setup` flag when running tests from the command line.
 
 ```cjs
 // setup-module.js
-async function globalSetup() {
+async function globalSetup(context) {
   // Setup shared resources, state, or environment
   console.log('Global setup executed');
+  context.server = await startServer();
   // 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');
+  await context.server.close();
   // Close servers, remove files, disconnect from databases, etc.
 }
 
@@ -531,15 +536,17 @@ module.exports = { globalSetup, globalTeardown };
 
 ```mjs
 // setup-module.mjs
-export async function globalSetup() {
+export async function globalSetup(context) {
   // Setup shared resources, state, or environment
   console.log('Global setup executed');
+  context.server = await startServer();
   // 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');
+  await context.server.close();
   // 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,
@@ -85,8 +86,12 @@ function createTestTree(rootTestOptions, globalOptions) {
         globalOptions.cwd,
       );
       harness.globalTeardownFunction = globalSetupFunctions.globalTeardownFunction;
+      if (typeof globalSetupFunctions.globalSetupFunction === 'function' ||
+          typeof globalSetupFunctions.globalTeardownFunction === 'function') {
+        harness.globalSetupContext = { __proto__: null };
+      }
       if (typeof globalSetupFunctions.globalSetupFunction === 'function') {
-        return globalSetupFunctions.globalSetupFunction();
+        await globalSetupFunctions.globalSetupFunction(harness.globalSetupContext);
       }
       return PromiseResolve();
     },
@@ -275,8 +280,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,23 @@
+'use strict';
+
+const fs = require('node:fs');
+
+const contextFlagPath = process.env.CONTEXT_FLAG_PATH;
+
+async function startServer() {
+  return {
+    async close() {
+      fs.writeFileSync(contextFlagPath, 'server closed');
+    },
+  };
+}
+
+async function globalSetup(context) {
+  context.server = await startServer();
+}
+
+async function globalTeardown(context) {
+  await context.server.close();
+}
+
+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, 'server closed');
+    });
 
     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, 'server closed');
+      });
 
       it('should handle async setup and teardown', async () => {
         const asyncFlagPath = tmpdir.resolve('async-executed.tmp');