Node.js Reference ยท util, assert and the Test Runner
Subtests in the Node.js test runner
Reference for subtests in node:test: nest tests with t.test(), generate tests in a loop, control concurrency, share setup and understand how failures bubble up.
A subtest is a test created inside another test by calling t.test() on the test context. The outer test becomes the parent: it passes only when its own function finishes without error and all of its subtests pass. A failing subtest does not stop its siblings, and the report shows the tree.
Subtests are the dynamic counterpart of describe() and it(). Because you call them from running code, you can create them in a loop, from a table of cases, or after an earlier step has produced the data they need.
import { test } from 'node:test'; test('math', async (t) => { await t.test('addition', () => {}); await t.test('subtraction', () => {}); });
How subtests behave
Each call to t.test(name, options, fn) returns a promise, resolved with undefined when that subtest finishes (the promise reports completion, not a result). Await it when the next step depends on the subtest or when you want sequential, readable code. Subtests that are not awaited are still run and still counted by the parent, in the order they were created.
By default a parent runs its subtests one at a time. Set concurrency on the parent test to run them in parallel: true means as many as the number of CPU cores, a number sets an exact limit.
A subtest has the same context as any test, so it can have its own subtests, hooks, mocks, skip, todo and plan. Hooks registered on the parent with t.beforeEach() run around each subtest, after any beforeEach hooks declared in enclosing suites or at file level.
Try it
The helper writes a test file and runs it with run(). Results are printed indented by depth, children before their parent.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Syntax
t.test([name][, options][, fn]) // returns Promise<void>
| Name | Description |
|---|---|
name |
Display name. Defaults to the function name or '<anonymous>'. |
options |
The same options as test(): skip, todo, only, timeout, concurrency, signal, plan. |
fn |
(t, done) => any, where t is the context of the subtest. |
Returns: a promise that settles when the subtest has finished. It resolves even if the subtest failed; the failure is recorded in the report and fails the parent.
Useful context members: t.name (the subtest's own name), t.fullName (parent names joined), t.signal, t.plan(), t.beforeEach(), t.afterEach(), t.before(), t.after().
Usage notes
- Await your subtests. Not awaiting works for pure subtests, but the parent function may finish and read results too early. A loop with
await t.test()is the clearest style. - Use a different parameter name for each level (
t,t1,t2), so a subtest cannot accidentally use its parent's context. - Name subtests from data. In a loop, include the input in the name, as in the first example. Identical names make failures hard to find.
- The parent fails when a subtest fails. The error on the parent says how many subtests failed; the actual assertion message is on the subtest.
plancounts subtests.test('x', { plan: 2 }, ...)passes when exactly two subtests (ort.assertcalls) happen.- Parent code after the subtests still runs. An assertion after a failed
await t.test()still executes, because the returned promise resolves instead of rejecting. - Choose
describefor fixed structure. If every test is known when the file loads, describe() and it() read better and get better file-level reporting.