diff --git a/doc/api/test.md b/doc/api/test.md index 2014981613f..a0236c31f79 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -3381,13 +3381,17 @@ added: The name of the test. -### `context.plan(count)` +### `context.plan(count[,options])` * `count` {number} The number of assertions and subtests that are expected to run. +* `options` {Object} Additional options for the plan. + * `wait` {boolean|number} The wait time for the plan: + * If `true`, the plan waits indefinitely for all assertions and subtests to run. + * If `false`, the plan performs an immediate check after the test function completes, + without waiting for any pending assertions or subtests. + Any assertions or subtests that complete after this check will not be counted towards the plan. + * If a number, it specifies the maximum wait time in milliseconds + before timing out while waiting for expected assertions and subtests to be matched. + If the timeout is reached, the test will fail. + **Default:** `false`. This function is used to set the number of assertions and subtests that are expected to run within the test. If the number of assertions and subtests that run does not match the @@ -3434,6 +3448,26 @@ test('planning with streams', (t, done) => { }); ``` +When using the `wait` option, you can control how long the test will wait for the expected assertions. +For example, setting a maximum wait time ensures that the test will wait for asynchronous assertions +to complete within the specified timeframe: + +```js +test('plan with wait: 2000 waits for async assertions', (t) => { + t.plan(1, { wait: 2000 }); // Waits for up to 2 seconds for the assertion to complete. + + const asyncActivity = () => { + setTimeout(() => { + t.assert.ok(true, 'Async assertion completed within the wait time'); + }, 1000); // Completes after 1 second, within the 2-second wait time. + }; + + asyncActivity(); // The test will pass because the assertion is completed in time. +}); +``` + +Note: If a `wait` timeout is specified, it begins counting down only after the test function finishes executing. + ### `context.runOnly(shouldRunOnlyTests)`