Skip to content
Tutorials Center
My learning

Topics

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

skip, todo and only in the Node.js test runner

Reference for skip, todo and only in node:test: skip tests with a reason, mark known failures as todo, focus tests with only and filter by name pattern.

node:test has three markers that change how a test is treated without deleting it. skip means "do not run this". todo means "run it, but do not fail the build if it fails". only means "run just the tests marked this way". Name patterns from the command line or from run() add a fourth way to select tests from outside the code.

All markers can be set three ways: as an option ({ skip: true }), with a shortcut method (test.skip(), it.todo(), describe.only()), or from inside the test with the context (t.skip(), t.todo()).

NODE
test('later', { todo: 'needs a design' }, () => {});
test.skip('not on this platform', () => {});
test('focused', { only: true }, () => {});

Try it

The helper writes a test file, runs it with run() and prints one line per test (indented by depth). Anything the tests print with console.log is listed after the report.

Node.js Skip and todo

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 Only and name patterns

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
test(name, { skip: true | 'reason' }, fn)
test(name, { todo: true | 'reason' }, fn)
test(name, { only: true }, fn)
test.skip(name, fn)    test.todo(name, fn)    test.only(name, fn)
describe.skip(...)     describe.todo(...)     describe.only(...)
it.skip(...)           it.todo(...)           it.only(...)
t.skip([reason])       t.todo([reason])       t.runOnly(shouldRun)

Command line (read-only, run in your own terminal):

Terminal
node --test --test-only                          # honor only: true
node --test --test-name-pattern="parser"         # run tests whose name matches
node --test --test-skip-pattern="slow"           # leave out tests whose name matches
Marker Test code runs? Counts as failure when it throws? Typical use
skip No No Platform-specific tests, tests that need a service
todo Yes No A known bug, a feature in progress
only Only marked tests run (in only mode) Yes Focusing on one test while debugging

Usage notes

  • only needs only mode. Without the --test-only flag (or only: true in run()), only markers are ignored and every test runs, as the first line of the second example shows. This is deliberate: a forgotten only does not silently hide tests in CI unless CI also uses the flag.
  • Only mode skips unmarked tests entirely. They are not run and are not listed as passed.
  • only and subtests. A parent marked only runs, but its subtests all run unless the parent calls t.runOnly(true), which switches the parent to only mode for its own subtests.
  • Skip reasons show up in reports. Pass a string so people know why. A plain true gives no explanation.
  • todo results are still printed. A failing todo test appears in the report with its error but does not change the exit code. A todo test that passes is a hint that the marker can go.
  • t.skip() does not stop the function. It only marks the result; the function keeps running until it returns, so add a return as in the first example.
  • Name patterns accept strings (converted to regular expressions) or RegExp objects. They match the full name of the test, including its parents' names. A test skipped by a pattern is not reported, and a skip pattern wins over a name pattern.
  • Test files are not filtered. Patterns and only choose tests, not files. Use file arguments or glob patterns to choose files.