Skip to content

Conversation

@algowizzz
Copy link

Summary

This PR adds a dedicated Suites section to the node:test documentation.
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

  • A new “Suites” section covering:
    • What a suite is and how it works
    • Synchronous callback behavior when registering tests
    • How suites wait for all nested tests/suites
    • How suite results depend entirely on their children
  • Examples of suites and nested suites
  • A comparison table between suites (suite() / describe()) and subtests (t.test())
  • Clarification that describe() is an alias of suite()

Why This Is Needed

  • The documentation references suites without defining them.
  • Developers transitioning from Mocha/Jest often assume different semantics.
  • Suites and subtests look similar but behave differently in important ways (async behavior, execution order, cancellation).
  • This makes the test runner easier to understand and reduces confusion.

Related Issue

Fixes: #60758

@nodejs-github-bot
Copy link
Collaborator

Review requested:

  • @nodejs/test_runner

@nodejs-github-bot nodejs-github-bot added doc Issues and PRs related to the documentations. test_runner Issues and PRs related to the test runner subsystem. labels Nov 18, 2025
Copy link
Contributor

@Ethan-Arrowood Ethan-Arrowood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

good start.

Copy link
Contributor

@Ethan-Arrowood Ethan-Arrowood left a 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**
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
**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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
tests and suites inside it --- suites cannot fail independently.
tests and suites inside it - suites cannot fail independently.

Comment on lines +142 to +168
``` 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);
});
});
});
```
Copy link
Contributor

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.

Suggested change
``` 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 |
Copy link
Contributor

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*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
*Suite example*
### Suite example


The suite finishes only after both tests complete.

*Subtest example*
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
*Subtest example*
### Subtest example

@feyzanurgok30-lab

This comment was marked as spam.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Issues and PRs related to the documentations. test_runner Issues and PRs related to the test runner subsystem.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Test Runner docs could use more information on the concept of a Suite

4 participants