diff --git a/doc/api/test.md b/doc/api/test.md index b12e6c9212af3b..5b44d5efde8ee5 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -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 @@ -193,6 +165,68 @@ When the `--test-rerun-failures` option is used, the test runner will only run t node --test-rerun-failures /path/to/state/file ``` +## `describe()` and `it()` aliases + +Suites and tests can also be written using the `describe()` and `it()` +functions. [`describe()`][] is an alias for [`suite()`][], and [`it()`][] is an +alias for [`test()`][]. + +```js +describe('A thing', () => { + it('should work', () => { + assert.strictEqual(1, 1); + }); + + it('should be ok', () => { + assert.strictEqual(2, 2); + }); + + describe('a nested thing', () => { + it('should work', () => { + assert.strictEqual(3, 3); + }); + }); +}); +``` + +`describe()` and `it()` are imported from the `node:test` module. + +```mjs +import { describe, it } from 'node:test'; +``` + +```cjs +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` @@ -275,40 +309,6 @@ it.todo('should do the thing', { expectFailure: true }, () => { }); ``` -## `describe()` and `it()` aliases - -Suites and tests can also be written using the `describe()` and `it()` -functions. [`describe()`][] is an alias for [`suite()`][], and [`it()`][] is an -alias for [`test()`][]. - -```js -describe('A thing', () => { - it('should work', () => { - assert.strictEqual(1, 1); - }); - - it('should be ok', () => { - assert.strictEqual(2, 2); - }); - - describe('a nested thing', () => { - it('should work', () => { - assert.strictEqual(3, 3); - }); - }); -}); -``` - -`describe()` and `it()` are imported from the `node:test` module. - -```mjs -import { describe, it } from 'node:test'; -``` - -```cjs -const { describe, it } = require('node:test'); -``` - ## `only` tests If Node.js is started with the [`--test-only`][] command-line option, or test