From a747163e040a7fd24fa0a32e660de9a24d8f30e3 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= <tniessen@tnie.de>
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?= <tniessen@tnie.de>
Date: Fri, 15 Jul 2022 22:30:15 +0200
Subject: [PATCH 2/2] Apply suggestions from code review
Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
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