Node.js Reference ยท util, assert and the Test Runner
Node.js describe() and it() functions (node:test)
Reference for describe() and it() in node:test: group tests into suites, nest suites, use skip, todo and only, and understand how they relate to test().
describe() creates a suite: a named group of tests. it() defines a test inside it. Both come from node:test and follow the style many JavaScript developers know from Mocha and Jasmine. They are not a separate engine: it is an alias of test, and describe is an alias of suite, a test whose only job is to hold other tests and hooks.
Suites give the report an indented structure, let you share setup with before() and beforeEach(), and let you skip, mark or focus a whole group with one option.
import { describe, it } from 'node:test'; import assert from 'node:assert/strict'; describe('Array.prototype.at', () => { it('counts from the end for negative indexes', () => { assert.equal([1, 2, 3].at(-1), 3); }); });
Try it
The helper below writes a test file and runs it with run(), printing each result indented by nesting depth (children are listed before their parent, because a suite finishes after its tests). The text inside the backtick string is the test file.
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
describe([name][, options][, fn]) describe.skip([name][, options][, fn]) describe.todo([name][, options][, fn]) describe.only([name][, options][, fn]) it([name][, options][, fn]) // same as test() it.skip(...) it.todo(...) it.only(...)
| Name | Description |
|---|---|
name |
Name of the suite or test. Defaults to the function's name or '<anonymous>'. |
options |
Same as for test(): skip, todo, only, timeout, concurrency, signal. |
fn |
For describe: a function that defines tests and hooks (it receives a suite context). For it: the test body (t, done) => any. |
Returns: a promise (Promise<void>) that resolves when the suite has finished. At the top level of a file you usually ignore it.
Usage notes
- The describe callback runs immediately, tests run later. Code placed directly inside
describe()executes while the suite is being defined, not while tests run. Put setup inbefore()orbeforeEach(), not as loose statements, if it must happen at test time. - Do not put assertions directly in
describe. They run at definition time and a throw there fails the suite itself rather than a test. - Options on a suite apply downward.
describe.skipskips every test in it. Give individual tests their owntimeoutwhen they need a time limit. - Tests inside one suite run one after another by default, in the order they were defined. Set
concurrencyon the suite to run them in parallel only when they share no state. - State is shared. In the first example the second test sees the items added by the first. Reset state in
beforeEach()if tests must be independent. describeanditversustestwith subtests. Usedescribeanditfor a static, declarative structure. Uset.test()(see Subtests) when you generate tests in a loop or need the parent test to do work around its children.- Mocha globals are not provided. You must import
describeanditfromnode:test; they are not global variables.