Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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.

Node.js A suite with nested suites

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.

Node.js describe and it are aliases of suite and test

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

NODE
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 in before() or beforeEach(), 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.skip skips every test in it. Give individual tests their own timeout when they need a time limit.
  • Tests inside one suite run one after another by default, in the order they were defined. Set concurrency on 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.
  • describe and it versus test with subtests. Use describe and it for a static, declarative structure. Use t.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 describe and it from node:test; they are not global variables.