From aa7d4e59f715abedeb5f1a7bfcaff9b368699fa3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Wed, 20 Jul 2022 17:40:43 +0200 Subject: [PATCH] doc: improve test runner timeout docs Add a warning to clarify that it is not a reliable mechanism for cancelling tests. Fix the default value of the timeout option. Simplify and capitalize the YAML description field. PR-URL: https://github.com/nodejs/node/pull/43836 Reviewed-By: Antoine du Hamel Reviewed-By: Colin Ihrig --- doc/api/test.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/api/test.md b/doc/api/test.md index ac433d5dd2ab13..2708324b1dc253 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -323,7 +323,7 @@ added: v18.0.0 changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/43505 - description: add a timeout to tests and allow setting it in options. + description: Add a `timeout` option. --> * `name` {string} The name of the test, which is displayed when reporting test @@ -346,7 +346,7 @@ changes: the test is `TODO`. **Default:** `false`. * `timeout` {number} A number of milliseconds the test will fail after. If unspecified, subtests inherit this value from their parent. - **Default:** `30_000`. + **Default:** `Infinity`. * `fn` {Function|AsyncFunction} The function under test. The first argument to this function is a [`TestContext`][] object. If the test uses callbacks, the callback function is passed as the second argument. **Default:** A no-op @@ -379,6 +379,11 @@ test('top level test', async (t) => { }); ``` +The `timeout` option can be used to fail the test if it takes longer than +`timeout` milliseconds to complete. However, it is not a reliable mechanism for +canceling tests because a running test might block the application thread and +thus prevent the scheduled cancellation. + ## `describe([name][, options][, fn])` * `name` {string} The name of the suite, which is displayed when reporting test @@ -545,7 +550,7 @@ added: v18.0.0 changes: - version: REPLACEME pr-url: https://github.com/nodejs/node/pull/43505 - description: add a timeout to tests and allow setting it in options. + description: Add a `timeout` option. --> * `name` {string} The name of the subtest, which is displayed when reporting @@ -567,7 +572,7 @@ changes: the test is `TODO`. **Default:** `false`. * `timeout` {number} A number of milliseconds the test will fail after. If unspecified, subtests inherit this value from their parent. - **Default:** `30_000`. + **Default:** `Infinity`. * `fn` {Function|AsyncFunction} The function under test. The first argument to this function is a [`TestContext`][] object. If the test uses callbacks, the callback function is passed as the second argument. **Default:** A no-op