From c23ee359abc2a606bbda25bef4dc6ca14128903e Mon Sep 17 00:00:00 2001 From: Marco Ippolito Date: Sun, 7 Jan 2024 11:32:17 +0100 Subject: [PATCH] doc: improve subtests documentation PR-URL: https://github.com/nodejs/node/pull/51379 Fixes: https://github.com/nodejs/node/issues/51359 Reviewed-By: Benjamin Gruenbaum Reviewed-By: Luigi Pinca Reviewed-By: Moshe Atlow --- doc/api/test.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/doc/api/test.md b/doc/api/test.md index fc5b8ecdd2bd29..c60a07e6ad40bb 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -105,9 +105,12 @@ If any tests fail, the process exit code is set to `1`. ## Subtests -The test context's `test()` method allows subtests to be created. This method -behaves identically to the top level `test()` function. The following example -demonstrates the creation of a top level test with two subtests. +The test context's `test()` method allows subtests to be created. +It allows you to structure your tests in a hierarchical manner, +where you can create nested tests within a larger test. +This method behaves identically to the top level `test()` function. +The following example demonstrates the creation of a +top level test with two subtests. ```js test('top level test', async (t) => { @@ -121,9 +124,13 @@ test('top level test', async (t) => { }); ``` +> **Note:** `beforeEach` and `afterEach` hooks are triggered +> between each subtest execution. + In this example, `await` is used to ensure that both subtests have completed. This is necessary because parent tests do not wait for their subtests to -complete. Any subtests that are still outstanding when their parent finishes +complete, unlike tests created with the `describe` and `it` syntax. +Any subtests that are still outstanding when their parent finishes are cancelled and treated as failures. Any subtest failures cause the parent test to fail.