From a74e0f31d5f4810625bd37f0f287653b46296c8d Mon Sep 17 00:00:00 2001 From: Mohamed Ahmed Date: Sat, 14 Nov 2026 20:55:37 +0200 Subject: [PATCH] doc: introduce suites section in test runner documentation Introduce a concise Suites section before Subtests in doc/api/test.md to explain how suite() groups tests and automatically waits for nested tests and suites to complete. Fixes: https://github.com/nodejs/node/issues/60758 Signed-off-by: Mohamed Ahmed Assisted-by: Antigravity --- doc/api/test.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/api/test.md b/doc/api/test.md index db530c609add..b67b0a846573 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -94,6 +94,35 @@ test('callback failing test', (t, done) => { If any tests fail, the process exit code is set to `1`. +## Suites + +The [`suite()`][] function groups related tests and nested suites together. +The suite callback receives a [`SuiteContext`][] object and registers any +nested [`test()`][] or [`suite()`][] calls declared within it. + +```js +suite('math operations', () => { + test('addition', () => { + assert.strictEqual(1 + 1, 2); + }); + + suite('multiplication', () => { + test('negative one', () => { + assert.strictEqual(2 * -1, -2); + }); + + test('zero', () => { + assert.strictEqual(2 * 0, 0); + }); + }); +}); +``` + +Unlike [`test()`][], `suite()` always waits for all of its nested tests and +suites to finish before completing, so nested tests do not need to be +awaited. A suite does not make assertions of its own; it passes if all of +its nested tests and suites pass, and fails if any of them throw or fail. + ## Subtests The test context's `test()` method allows subtests to be created.