doc: add code examples to node test runner

PR-URL: #43359
Reviewed-By: Benjamin Gruenbaum <[email protected]>
Reviewed-By: Colin Ihrig <[email protected]>
Reviewed-By: Akhil Marsonya <[email protected]>
Reviewed-By: Harshitha K P <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>
Reviewed-By: James M Snell <[email protected]>
Reviewed-By: Franziska Hinkelmann <[email protected]>
Reviewed-By: Rich Trott <[email protected]>
Co-authored-by: Antoine du Hamel <[email protected]>

Author: 2 people

doc/api/test.md

@@ -357,6 +357,12 @@ This function is used to write TAP diagnostics to the output. Any diagnostic
 information is included at the end of the test's results. This function does
 not return a value.
 
+```js
+test('top level test', (t) => {
+  t.diagnostic('A diagnostic message');
+});
+```
+
 ### `context.runOnly(shouldRunOnlyTests)`
 
 <!-- YAML
@@ -370,6 +376,17 @@ have the `only` option set. Otherwise, all tests are run. If Node.js was not
 started with the [`--test-only`][] command-line option, this function is a
 no-op.
 
+```js
+test('top level test', (t) => {
+  // The test context can be set to run subtests with the 'only' option.
+  t.runOnly(true);
+  return Promise.all([
+    t.test('this subtest is now skipped'),
+    t.test('this subtest is run', { only: true }),
+  ]);
+});
+```
+
 ### `context.skip([message])`
 
 <!-- YAML
@@ -383,6 +400,13 @@ This function causes the test's output to indicate the test as skipped. If
 not terminate execution of the test function. This function does not return a
 value.
 
+```js
+test('top level test', (t) => {
+  // Make sure to return here as well if the test contains additional logic.
+  t.skip('this is skipped');
+});
+```
+
 ### `context.todo([message])`
 
 <!-- YAML
@@ -395,6 +419,13 @@ This function adds a `TODO` directive to the test's output. If `message` is
 provided, it is included in the TAP output. Calling `todo()` does not terminate
 execution of the test function. This function does not return a value.
 
+```js
+test('top level test', (t) => {
+  // This test is marked as `TODO`
+  t.todo('this is a todo');
+});
+```
+
 ### `context.test([name][, options][, fn])`
 
 <!-- YAML
@@ -427,6 +458,18 @@ added: v18.0.0
 This function is used to create subtests under the current test. This function
 behaves in the same fashion as the top level [`test()`][] function.
 
+```js
+test('top level test', async (t) => {
+  await t.test(
+    'This is a subtest',
+    { only: false, skip: false, concurrency: 1, todo: false },
+    (t) => {
+      assert.ok('some relevant assertion here');
+    }
+  );
+});
+```
+
 [TAP]: https://testanything.org/
 [`--test-only`]: cli.md#--test-only
 [`--test`]: cli.md#--test