From 6975dd14253e936509e2a68b293101fa234e53af Mon Sep 17 00:00:00 2001
From: Wassim Chegham <github@wassim.dev>
Date: Thu, 9 Jun 2022 12:23:40 +0200
Subject: [PATCH] doc: add code examples to node test runner

PR-URL: https://github.com/nodejs/node/pull/43359
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Akhil Marsonya <akhil.marsonya27@gmail.com>
Reviewed-By: Harshitha K P <harshitha014@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
 doc/api/test.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 43 insertions(+)

diff --git a/doc/api/test.md b/doc/api/test.md
index 7513dc24e26afd..52620899191142 100644
--- a/doc/api/test.md
+++ b/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