diff options
Diffstat (limited to 'doc/api/test.md')
| -rw-r--r-- | doc/api/test.md | 56 |
1 files changed, 56 insertions, 0 deletions
diff --git a/doc/api/test.md b/doc/api/test.md index 86cd1447633..9ce8b731a46 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -148,6 +148,42 @@ test('skip() method with message', (t) => { }); ``` +### `only` tests + +If Node.js is started with the [`--test-only`][] command-line option, it is +possible to skip all top level tests except for a selected subset by passing +the `only` option to the tests that should be run. When a test with the `only` +option set is run, all subtests are also run. The test context's `runOnly()` +method can be used to implement the same behavior at the subtest level. + +```js +// Assume Node.js is run with the --test-only command-line option. +// The 'only' option is set, so this test is run. +test('this test is run', { only: true }, async (t) => { + // Within this test, all subtests are run by default. + await t.test('running subtest'); + + // The test context can be updated to run subtests with the 'only' option. + t.runOnly(true); + await t.test('this subtest is now skipped'); + await t.test('this subtest is run', { only: true }); + + // Switch the context back to execute all tests. + t.runOnly(false); + await t.test('this subtest is now run'); + + // Explicitly do not run these tests. + await t.test('skipped subtest 3', { only: false }); + await t.test('skipped subtest 4', { skip: true }); +}); + +// The 'only' option is not set, so this test is skipped. +test('this test is not run', () => { + // This code is not run. + throw new Error('fail'); +}); +``` + ## Extraneous asynchronous activity Once a test function finishes executing, the TAP results are output as quickly @@ -197,6 +233,9 @@ added: REPLACEME * `concurrency` {number} The number of tests that can be run at the same time. If unspecified, subtests inherit this value from their parent. **Default:** `1`. + * `only` {boolean} If truthy, and the test context is configured to run + `only` tests, then this test will be run. Otherwise, the test is skipped. + **Default:** `false`. * `skip` {boolean|string} If truthy, the test is skipped. If a string is provided, that string is displayed in the test results as the reason for skipping the test. **Default:** `false`. @@ -257,6 +296,19 @@ This function is used to write TAP diagnostics to the output. Any diagnostic information is included at the end of the test's results. This function does not return a value. +### `context.runOnly(shouldRunOnlyTests)` + +<!-- YAML +added: REPLACEME +--> + +* `shouldRunOnlyTests` {boolean} Whether or not to run `only` tests. + +If `shouldRunOnlyTests` is truthy, the test context will only run tests that +have the `only` option set. Otherwise, all tests are run. If Node.js was not +started with the [`--test-only`][] command-line option, this function is a +no-op. + ### `context.skip([message])` <!-- YAML @@ -296,6 +348,9 @@ added: REPLACEME * `concurrency` {number} The number of tests that can be run at the same time. If unspecified, subtests inherit this value from their parent. **Default:** `1`. + * `only` {boolean} If truthy, and the test context is configured to run + `only` tests, then this test will be run. Otherwise, the test is skipped. + **Default:** `false`. * `skip` {boolean|string} If truthy, the test is skipped. If a string is provided, that string is displayed in the test results as the reason for skipping the test. **Default:** `false`. @@ -312,5 +367,6 @@ This function is used to create subtests under the current test. This function behaves in the same fashion as the top level [`test()`][] function. [TAP]: https://testanything.org/ +[`--test-only`]: cli.md#--test-only [`TestContext`]: #class-testcontext [`test()`]: #testname-options-fn |