Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท util, assert and the Test Runner

Node.js test hooks: before(), after(), beforeEach(), afterEach()

Reference for node:test hooks before(), after(), beforeEach() and afterEach(): setup and teardown order, async hooks, failures and per-test hooks on t.

Hooks are functions the test runner calls around your tests. before() runs once before the first test of its suite, after() runs once after the last one, beforeEach() runs before every test in the suite and afterEach() runs after every test. They are the place to open a temporary file or a server, reset shared state, and clean up.

A hook belongs to the suite (or file, or test) it is declared in. Hooks declared outside any describe() apply to the whole file, including tests inside nested suites.

NODE
import { describe, it, before, after } from 'node:test';

describe('database tests', () => {
  before(() => { /* connect */ });
  after(() => { /* disconnect */ });
  it('queries rows', () => {});
});

Try it

Node.js The order hooks and tests run in

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 Async hooks, per-test state and a failing setup

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
before(fn[, options])
after(fn[, options])
beforeEach(fn[, options])
afterEach(fn[, options])

// on a test context t (apply to its subtests):
t.before(fn[, options])  t.after(fn[, options])
t.beforeEach(fn[, options])  t.afterEach(fn[, options])
Name Description
fn (context, done) => any. May be synchronous, return a promise, or call done(). For beforeEach and afterEach the context describes the test about to run (or just run); for before and after it is the suite.
options.signal An AbortSignal that can cancel the hook.
options.timeout Milliseconds before the hook is treated as failed. Default Infinity.

Returns: undefined.

Order. For a test inside nested suites: before hooks of outer suites run first, then beforeEach from the outermost to the innermost suite, then the test, then afterEach hooks from the innermost outward. after hooks run once when the suite is finished.

Usage notes

  • after and afterEach still run when a test fails. That is what makes them the right place for cleanup. Do not put cleanup at the end of the test body, where a thrown error skips it.
  • A failing before hook fails the suite. The tests inside are reported as cancelled with the message that they did not finish before their parent, but after hooks still run.
  • A failing beforeEach fails the test it was running for. Fix hook errors first: every test of the suite is affected, so one broken hook can look like many failures.
  • File-level hooks apply to everything. A beforeEach() at the top of a file, outside any describe(), runs before every test and subtest in that file. That is convenient for resetting mocks, but easy to forget.
  • Async hooks. Return a promise or use done, like tests; do not do both.
  • Share state through variables, not through this. Declare let db; in the suite and assign it in before(). Arrow functions have no suite-specific this.
  • t.beforeEach() and friends register hooks for the subtests of one test. See Subtests.
  • Mock restoration does not need a hook when you use t.mock, because mocks created on a test context are restored when that test ends.