From 2c8957789a6f593654535f704e52d28ea4ae9449 Mon Sep 17 00:00:00 2001
From: Rawal27 <obviouslykamal@gmail.com>
Date: Fri, 31 Jul 2026 16:34:00 +0530
Subject: [PATCH 1/3] doc: clarify TestContext lifecycle and hook execution
 order

Signed-off-by: Rawal27 <obviouslykamal@gmail.com>
---
 doc/api/test.md | 41 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

diff --git a/doc/api/test.md b/doc/api/test.md
index cfbb350e1584..76976001d2ba 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -4078,6 +4078,47 @@ An instance of `TestContext` is passed to each test function in order to
 interact with the test runner. However, the `TestContext` constructor is not
 exposed as part of the API.
 
+### TestContext lifecycle
+
+A new `TestContext` instance is created for every test execution.
+
+The context remains available throughout the execution of the test, including
+its associated hooks.
+
+Each subtest receives its own independent `TestContext` instance,
+rather than sharing the parent's context.
+
+### Example
+
+```mjs
+import test from 'node:test';
+
+test('parent', async (t) => {
+  console.log(`Parent: ${t.name}`);
+
+  await t.test('child', (t) => {
+    console.log(`Child: ${t.name}`);
+  });
+});
+```
+
+In this example, the parent test and the subtest each receive their own
+`TestContext` instance.
+
+### Execution order
+
+When hooks are registered on a test that contains subtests, they execute in
+the following order for each subtest:
+
+1. `before`
+2. `beforeEach`
+3. subtest execution
+4. `afterEach`
+5. `after`
+
+When multiple hooks of the same type are registered, they execute in
+registration order.
+
 ### `context.before([fn][, options])`
 
 <!-- YAML

From cc6c8ad7a56ba6bce5ba9d3d1c86be4f78d75dca Mon Sep 17 00:00:00 2001
From: Rawal27 <obviouslykamal@gmail.com>
Date: Fri, 31 Jul 2026 16:53:06 +0530
Subject: [PATCH 2/3] test: ssh signing


From 17b19c50c4b92ff4ec253f0936428729134943e0 Mon Sep 17 00:00:00 2001
From: Rawal27 <obviouslykamal@gmail.com>
Date: Fri, 31 Jul 2026 22:16:25 +0530
Subject: [PATCH 3/3] doc: improve TestContext example

Signed-off-by: Rawal27 <obviouslykamal@gmail.com>
---
 doc/api/test.md | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/doc/api/test.md b/doc/api/test.md
index 76976001d2ba..1a453a1dc515 100644
--- a/doc/api/test.md
+++ b/doc/api/test.md
@@ -4091,13 +4091,12 @@ rather than sharing the parent's context.
 ### Example
 
 ```mjs
+import assert from 'node:assert/strict';
 import test from 'node:test';
 
-test('parent', async (t) => {
-  console.log(`Parent: ${t.name}`);
-
-  await t.test('child', (t) => {
-    console.log(`Child: ${t.name}`);
+test('parent', async (parentContext) => {
+  await parentContext.test('child', (childContext) => {
+    assert.notStrictEqual(parentContext, childContext);
   });
 });
 ```