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()).
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.
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
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):
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
onlyneeds only mode. Without the--test-onlyflag (oronly: trueinrun()),onlymarkers are ignored and every test runs, as the first line of the second example shows. This is deliberate: a forgottenonlydoes 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.
onlyand subtests. A parent markedonlyruns, but its subtests all run unless the parent callst.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
truegives no explanation. todoresults 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 areturnas in the first example.- Name patterns accept strings (converted to regular expressions) or
RegExpobjects. 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
onlychoose tests, not files. Use file arguments or glob patterns to choose files.