From a747163e040a7fd24fa0a32e660de9a24d8f30e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Thu, 14 Jul 2022 22:17:32 +0000 Subject: [PATCH 1/2] 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. --- 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 5970106e11da3e..83e0bfc385877c 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 @@ -345,7 +345,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:** `undefined`. * `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 @@ -378,6 +378,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 @@ -529,7 +534,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 @@ -551,7 +556,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:** `undefined`. * `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 From 1ad03cc553f5588edd1f6934448bbd83fe667d8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Fri, 15 Jul 2022 22:30:15 +0200 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Antoine du Hamel --- doc/api/test.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/test.md b/doc/api/test.md index 83e0bfc385877c..762d13bf820e0b 100644 --- a/doc/api/test.md +++ b/doc/api/test.md @@ -345,7 +345,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:** `undefined`. + **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 @@ -556,7 +556,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:** `undefined`. + **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