-
-
Notifications
You must be signed in to change notification settings - Fork 33.8k
doc: add detailed explanation of suites and their behavior in the test runner #60765
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Conversation
|
Review requested:
|
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
good start.
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
looking good. I'd like this to get some more input from other test_runner maintainers too.
| }); | ||
| ``` | ||
|
|
||
| **Suites vs. Subtests** |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| **Suites vs. Subtests** | |
| ### Suites vs. Subtests |
| Suites provide a way to group related tests under a common name. A suite | ||
| is created with the `suite()` function (or its alias `describe()`). The | ||
| callback passed to `suite()` is executed synchronously and is used only | ||
| to register nested tests or nested suites. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| to register nested tests or nested suites. | |
| to register lifecycle methods (such as `before()` and `after()`), nested tests, or nested suites. |
| to register nested tests or nested suites. | ||
|
|
||
| A suite reports a result, but its status is fully determined by the | ||
| tests and suites inside it --- suites cannot fail independently. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| tests and suites inside it --- suites cannot fail independently. | |
| tests and suites inside it - suites cannot fail independently. |
| ``` js | ||
| import { suite, test } from 'node:test'; | ||
| import assert from 'node:assert'; | ||
| suite('math operations', () => { | ||
| test('addition', () => { | ||
| assert.strictEqual(1 + 1, 2); | ||
| }); | ||
| test('multiplication', () => { | ||
| assert.strictEqual(2 * 2, 4); | ||
| }); | ||
| }); | ||
| ``` | ||
|
|
||
| ``` js | ||
| suite('user features', () => { | ||
| suite('profile', () => { | ||
| test('updates display name', () => { | ||
| assert.ok(true); | ||
| }); | ||
| }); | ||
| suite('settings', () => { | ||
| test('enables notifications', () => { | ||
| assert.ok(true); | ||
| }); | ||
| }); | ||
| }); | ||
| ``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Lets simplify this example to demonstrate everything in one code block.
| ``` js | |
| import { suite, test } from 'node:test'; | |
| import assert from 'node:assert'; | |
| suite('math operations', () => { | |
| test('addition', () => { | |
| assert.strictEqual(1 + 1, 2); | |
| }); | |
| test('multiplication', () => { | |
| assert.strictEqual(2 * 2, 4); | |
| }); | |
| }); | |
| ``` | |
| ``` js | |
| suite('user features', () => { | |
| suite('profile', () => { | |
| test('updates display name', () => { | |
| assert.ok(true); | |
| }); | |
| }); | |
| suite('settings', () => { | |
| test('enables notifications', () => { | |
| assert.ok(true); | |
| }); | |
| }); | |
| }); | |
| ``` | |
| ```js | |
| import { suite, test } from 'node:test'; | |
| import assert from 'node:assert'; | |
| 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); | |
| }); | |
| }); | |
| }); | |
| ``` |
| | Feature | Suite (`suite()`) | Subtest (`t.test()`) | | ||
| |-------------------------------------------|---------------------------------------------------------------------------------------------|----------------------------------------------| | ||
| | Parent waits for children | Always | Only if awaited | | ||
| | Pending children canceled if parent ends | No, unless the suite is canceled via `AbortSignal` | Yes | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What is another way to cancel the parent suite and the subtests continue to execute?
| | Callback controls execution order | No — tests execute strictly in declaration order; the suite callback cannot pause execution | Yes — execution order controlled via `await` | | ||
|
|
||
|
|
||
| *Suite example* |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| *Suite example* | |
| ### Suite example |
|
|
||
| The suite finishes only after both tests complete. | ||
|
|
||
| *Subtest example* |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| *Subtest example* | |
| ### Subtest example |
Summary
This PR adds a dedicated Suites section to the
node:testdocumentation.The existing docs reference suites (for example, in the Subtests section) without explaining what they are or how they differ from tests with subtests. This addition fills that gap and clarifies suite behavior.
What This PR Adds
suite()/describe()) and subtests (t.test())describe()is an alias ofsuite()Why This Is Needed
Related Issue
Fixes: #60758