Skip to content

doc: move describe/it aliases section before expectFailure #61567

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nodejs-github-bot merged 2 commits into from
Feb 9, 2026
Merged

doc: move describe/it aliases section before expectFailure #61567

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c1db7d
doc: move describe/it aliases section before expectFailure
lraveri Jan 28, 2026
a51ac28
doc: group test runner flag options in documentation
lraveri Jan 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
doc: group test runner flag options in documentation 
Signed-off-by: Luca Raveri <lucaraveri993@gmail.com>
  • Loading branch information
@lraveri
lraveri committed Jan 29, 2026
commit a51ac280277bd0b65036f082794fe71e4fc75b0e
118 changes: 59 additions & 59 deletions doc/api/test.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,34 +125,6 @@ Any subtests that are still outstanding when their parent finishes
are cancelled and treated as failures. Any subtest failures cause the parent
test to fail.

## Skipping tests

Individual tests can be skipped by passing the `skip` option to the test, or by
calling the test context's `skip()` method as shown in the
following example.

```js
// The skip option is used, but no message is provided.
test('skip option', { skip: true }, (t) => {
// This code is never executed.
});

// The skip option is used, and a message is provided.
test('skip option with message', { skip: 'this is skipped' }, (t) => {
// This code is never executed.
});

test('skip() method', (t) => {
// Make sure to return here as well if the test contains additional logic.
t.skip();
});

test('skip() method with message', (t) => {
// Make sure to return here as well if the test contains additional logic.
t.skip('this is skipped');
});
```

## Rerunning failed tests

The test runner supports persisting the state of the run to a file, allowing
Expand Down Expand Up @@ -193,37 +165,6 @@ When the `--test-rerun-failures` option is used, the test runner will only run t
node --test-rerun-failures /path/to/state/file
```

## TODO tests

Individual tests can be marked as flaky or incomplete by passing the `todo`
option to the test, or by calling the test context's `todo()` method, as shown
in the following example. These tests represent a pending implementation or bug
that needs to be fixed. TODO tests are executed, but are not treated as test
failures, and therefore do not affect the process exit code. If a test is marked
as both TODO and skipped, the TODO option is ignored.

```js
// The todo option is used, but no message is provided.
test('todo option', { todo: true }, (t) => {
// This code is executed, but not treated as a failure.
throw new Error('this does not fail the test');
});

// The todo option is used, and a message is provided.
test('todo option with message', { todo: 'this is a todo test' }, (t) => {
// This code is executed.
});

test('todo() method', (t) => {
t.todo();
});

test('todo() method with message', (t) => {
t.todo('this is a todo test and is not treated as a failure');
throw new Error('this does not fail the test');
});
```

## `describe()` and `it()` aliases

Suites and tests can also be written using the `describe()` and `it()`
Expand Down Expand Up @@ -258,6 +199,65 @@ import { describe, it } from 'node:test';
const { describe, it } = require('node:test');
```

## Skipping tests

Individual tests can be skipped by passing the `skip` option to the test, or by
calling the test context's `skip()` method as shown in the
following example.

```js
// The skip option is used, but no message is provided.
test('skip option', { skip: true }, (t) => {
// This code is never executed.
});

// The skip option is used, and a message is provided.
test('skip option with message', { skip: 'this is skipped' }, (t) => {
// This code is never executed.
});

test('skip() method', (t) => {
// Make sure to return here as well if the test contains additional logic.
t.skip();
});

test('skip() method with message', (t) => {
// Make sure to return here as well if the test contains additional logic.
t.skip('this is skipped');
});
```

## TODO tests

Individual tests can be marked as flaky or incomplete by passing the `todo`
option to the test, or by calling the test context's `todo()` method, as shown
in the following example. These tests represent a pending implementation or bug
that needs to be fixed. TODO tests are executed, but are not treated as test
failures, and therefore do not affect the process exit code. If a test is marked
as both TODO and skipped, the TODO option is ignored.

```js
// The todo option is used, but no message is provided.
test('todo option', { todo: true }, (t) => {
// This code is executed, but not treated as a failure.
throw new Error('this does not fail the test');
});

// The todo option is used, and a message is provided.
test('todo option with message', { todo: 'this is a todo test' }, (t) => {
// This code is executed.
});

test('todo() method', (t) => {
t.todo();
});

test('todo() method with message', (t) => {
t.todo('this is a todo test and is not treated as a failure');
throw new Error('this does not fail the test');
});
```

## Expecting tests to fail

<!-- YAML
Expand Down
Loading