test_runner: add getTestContext()

PR-URL: #62501
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Chemi Atlow <chemi@atlow.co.il>

Author: MoLow

doc/api/test.md

@@ -3675,6 +3675,44 @@ Emitted when no more tests are queued for execution in watch mode.
 
 Emitted when one or more tests are restarted due to a file change in watch mode.
 
+## `getTestContext()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {TestContext|SuiteContext|undefined}
+
+Returns the [`TestContext`][] or [`SuiteContext`][] object associated with the
+currently executing test or suite, or `undefined` if called outside of a test or
+suite. This function can be used to access context information from within the
+test or suite function or any async operations within them.
+
+```mjs
+import { getTestContext } from'node:test';
+
+test('example test', async () => {
+constctx=getTestContext();
+console.log(`Running test: ${ctx.name}`);
+});
+
+describe('example suite', () => {
+constctx=getTestContext();
+console.log(`Running suite: ${ctx.name}`);
+});
+```
+
+When called from a test, returns a [`TestContext`][].
+When called from a suite, returns a [`SuiteContext`][].
+
+If called from outside a test or suite (e.g., at the top level of a module or in
+a setTimeout callback after execution has completed), this function returns
+`undefined`.
+
+When called from within a hook (before, beforeEach, after, afterEach), this
+function returns the context of the test or suite that the hook is associated
+with.
+
 ## Test instrumentation and OpenTelemetry
 
 <!-- YAML

lib/internal/test_runner/harness.js

@@ -21,7 +21,7 @@ const {
 },
 }=require('internal/errors');
 const{exitCodes: { kGenericUserError }}=internalBinding('errors');
-const{ kCancelledByParent, Test, Suite }=require('internal/test_runner/test');
+const{ kCancelledByParent, Test, Suite, TestContext, SuiteContext}=require('internal/test_runner/test');
 const{
  parseCommandLine,
  reporterScope,
@@ -431,8 +431,27 @@ function hook(hook) {
 };
 }
 
+functiongetTestContext(){
+consttest=testResources.get(executionAsyncId());
+// Exclude the reporter sentinel
+if(test===undefined||test===reporterScope){
+returnundefined;
+}
+// For hooks (hookType is set), return the test/suite being hooked (the parent)
+constactualTest=test.hookType!==undefined ? test.parent : test;
+if(actualTest===undefined){
+returnundefined;
+}
+// Return SuiteContext for suites, TestContext for tests
+if(actualTestinstanceofSuite){
+returnnewSuiteContext(actualTest);
+}
+returnnewTestContext(actualTest);
+}
+
 module.exports={
  createTestTree,
+ getTestContext,
 test: runInParentContext(Test),
 suite: runInParentContext(Suite),
 before: hook('before'),

lib/internal/test_runner/test.js

@@ -1831,4 +1831,6 @@ module.exports = {
  kUnwrapErrors,
  Suite,
  Test,
+ TestContext,
+ SuiteContext,
 };

lib/test.js

@@ -5,7 +5,7 @@ const {
  ObjectDefineProperty,
 }=primordials;
 
-const{ test, suite, before, after, beforeEach, afterEach }=require('internal/test_runner/harness');
+const{ test, suite, before, after, beforeEach, afterEach, getTestContext}=require('internal/test_runner/harness');
 const{ run }=require('internal/test_runner/runner');
 
 module.exports=test;
@@ -15,6 +15,7 @@ ObjectAssign(module.exports, {
  before,
  beforeEach,
 describe: suite,
+ getTestContext,
 it: test,
  run,
  suite,

test/parallel/test-runner-get-test-context.js

@@ -0,0 +1,54 @@
+'use strict';
+require('../common');
+constassert=require('node:assert');
+const{ test, getTestContext, describe, it }=require('node:test');
+
+// Outside a test — must return undefined
+assert.strictEqual(getTestContext(),undefined);
+
+test('getTestContext returns current context inside test',async()=>{
+constctx=getTestContext();
+assert.ok(ctx!==undefined);
+assert.strictEqual(ctx.name,'getTestContext returns current context inside test');
+assert.strictEqual(typeofctx.signal,'object');
+assert.strictEqual(typeofctx.fullName,'string');
+});
+
+test('getTestContext works in nested test',async(t)=>{
+awaitt.test('child',async()=>{
+constctx=getTestContext();
+assert.ok(ctx!==undefined);
+assert.strictEqual(ctx.name,'child');
+});
+});
+
+describe('getTestContext works in describe/it',()=>{
+it('has correct name',()=>{
+constctx=getTestContext();
+assert.ok(ctx!==undefined);
+assert.strictEqual(ctx.name,'has correct name');
+});
+});
+
+describe('getTestContext returns SuiteContext in suite',()=>{
+it('suite context is available',()=>{
+constctx=getTestContext();
+assert.ok(ctx!==undefined);
+// Suite name appears as parent in nested test context
+assert.strictEqual(typeofctx.signal,'object');
+assert.strictEqual(typeofctx.fullName,'string');
+});
+});
+
+test('getTestContext works in test body during async operations',async(t)=>{
+constctx=getTestContext();
+assert.ok(ctx!==undefined);
+assert.strictEqual(ctx.name,'getTestContext works in test body during async operations');
+
+// Also works in nested async context
+constctxInSetImmediate=awaitnewPromise((resolve)=>{
+setImmediate(()=>resolve(getTestContext()));
+});
+assert.ok(ctxInSetImmediate!==undefined);
+assert.strictEqual(ctxInSetImmediate.name,'getTestContext works in test body during async operations');
+});

tools/doc/type-parser.mjs

@@ -252,6 +252,8 @@ const customTypesMap = {
 'Timer': 'timers.html#timers',
 
 'TestsStream': 'test.html#class-testsstream',
+'TestContext': 'test.html#class-testcontext',
+'SuiteContext': 'test.html#class-suitecontext',
 
 'tls.SecureContext': 'tls.html#tlscreatesecurecontextoptions',
 'tls.Server': 'tls.html#class-tlsserver',