@rio-cloud/cdk-v2-constructs 8.2.0-alpha.0 → 8.2.1-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (179) hide show
  1. package/.jsii +2 -2
  2. package/node_modules/@types/node/README.md +3 -3
  3. package/node_modules/@types/node/assert/strict.d.ts +105 -2
  4. package/node_modules/@types/node/assert.d.ts +211 -92
  5. package/node_modules/@types/node/async_hooks.d.ts +103 -19
  6. package/node_modules/@types/node/buffer.buffer.d.ts +472 -0
  7. package/node_modules/@types/node/buffer.d.ts +88 -516
  8. package/node_modules/@types/node/child_process.d.ts +167 -231
  9. package/node_modules/@types/node/cluster.d.ts +172 -26
  10. package/node_modules/@types/node/compatibility/iterators.d.ts +21 -0
  11. package/node_modules/@types/node/console.d.ts +66 -28
  12. package/node_modules/@types/node/constants.d.ts +14 -12
  13. package/node_modules/@types/node/crypto.d.ts +1458 -497
  14. package/node_modules/@types/node/dgram.d.ts +44 -30
  15. package/node_modules/@types/node/diagnostics_channel.d.ts +389 -4
  16. package/node_modules/@types/node/dns/promises.d.ts +120 -42
  17. package/node_modules/@types/node/dns.d.ts +209 -95
  18. package/node_modules/@types/node/domain.d.ts +14 -18
  19. package/node_modules/@types/node/events.d.ts +245 -113
  20. package/node_modules/@types/node/fs/promises.d.ts +194 -96
  21. package/node_modules/@types/node/fs.d.ts +695 -270
  22. package/node_modules/@types/node/globals.d.ts +97 -308
  23. package/node_modules/@types/node/globals.typedarray.d.ts +41 -0
  24. package/node_modules/@types/node/http.d.ts +363 -97
  25. package/node_modules/@types/node/http2.d.ts +684 -231
  26. package/node_modules/@types/node/https.d.ts +122 -87
  27. package/node_modules/@types/node/index.d.ts +24 -11
  28. package/node_modules/@types/node/inspector.d.ts +220 -2690
  29. package/node_modules/@types/node/inspector.generated.d.ts +4239 -0
  30. package/node_modules/@types/node/module.d.ts +705 -149
  31. package/node_modules/@types/node/net.d.ts +178 -54
  32. package/node_modules/@types/node/os.d.ts +47 -17
  33. package/node_modules/@types/node/package.json +22 -97
  34. package/node_modules/@types/node/path.d.ts +12 -3
  35. package/node_modules/@types/node/perf_hooks.d.ts +500 -97
  36. package/node_modules/@types/node/process.d.ts +657 -87
  37. package/node_modules/@types/node/punycode.d.ts +5 -5
  38. package/node_modules/@types/node/querystring.d.ts +24 -13
  39. package/node_modules/@types/node/readline/promises.d.ts +25 -14
  40. package/node_modules/@types/node/readline.d.ts +102 -41
  41. package/node_modules/@types/node/repl.d.ts +38 -30
  42. package/node_modules/@types/node/sea.d.ts +162 -0
  43. package/node_modules/@types/node/sqlite.d.ts +1040 -0
  44. package/node_modules/@types/node/stream/consumers.d.ts +33 -7
  45. package/node_modules/@types/node/stream/promises.d.ts +8 -1
  46. package/node_modules/@types/node/stream/web.d.ts +251 -28
  47. package/node_modules/@types/node/stream.d.ts +1060 -1055
  48. package/node_modules/@types/node/string_decoder.d.ts +8 -8
  49. package/node_modules/@types/node/test.d.ts +2133 -1166
  50. package/node_modules/@types/node/timers/promises.d.ts +31 -16
  51. package/node_modules/@types/node/timers.d.ts +159 -114
  52. package/node_modules/@types/node/tls.d.ts +232 -163
  53. package/node_modules/@types/node/trace_events.d.ts +43 -28
  54. package/node_modules/@types/node/ts5.6/buffer.buffer.d.ts +468 -0
  55. package/node_modules/@types/node/ts5.6/compatibility/float16array.d.ts +71 -0
  56. package/node_modules/@types/node/ts5.6/globals.typedarray.d.ts +36 -0
  57. package/node_modules/@types/node/ts5.6/index.d.ts +103 -0
  58. package/node_modules/@types/node/ts5.7/compatibility/float16array.d.ts +72 -0
  59. package/node_modules/@types/node/ts5.7/index.d.ts +103 -0
  60. package/node_modules/@types/node/tty.d.ts +9 -9
  61. package/node_modules/@types/node/url.d.ts +236 -84
  62. package/node_modules/@types/node/util.d.ts +562 -412
  63. package/node_modules/@types/node/v8.d.ts +368 -21
  64. package/node_modules/@types/node/vm.d.ts +443 -149
  65. package/node_modules/@types/node/wasi.d.ts +62 -18
  66. package/node_modules/@types/node/web-globals/abortcontroller.d.ts +34 -0
  67. package/node_modules/@types/node/web-globals/crypto.d.ts +32 -0
  68. package/node_modules/@types/node/web-globals/domexception.d.ts +68 -0
  69. package/node_modules/@types/node/web-globals/events.d.ts +97 -0
  70. package/node_modules/@types/node/web-globals/fetch.d.ts +62 -0
  71. package/node_modules/@types/node/web-globals/navigator.d.ts +25 -0
  72. package/node_modules/@types/node/web-globals/storage.d.ts +24 -0
  73. package/node_modules/@types/node/web-globals/streams.d.ts +22 -0
  74. package/node_modules/@types/node/worker_threads.d.ts +310 -107
  75. package/node_modules/@types/node/zlib.d.ts +301 -73
  76. package/node_modules/undici-types/LICENSE +21 -0
  77. package/node_modules/undici-types/agent.d.ts +13 -12
  78. package/node_modules/undici-types/api.d.ts +26 -26
  79. package/node_modules/undici-types/balanced-pool.d.ts +19 -7
  80. package/node_modules/undici-types/cache-interceptor.d.ts +173 -0
  81. package/node_modules/undici-types/client-stats.d.ts +15 -0
  82. package/node_modules/undici-types/client.d.ts +26 -15
  83. package/node_modules/undici-types/connector.d.ts +2 -2
  84. package/node_modules/undici-types/cookies.d.ts +2 -0
  85. package/node_modules/undici-types/diagnostics-channel.d.ts +19 -12
  86. package/node_modules/undici-types/dispatcher.d.ts +148 -113
  87. package/node_modules/undici-types/env-http-proxy-agent.d.ts +22 -0
  88. package/node_modules/undici-types/errors.d.ts +79 -46
  89. package/node_modules/undici-types/eventsource.d.ts +66 -0
  90. package/node_modules/undici-types/fetch.d.ts +41 -39
  91. package/node_modules/undici-types/formdata.d.ts +8 -8
  92. package/node_modules/undici-types/global-dispatcher.d.ts +4 -4
  93. package/node_modules/undici-types/global-origin.d.ts +5 -5
  94. package/node_modules/undici-types/h2c-client.d.ts +73 -0
  95. package/node_modules/undici-types/handlers.d.ts +11 -5
  96. package/node_modules/undici-types/header.d.ts +157 -1
  97. package/node_modules/undici-types/index.d.ts +68 -43
  98. package/node_modules/undici-types/interceptors.d.ts +71 -3
  99. package/node_modules/undici-types/mock-agent.d.ts +36 -18
  100. package/node_modules/undici-types/mock-call-history.d.ts +111 -0
  101. package/node_modules/undici-types/mock-client.d.ts +6 -4
  102. package/node_modules/undici-types/mock-errors.d.ts +3 -3
  103. package/node_modules/undici-types/mock-interceptor.d.ts +24 -23
  104. package/node_modules/undici-types/mock-pool.d.ts +6 -4
  105. package/node_modules/undici-types/package.json +1 -1
  106. package/node_modules/undici-types/patch.d.ts +0 -42
  107. package/node_modules/undici-types/pool-stats.d.ts +8 -8
  108. package/node_modules/undici-types/pool.d.ts +21 -8
  109. package/node_modules/undici-types/proxy-agent.d.ts +5 -6
  110. package/node_modules/undici-types/readable.d.ts +24 -17
  111. package/node_modules/undici-types/retry-agent.d.ts +8 -0
  112. package/node_modules/undici-types/retry-handler.d.ts +125 -0
  113. package/node_modules/undici-types/round-robin-pool.d.ts +41 -0
  114. package/node_modules/undici-types/snapshot-agent.d.ts +109 -0
  115. package/node_modules/undici-types/util.d.ts +18 -0
  116. package/node_modules/undici-types/utility.d.ts +7 -0
  117. package/node_modules/undici-types/webidl.d.ts +157 -36
  118. package/node_modules/undici-types/websocket.d.ts +67 -12
  119. package/package.json +9 -60
  120. package/version.json +1 -1
  121. package/node_modules/@types/node/dom-events.d.ts +0 -122
  122. package/node_modules/@types/node/globals.global.d.ts +0 -1
  123. package/node_modules/@types/node/ts4.8/assert/strict.d.ts +0 -8
  124. package/node_modules/@types/node/ts4.8/assert.d.ts +0 -996
  125. package/node_modules/@types/node/ts4.8/async_hooks.d.ts +0 -539
  126. package/node_modules/@types/node/ts4.8/buffer.d.ts +0 -2362
  127. package/node_modules/@types/node/ts4.8/child_process.d.ts +0 -1540
  128. package/node_modules/@types/node/ts4.8/cluster.d.ts +0 -432
  129. package/node_modules/@types/node/ts4.8/console.d.ts +0 -415
  130. package/node_modules/@types/node/ts4.8/constants.d.ts +0 -19
  131. package/node_modules/@types/node/ts4.8/crypto.d.ts +0 -4455
  132. package/node_modules/@types/node/ts4.8/dgram.d.ts +0 -586
  133. package/node_modules/@types/node/ts4.8/diagnostics_channel.d.ts +0 -191
  134. package/node_modules/@types/node/ts4.8/dns/promises.d.ts +0 -425
  135. package/node_modules/@types/node/ts4.8/dns.d.ts +0 -809
  136. package/node_modules/@types/node/ts4.8/dom-events.d.ts +0 -122
  137. package/node_modules/@types/node/ts4.8/domain.d.ts +0 -170
  138. package/node_modules/@types/node/ts4.8/events.d.ts +0 -796
  139. package/node_modules/@types/node/ts4.8/fs/promises.d.ts +0 -1232
  140. package/node_modules/@types/node/ts4.8/fs.d.ts +0 -4289
  141. package/node_modules/@types/node/ts4.8/globals.d.ts +0 -381
  142. package/node_modules/@types/node/ts4.8/globals.global.d.ts +0 -1
  143. package/node_modules/@types/node/ts4.8/http.d.ts +0 -1888
  144. package/node_modules/@types/node/ts4.8/http2.d.ts +0 -2382
  145. package/node_modules/@types/node/ts4.8/https.d.ts +0 -550
  146. package/node_modules/@types/node/ts4.8/index.d.ts +0 -88
  147. package/node_modules/@types/node/ts4.8/inspector.d.ts +0 -2747
  148. package/node_modules/@types/node/ts4.8/module.d.ts +0 -287
  149. package/node_modules/@types/node/ts4.8/net.d.ts +0 -949
  150. package/node_modules/@types/node/ts4.8/os.d.ts +0 -477
  151. package/node_modules/@types/node/ts4.8/path.d.ts +0 -191
  152. package/node_modules/@types/node/ts4.8/perf_hooks.d.ts +0 -639
  153. package/node_modules/@types/node/ts4.8/process.d.ts +0 -1532
  154. package/node_modules/@types/node/ts4.8/punycode.d.ts +0 -117
  155. package/node_modules/@types/node/ts4.8/querystring.d.ts +0 -141
  156. package/node_modules/@types/node/ts4.8/readline/promises.d.ts +0 -150
  157. package/node_modules/@types/node/ts4.8/readline.d.ts +0 -539
  158. package/node_modules/@types/node/ts4.8/repl.d.ts +0 -430
  159. package/node_modules/@types/node/ts4.8/stream/consumers.d.ts +0 -12
  160. package/node_modules/@types/node/ts4.8/stream/promises.d.ts +0 -83
  161. package/node_modules/@types/node/ts4.8/stream/web.d.ts +0 -350
  162. package/node_modules/@types/node/ts4.8/stream.d.ts +0 -1701
  163. package/node_modules/@types/node/ts4.8/string_decoder.d.ts +0 -67
  164. package/node_modules/@types/node/ts4.8/test.d.ts +0 -1382
  165. package/node_modules/@types/node/ts4.8/timers/promises.d.ts +0 -93
  166. package/node_modules/@types/node/ts4.8/timers.d.ts +0 -240
  167. package/node_modules/@types/node/ts4.8/tls.d.ts +0 -1210
  168. package/node_modules/@types/node/ts4.8/trace_events.d.ts +0 -182
  169. package/node_modules/@types/node/ts4.8/tty.d.ts +0 -208
  170. package/node_modules/@types/node/ts4.8/url.d.ts +0 -927
  171. package/node_modules/@types/node/ts4.8/util.d.ts +0 -2186
  172. package/node_modules/@types/node/ts4.8/v8.d.ts +0 -635
  173. package/node_modules/@types/node/ts4.8/vm.d.ts +0 -901
  174. package/node_modules/@types/node/ts4.8/wasi.d.ts +0 -158
  175. package/node_modules/@types/node/ts4.8/worker_threads.d.ts +0 -691
  176. package/node_modules/@types/node/ts4.8/zlib.d.ts +0 -517
  177. package/node_modules/argparse/CHANGELOG.md +0 -216
  178. package/node_modules/undici-types/file.d.ts +0 -39
  179. package/node_modules/undici-types/filereader.d.ts +0 -54
@@ -10,7 +10,7 @@
10
10
  * work:
11
11
  *
12
12
  * ```js
13
- * import test from 'test';
13
+ * import test from 'node:test';
14
14
  * ```
15
15
  *
16
16
  * Tests created via the `test` module consist of a single function that is
@@ -18,14 +18,14 @@
18
18
  *
19
19
  * 1. A synchronous function that is considered failing if it throws an exception,
20
20
  * and is considered passing otherwise.
21
- * 2. A function that returns a `Promise` that is considered failing if the`Promise` rejects, and is considered passing if the `Promise` resolves.
21
+ * 2. A function that returns a `Promise` that is considered failing if the `Promise` rejects, and is considered passing if the `Promise` fulfills.
22
22
  * 3. A function that receives a callback function. If the callback receives any
23
23
  * truthy value as its first argument, the test is considered failing. If a
24
24
  * falsy value is passed as the first argument to the callback, the test is
25
25
  * considered passing. If the test function receives a callback function and
26
26
  * also returns a `Promise`, the test will fail.
27
27
  *
28
- * The following example illustrates how tests are written using the`test` module.
28
+ * The following example illustrates how tests are written using the `test` module.
29
29
  *
30
30
  * ```js
31
31
  * test('synchronous passing test', (t) => {
@@ -40,7 +40,7 @@
40
40
  *
41
41
  * test('asynchronous passing test', async (t) => {
42
42
  * // This test passes because the Promise returned by the async
43
- * // function is not rejected.
43
+ * // function is settled and not rejected.
44
44
  * assert.strictEqual(1, 1);
45
45
  * });
46
46
  *
@@ -76,26 +76,14 @@
76
76
  *
77
77
  * If any tests fail, the process exit code is set to `1`.
78
78
  * @since v18.0.0, v16.17.0
79
- * @see [source](https://github.com/nodejs/node/blob/v20.4.0/lib/test.js)
79
+ * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/test.js)
80
80
  */
81
81
  declare module "node:test" {
82
+ import { AssertMethodNames } from "node:assert";
82
83
  import { Readable } from "node:stream";
83
- import { AsyncResource } from "node:async_hooks";
84
- /**
85
- * ```js
86
- * import { tap } from 'node:test/reporters';
87
- * import { run } from 'node:test';
88
- * import process from 'node:process';
89
- * import path from 'node:path';
90
- *
91
- * run({ files: [path.resolve('./tests/test.js')] })
92
- * .compose(tap)
93
- * .pipe(process.stdout);
94
- * ```
95
- * @since v18.9.0, v16.19.0
96
- * @param options Configuration options for running tests. The following properties are supported:
97
- */
98
- function run(options?: RunOptions): TestsStream;
84
+ import { URL } from "node:url";
85
+ import TestFn = test.TestFn;
86
+ import TestOptions = test.TestOptions;
99
87
  /**
100
88
  * The `test()` function is the value imported from the `test` module. Each
101
89
  * invocation of this function results in reporting the test to the `TestsStream`.
@@ -104,8 +92,8 @@ declare module "node:test" {
104
92
  * actions related to the current test. Examples include skipping the test, adding
105
93
  * additional diagnostic information, or creating subtests.
106
94
  *
107
- * `test()` returns a `Promise` that resolves once the test completes.
108
- * if `test()` is called within a `describe()` block, it resolve immediately.
95
+ * `test()` returns a `Promise` that fulfills once the test completes.
96
+ * if `test()` is called within a suite, it fulfills immediately.
109
97
  * The return value can usually be discarded for top level tests.
110
98
  * However, the return value from subtests should be used to prevent the parent
111
99
  * test from finishing first and cancelling the subtest
@@ -124,1205 +112,2159 @@ declare module "node:test" {
124
112
  * });
125
113
  * ```
126
114
  *
127
- * 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
115
+ * 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
128
116
  * canceling tests because a running test might block the application thread and
129
117
  * thus prevent the scheduled cancellation.
130
118
  * @since v18.0.0, v16.17.0
131
- * @param [name='The name'] The name of the test, which is displayed when reporting test results.
132
- * @param options Configuration options for the test. The following properties are supported:
133
- * @param [fn='A no-op function'] The function under test. The first argument to this function is a {@link TestContext} object. If the test uses callbacks, the callback function is passed as the
134
- * second argument.
135
- * @return Resolved with `undefined` once the test completes, or immediately if the test runs within {@link describe}.
119
+ * @param name The name of the test, which is displayed when reporting test results.
120
+ * Defaults to the `name` property of `fn`, or `'<anonymous>'` if `fn` does not have a name.
121
+ * @param options Configuration options for the test.
122
+ * @param fn The function under test. The first argument to this function is a {@link TestContext} object.
123
+ * If the test uses callbacks, the callback function is passed as the second argument.
124
+ * @return Fulfilled with `undefined` once the test completes, or immediately if the test runs within a suite.
136
125
  */
137
126
  function test(name?: string, fn?: TestFn): Promise<void>;
138
127
  function test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
139
128
  function test(options?: TestOptions, fn?: TestFn): Promise<void>;
140
129
  function test(fn?: TestFn): Promise<void>;
141
130
  namespace test {
142
- export { after, afterEach, before, beforeEach, describe, it, mock, only, run, skip, test, todo };
131
+ export { test };
132
+ export { suite as describe, test as it };
143
133
  }
144
- /**
145
- * The `describe()` function imported from the `node:test` module. Each
146
- * invocation of this function results in the creation of a Subtest.
147
- * After invocation of top level `describe` functions,
148
- * all top level tests and suites will execute.
149
- * @param [name='The name'] The name of the suite, which is displayed when reporting test results.
150
- * @param options Configuration options for the suite. supports the same options as `test([name][, options][, fn])`.
151
- * @param [fn='A no-op function'] The function under suite declaring all subtests and subsuites. The first argument to this function is a {@link SuiteContext} object.
152
- * @return Immediately fulfilled with `undefined`.
153
- */
154
- function describe(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
155
- function describe(name?: string, fn?: SuiteFn): Promise<void>;
156
- function describe(options?: TestOptions, fn?: SuiteFn): Promise<void>;
157
- function describe(fn?: SuiteFn): Promise<void>;
158
- namespace describe {
159
- /**
160
- * Shorthand for skipping a suite, same as `describe([name], { skip: true }[, fn])`.
161
- */
162
- function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
163
- function skip(name?: string, fn?: SuiteFn): Promise<void>;
164
- function skip(options?: TestOptions, fn?: SuiteFn): Promise<void>;
165
- function skip(fn?: SuiteFn): Promise<void>;
166
- /**
167
- * Shorthand for marking a suite as `TODO`, same as `describe([name], { todo: true }[, fn])`.
168
- */
169
- function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
170
- function todo(name?: string, fn?: SuiteFn): Promise<void>;
171
- function todo(options?: TestOptions, fn?: SuiteFn): Promise<void>;
172
- function todo(fn?: SuiteFn): Promise<void>;
173
- /**
174
- * Shorthand for marking a suite as `only`, same as `describe([name], { only: true }[, fn])`.
175
- * @since v18.15.0
176
- */
177
- function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
178
- function only(name?: string, fn?: SuiteFn): Promise<void>;
179
- function only(options?: TestOptions, fn?: SuiteFn): Promise<void>;
180
- function only(fn?: SuiteFn): Promise<void>;
181
- }
182
- /**
183
- * Shorthand for `test()`.
184
- *
185
- * The `it()` function is imported from the `node:test` module.
186
- * @since v18.6.0, v16.17.0
187
- */
188
- function it(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
189
- function it(name?: string, fn?: TestFn): Promise<void>;
190
- function it(options?: TestOptions, fn?: TestFn): Promise<void>;
191
- function it(fn?: TestFn): Promise<void>;
192
- namespace it {
134
+ namespace test {
193
135
  /**
194
- * Shorthand for skipping a test, same as `it([name], { skip: true }[, fn])`.
136
+ * **Note:** `shard` is used to horizontally parallelize test running across
137
+ * machines or processes, ideal for large-scale executions across varied
138
+ * environments. It's incompatible with `watch` mode, tailored for rapid
139
+ * code iteration by automatically rerunning tests on file changes.
140
+ *
141
+ * ```js
142
+ * import { tap } from 'node:test/reporters';
143
+ * import { run } from 'node:test';
144
+ * import process from 'node:process';
145
+ * import path from 'node:path';
146
+ *
147
+ * run({ files: [path.resolve('./tests/test.js')] })
148
+ * .compose(tap)
149
+ * .pipe(process.stdout);
150
+ * ```
151
+ * @since v18.9.0, v16.19.0
152
+ * @param options Configuration options for running tests.
153
+ */
154
+ function run(options?: RunOptions): TestsStream;
155
+ /**
156
+ * The `suite()` function is imported from the `node:test` module.
157
+ * @param name The name of the suite, which is displayed when reporting test results.
158
+ * Defaults to the `name` property of `fn`, or `'<anonymous>'` if `fn` does not have a name.
159
+ * @param options Configuration options for the suite. This supports the same options as {@link test}.
160
+ * @param fn The suite function declaring nested tests and suites. The first argument to this function is a {@link SuiteContext} object.
161
+ * @return Immediately fulfilled with `undefined`.
162
+ * @since v20.13.0
163
+ */
164
+ function suite(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
165
+ function suite(name?: string, fn?: SuiteFn): Promise<void>;
166
+ function suite(options?: TestOptions, fn?: SuiteFn): Promise<void>;
167
+ function suite(fn?: SuiteFn): Promise<void>;
168
+ namespace suite {
169
+ /**
170
+ * Shorthand for skipping a suite. This is the same as calling {@link suite} with `options.skip` set to `true`.
171
+ * @since v20.13.0
172
+ */
173
+ function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
174
+ function skip(name?: string, fn?: SuiteFn): Promise<void>;
175
+ function skip(options?: TestOptions, fn?: SuiteFn): Promise<void>;
176
+ function skip(fn?: SuiteFn): Promise<void>;
177
+ /**
178
+ * Shorthand for marking a suite as `TODO`. This is the same as calling {@link suite} with `options.todo` set to `true`.
179
+ * @since v20.13.0
180
+ */
181
+ function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
182
+ function todo(name?: string, fn?: SuiteFn): Promise<void>;
183
+ function todo(options?: TestOptions, fn?: SuiteFn): Promise<void>;
184
+ function todo(fn?: SuiteFn): Promise<void>;
185
+ /**
186
+ * Shorthand for marking a suite as `only`. This is the same as calling {@link suite} with `options.only` set to `true`.
187
+ * @since v20.13.0
188
+ */
189
+ function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
190
+ function only(name?: string, fn?: SuiteFn): Promise<void>;
191
+ function only(options?: TestOptions, fn?: SuiteFn): Promise<void>;
192
+ function only(fn?: SuiteFn): Promise<void>;
193
+ }
194
+ /**
195
+ * Shorthand for skipping a test. This is the same as calling {@link test} with `options.skip` set to `true`.
196
+ * @since v20.2.0
195
197
  */
196
198
  function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
197
199
  function skip(name?: string, fn?: TestFn): Promise<void>;
198
200
  function skip(options?: TestOptions, fn?: TestFn): Promise<void>;
199
201
  function skip(fn?: TestFn): Promise<void>;
200
202
  /**
201
- * Shorthand for marking a test as `TODO`, same as `it([name], { todo: true }[, fn])`.
203
+ * Shorthand for marking a test as `TODO`. This is the same as calling {@link test} with `options.todo` set to `true`.
204
+ * @since v20.2.0
202
205
  */
203
206
  function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
204
207
  function todo(name?: string, fn?: TestFn): Promise<void>;
205
208
  function todo(options?: TestOptions, fn?: TestFn): Promise<void>;
206
209
  function todo(fn?: TestFn): Promise<void>;
207
210
  /**
208
- * Shorthand for marking a test as `only`, same as `it([name], { only: true }[, fn])`.
209
- * @since v18.15.0
211
+ * Shorthand for marking a test as `only`. This is the same as calling {@link test} with `options.only` set to `true`.
212
+ * @since v20.2.0
210
213
  */
211
214
  function only(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
212
215
  function only(name?: string, fn?: TestFn): Promise<void>;
213
216
  function only(options?: TestOptions, fn?: TestFn): Promise<void>;
214
217
  function only(fn?: TestFn): Promise<void>;
215
- }
216
- /**
217
- * Shorthand for skipping a test, same as `test([name], { skip: true }[, fn])`.
218
- * @since v20.2.0
219
- */
220
- function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
221
- function skip(name?: string, fn?: TestFn): Promise<void>;
222
- function skip(options?: TestOptions, fn?: TestFn): Promise<void>;
223
- function skip(fn?: TestFn): Promise<void>;
224
- /**
225
- * Shorthand for marking a test as `TODO`, same as `test([name], { todo: true }[, fn])`.
226
- * @since v20.2.0
227
- */
228
- function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
229
- function todo(name?: string, fn?: TestFn): Promise<void>;
230
- function todo(options?: TestOptions, fn?: TestFn): Promise<void>;
231
- function todo(fn?: TestFn): Promise<void>;
232
- /**
233
- * Shorthand for marking a test as `only`, same as `test([name], { only: true }[, fn])`.
234
- * @since v20.2.0
235
- */
236
- function only(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
237
- function only(name?: string, fn?: TestFn): Promise<void>;
238
- function only(options?: TestOptions, fn?: TestFn): Promise<void>;
239
- function only(fn?: TestFn): Promise<void>;
240
- /**
241
- * The type of a function under test. The first argument to this function is a
242
- * {@link TestContext} object. If the test uses callbacks, the callback function is passed as
243
- * the second argument.
244
- */
245
- type TestFn = (t: TestContext, done: (result?: any) => void) => void | Promise<void>;
246
- /**
247
- * The type of a function under Suite.
248
- */
249
- type SuiteFn = (s: SuiteContext) => void | Promise<void>;
250
- interface TestShard {
251
- /**
252
- * A positive integer between 1 and `<total>` that specifies the index of the shard to run.
253
- */
254
- index: number;
255
218
  /**
256
- * A positive integer that specifies the total number of shards to split the test files to.
257
- */
258
- total: number;
259
- }
260
- interface RunOptions {
261
- /**
262
- * If a number is provided, then that many files would run in parallel.
263
- * If truthy, it would run (number of cpu cores - 1) files in parallel.
264
- * If falsy, it would only run one file at a time.
265
- * If unspecified, subtests inherit this value from their parent.
266
- * @default true
267
- */
268
- concurrency?: number | boolean | undefined;
269
- /**
270
- * An array containing the list of files to run.
271
- * If unspecified, the test runner execution model will be used.
272
- */
273
- files?: readonly string[] | undefined;
274
- /**
275
- * Allows aborting an in-progress test execution.
276
- * @default undefined
277
- */
278
- signal?: AbortSignal | undefined;
279
- /**
280
- * A number of milliseconds the test will fail after.
281
- * If unspecified, subtests inherit this value from their parent.
282
- * @default Infinity
283
- */
284
- timeout?: number | undefined;
285
- /**
286
- * Sets inspector port of test child process.
287
- * If a nullish value is provided, each process gets its own port,
288
- * incremented from the primary's `process.debugPort`.
289
- */
290
- inspectPort?: number | (() => number) | undefined;
291
- /**
292
- * That can be used to only run tests whose name matches the provided pattern.
293
- * Test name patterns are interpreted as JavaScript regular expressions.
294
- * For each test that is executed, any corresponding test hooks, such as `beforeEach()`, are also run.
295
- */
296
- testNamePatterns?: string | RegExp | string[] | RegExp[];
297
- /**
298
- * If truthy, the test context will only run tests that have the `only` option set
299
- */
300
- only?: boolean;
301
- /**
302
- * A function that accepts the TestsStream instance and can be used to setup listeners before any tests are run.
303
- */
304
- setup?: (root: Test) => void | Promise<void>;
305
- /**
306
- * Whether to run in watch mode or not.
307
- * @default false
308
- */
309
- watch?: boolean | undefined;
310
- /**
311
- * Running tests in a specific shard.
312
- * @default undefined
313
- */
314
- shard?: TestShard | undefined;
315
- }
316
- class Test extends AsyncResource {
317
- concurrency: number;
318
- nesting: number;
319
- only: boolean;
320
- reporter: TestsStream;
321
- runOnlySubtests: boolean;
322
- testNumber: number;
323
- timeout: number | null;
324
- }
325
- /**
326
- * A successful call to `run()` method will return a new `TestsStream` object, streaming a series of events representing the execution of the tests.`TestsStream` will emit events, in the
327
- * order of the tests definition
328
- * @since v18.9.0, v16.19.0
329
- */
330
- class TestsStream extends Readable implements NodeJS.ReadableStream {
331
- addListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
332
- addListener(event: "test:fail", listener: (data: TestFail) => void): this;
333
- addListener(event: "test:pass", listener: (data: TestPass) => void): this;
334
- addListener(event: "test:plan", listener: (data: TestPlan) => void): this;
335
- addListener(event: "test:start", listener: (data: TestStart) => void): this;
336
- addListener(event: "test:stderr", listener: (data: TestStderr) => void): this;
337
- addListener(event: "test:stdout", listener: (data: TestStdout) => void): this;
338
- addListener(event: string, listener: (...args: any[]) => void): this;
339
- emit(event: "test:diagnostic", data: DiagnosticData): boolean;
340
- emit(event: "test:fail", data: TestFail): boolean;
341
- emit(event: "test:pass", data: TestPass): boolean;
342
- emit(event: "test:plan", data: TestPlan): boolean;
343
- emit(event: "test:start", data: TestStart): boolean;
344
- emit(event: "test:stderr", data: TestStderr): boolean;
345
- emit(event: "test:stdout", data: TestStdout): boolean;
346
- emit(event: string | symbol, ...args: any[]): boolean;
347
- on(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
348
- on(event: "test:fail", listener: (data: TestFail) => void): this;
349
- on(event: "test:pass", listener: (data: TestPass) => void): this;
350
- on(event: "test:plan", listener: (data: TestPlan) => void): this;
351
- on(event: "test:start", listener: (data: TestStart) => void): this;
352
- on(event: "test:stderr", listener: (data: TestStderr) => void): this;
353
- on(event: "test:stdout", listener: (data: TestStdout) => void): this;
354
- on(event: string, listener: (...args: any[]) => void): this;
355
- once(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
356
- once(event: "test:fail", listener: (data: TestFail) => void): this;
357
- once(event: "test:pass", listener: (data: TestPass) => void): this;
358
- once(event: "test:plan", listener: (data: TestPlan) => void): this;
359
- once(event: "test:start", listener: (data: TestStart) => void): this;
360
- once(event: "test:stderr", listener: (data: TestStderr) => void): this;
361
- once(event: "test:stdout", listener: (data: TestStdout) => void): this;
362
- once(event: string, listener: (...args: any[]) => void): this;
363
- prependListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
364
- prependListener(event: "test:fail", listener: (data: TestFail) => void): this;
365
- prependListener(event: "test:pass", listener: (data: TestPass) => void): this;
366
- prependListener(event: "test:plan", listener: (data: TestPlan) => void): this;
367
- prependListener(event: "test:start", listener: (data: TestStart) => void): this;
368
- prependListener(event: "test:stderr", listener: (data: TestStderr) => void): this;
369
- prependListener(event: "test:stdout", listener: (data: TestStdout) => void): this;
370
- prependListener(event: string, listener: (...args: any[]) => void): this;
371
- prependOnceListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
372
- prependOnceListener(event: "test:fail", listener: (data: TestFail) => void): this;
373
- prependOnceListener(event: "test:pass", listener: (data: TestPass) => void): this;
374
- prependOnceListener(event: "test:plan", listener: (data: TestPlan) => void): this;
375
- prependOnceListener(event: "test:start", listener: (data: TestStart) => void): this;
376
- prependOnceListener(event: "test:stderr", listener: (data: TestStderr) => void): this;
377
- prependOnceListener(event: "test:stdout", listener: (data: TestStdout) => void): this;
378
- prependOnceListener(event: string, listener: (...args: any[]) => void): this;
379
- }
380
- /**
381
- * An instance of `TestContext` is passed to each test function in order to
382
- * interact with the test runner. However, the `TestContext` constructor is not
383
- * exposed as part of the API.
384
- * @since v18.0.0, v16.17.0
385
- */
386
- class TestContext {
387
- /**
388
- * This function is used to create a hook running before subtest of the current test.
389
- * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
390
- * the second argument. Default: A no-op function.
391
- * @param options Configuration options for the hook.
392
- * @since v20.1.0
393
- */
394
- before: typeof before;
395
- /**
396
- * This function is used to create a hook running before each subtest of the current test.
397
- * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
398
- * the second argument. Default: A no-op function.
399
- * @param options Configuration options for the hook.
400
- * @since v18.8.0
401
- */
402
- beforeEach: typeof beforeEach;
403
- /**
404
- * This function is used to create a hook that runs after the current test finishes.
405
- * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
406
- * the second argument. Default: A no-op function.
407
- * @param options Configuration options for the hook.
408
- * @since v18.13.0
409
- */
410
- after: typeof after;
411
- /**
412
- * This function is used to create a hook running after each subtest of the current test.
413
- * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
414
- * the second argument. Default: A no-op function.
415
- * @param options Configuration options for the hook.
416
- * @since v18.8.0
417
- */
418
- afterEach: typeof afterEach;
419
- /**
420
- * This function is used to write diagnostics to the output. Any diagnostic
421
- * information is included at the end of the test's results. This function does
422
- * not return a value.
423
- *
424
- * ```js
425
- * test('top level test', (t) => {
426
- * t.diagnostic('A diagnostic message');
427
- * });
428
- * ```
429
- * @since v18.0.0, v16.17.0
430
- * @param message Message to be reported.
431
- */
432
- diagnostic(message: string): void;
433
- /**
434
- * The name of the test.
435
- * @since v18.8.0, v16.18.0
436
- */
437
- readonly name: string;
438
- /**
439
- * If `shouldRunOnlyTests` is truthy, the test context will only run tests that
440
- * have the `only` option set. Otherwise, all tests are run. If Node.js was not
441
- * started with the `--test-only` command-line option, this function is a
442
- * no-op.
219
+ * The type of a function passed to {@link test}. The first argument to this function is a {@link TestContext} object.
220
+ * If the test uses callbacks, the callback function is passed as the second argument.
221
+ */
222
+ type TestFn = (t: TestContext, done: (result?: any) => void) => void | Promise<void>;
223
+ /**
224
+ * The type of a suite test function. The argument to this function is a {@link SuiteContext} object.
225
+ */
226
+ type SuiteFn = (s: SuiteContext) => void | Promise<void>;
227
+ interface TestShard {
228
+ /**
229
+ * A positive integer between 1 and `total` that specifies the index of the shard to run.
230
+ */
231
+ index: number;
232
+ /**
233
+ * A positive integer that specifies the total number of shards to split the test files to.
234
+ */
235
+ total: number;
236
+ }
237
+ interface RunOptions {
238
+ /**
239
+ * If a number is provided, then that many tests would run asynchronously (they are still managed by the single-threaded event loop).
240
+ * If `true`, it would run `os.availableParallelism() - 1` test files in parallel. If `false`, it would only run one test file at a time.
241
+ * @default false
242
+ */
243
+ concurrency?: number | boolean | undefined;
244
+ /**
245
+ * Specifies the current working directory to be used by the test runner.
246
+ * Serves as the base path for resolving files according to the
247
+ * [test runner execution model](https://nodejs.org/docs/latest-v24.x/api/test.html#test-runner-execution-model).
248
+ * @since v23.0.0
249
+ * @default process.cwd()
250
+ */
251
+ cwd?: string | undefined;
252
+ /**
253
+ * An array containing the list of files to run. If omitted, files are run according to the
254
+ * [test runner execution model](https://nodejs.org/docs/latest-v24.x/api/test.html#test-runner-execution-model).
255
+ */
256
+ files?: readonly string[] | undefined;
257
+ /**
258
+ * Configures the test runner to exit the process once all known
259
+ * tests have finished executing even if the event loop would
260
+ * otherwise remain active.
261
+ * @default false
262
+ */
263
+ forceExit?: boolean | undefined;
264
+ /**
265
+ * An array containing the list of glob patterns to match test files.
266
+ * This option cannot be used together with `files`. If omitted, files are run according to the
267
+ * [test runner execution model](https://nodejs.org/docs/latest-v24.x/api/test.html#test-runner-execution-model).
268
+ * @since v22.6.0
269
+ */
270
+ globPatterns?: readonly string[] | undefined;
271
+ /**
272
+ * Sets inspector port of test child process.
273
+ * This can be a number, or a function that takes no arguments and returns a
274
+ * number. If a nullish value is provided, each process gets its own port,
275
+ * incremented from the primary's `process.debugPort`. This option is ignored
276
+ * if the `isolation` option is set to `'none'` as no child processes are
277
+ * spawned.
278
+ * @default undefined
279
+ */
280
+ inspectPort?: number | (() => number) | undefined;
281
+ /**
282
+ * Configures the type of test isolation. If set to
283
+ * `'process'`, each test file is run in a separate child process. If set to
284
+ * `'none'`, all test files run in the current process.
285
+ * @default 'process'
286
+ * @since v22.8.0
287
+ */
288
+ isolation?: "process" | "none" | undefined;
289
+ /**
290
+ * If truthy, the test context will only run tests that have the `only` option set
291
+ */
292
+ only?: boolean | undefined;
293
+ /**
294
+ * A function that accepts the `TestsStream` instance and can be used to setup listeners before any tests are run.
295
+ * @default undefined
296
+ */
297
+ setup?: ((reporter: TestsStream) => void | Promise<void>) | undefined;
298
+ /**
299
+ * An array of CLI flags to pass to the `node` executable when
300
+ * spawning the subprocesses. This option has no effect when `isolation` is `'none`'.
301
+ * @since v22.10.0
302
+ * @default []
303
+ */
304
+ execArgv?: readonly string[] | undefined;
305
+ /**
306
+ * An array of CLI flags to pass to each test file when spawning the
307
+ * subprocesses. This option has no effect when `isolation` is `'none'`.
308
+ * @since v22.10.0
309
+ * @default []
310
+ */
311
+ argv?: readonly string[] | undefined;
312
+ /**
313
+ * Allows aborting an in-progress test execution.
314
+ */
315
+ signal?: AbortSignal | undefined;
316
+ /**
317
+ * If provided, only run tests whose name matches the provided pattern.
318
+ * Strings are interpreted as JavaScript regular expressions.
319
+ * @default undefined
320
+ */
321
+ testNamePatterns?: string | RegExp | ReadonlyArray<string | RegExp> | undefined;
322
+ /**
323
+ * A String, RegExp or a RegExp Array, that can be used to exclude running tests whose
324
+ * name matches the provided pattern. Test name patterns are interpreted as JavaScript
325
+ * regular expressions. For each test that is executed, any corresponding test hooks,
326
+ * such as `beforeEach()`, are also run.
327
+ * @default undefined
328
+ * @since v22.1.0
329
+ */
330
+ testSkipPatterns?: string | RegExp | ReadonlyArray<string | RegExp> | undefined;
331
+ /**
332
+ * The number of milliseconds after which the test execution will fail.
333
+ * If unspecified, subtests inherit this value from their parent.
334
+ * @default Infinity
335
+ */
336
+ timeout?: number | undefined;
337
+ /**
338
+ * Whether to run in watch mode or not.
339
+ * @default false
340
+ */
341
+ watch?: boolean | undefined;
342
+ /**
343
+ * Running tests in a specific shard.
344
+ * @default undefined
345
+ */
346
+ shard?: TestShard | undefined;
347
+ /**
348
+ * A file path where the test runner will
349
+ * store the state of the tests to allow rerunning only the failed tests on a next run.
350
+ * @since v24.7.0
351
+ * @default undefined
352
+ */
353
+ rerunFailuresFilePath?: string | undefined;
354
+ /**
355
+ * enable [code coverage](https://nodejs.org/docs/latest-v24.x/api/test.html#collecting-code-coverage) collection.
356
+ * @since v22.10.0
357
+ * @default false
358
+ */
359
+ coverage?: boolean | undefined;
360
+ /**
361
+ * Excludes specific files from code coverage
362
+ * using a glob pattern, which can match both absolute and relative file paths.
363
+ * This property is only applicable when `coverage` was set to `true`.
364
+ * If both `coverageExcludeGlobs` and `coverageIncludeGlobs` are provided,
365
+ * files must meet **both** criteria to be included in the coverage report.
366
+ * @since v22.10.0
367
+ * @default undefined
368
+ */
369
+ coverageExcludeGlobs?: string | readonly string[] | undefined;
370
+ /**
371
+ * Includes specific files in code coverage
372
+ * using a glob pattern, which can match both absolute and relative file paths.
373
+ * This property is only applicable when `coverage` was set to `true`.
374
+ * If both `coverageExcludeGlobs` and `coverageIncludeGlobs` are provided,
375
+ * files must meet **both** criteria to be included in the coverage report.
376
+ * @since v22.10.0
377
+ * @default undefined
378
+ */
379
+ coverageIncludeGlobs?: string | readonly string[] | undefined;
380
+ /**
381
+ * Require a minimum percent of covered lines. If code
382
+ * coverage does not reach the threshold specified, the process will exit with code `1`.
383
+ * @since v22.10.0
384
+ * @default 0
385
+ */
386
+ lineCoverage?: number | undefined;
387
+ /**
388
+ * Require a minimum percent of covered branches. If code
389
+ * coverage does not reach the threshold specified, the process will exit with code `1`.
390
+ * @since v22.10.0
391
+ * @default 0
392
+ */
393
+ branchCoverage?: number | undefined;
394
+ /**
395
+ * Require a minimum percent of covered functions. If code
396
+ * coverage does not reach the threshold specified, the process will exit with code `1`.
397
+ * @since v22.10.0
398
+ * @default 0
399
+ */
400
+ functionCoverage?: number | undefined;
401
+ }
402
+ /**
403
+ * A successful call to `run()` will return a new `TestsStream` object, streaming a series of events representing the execution of the tests.
443
404
  *
444
- * ```js
445
- * test('top level test', (t) => {
446
- * // The test context can be set to run subtests with the 'only' option.
447
- * t.runOnly(true);
448
- * return Promise.all([
449
- * t.test('this subtest is now skipped'),
450
- * t.test('this subtest is run', { only: true }),
451
- * ]);
452
- * });
453
- * ```
405
+ * Some of the events are guaranteed to be emitted in the same order as the tests are defined, while others are emitted in the order that the tests execute.
406
+ * @since v18.9.0, v16.19.0
407
+ */
408
+ interface TestsStream extends Readable {
409
+ addListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
410
+ addListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;
411
+ addListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
412
+ addListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
413
+ addListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
414
+ addListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
415
+ addListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
416
+ addListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
417
+ addListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;
418
+ addListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
419
+ addListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
420
+ addListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;
421
+ addListener(event: "test:watch:drained", listener: () => void): this;
422
+ addListener(event: "test:watch:restarted", listener: () => void): this;
423
+ addListener(event: string, listener: (...args: any[]) => void): this;
424
+ emit(event: "test:coverage", data: EventData.TestCoverage): boolean;
425
+ emit(event: "test:complete", data: EventData.TestComplete): boolean;
426
+ emit(event: "test:dequeue", data: EventData.TestDequeue): boolean;
427
+ emit(event: "test:diagnostic", data: EventData.TestDiagnostic): boolean;
428
+ emit(event: "test:enqueue", data: EventData.TestEnqueue): boolean;
429
+ emit(event: "test:fail", data: EventData.TestFail): boolean;
430
+ emit(event: "test:pass", data: EventData.TestPass): boolean;
431
+ emit(event: "test:plan", data: EventData.TestPlan): boolean;
432
+ emit(event: "test:start", data: EventData.TestStart): boolean;
433
+ emit(event: "test:stderr", data: EventData.TestStderr): boolean;
434
+ emit(event: "test:stdout", data: EventData.TestStdout): boolean;
435
+ emit(event: "test:summary", data: EventData.TestSummary): boolean;
436
+ emit(event: "test:watch:drained"): boolean;
437
+ emit(event: "test:watch:restarted"): boolean;
438
+ emit(event: string | symbol, ...args: any[]): boolean;
439
+ on(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
440
+ on(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;
441
+ on(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
442
+ on(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
443
+ on(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
444
+ on(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
445
+ on(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
446
+ on(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
447
+ on(event: "test:start", listener: (data: EventData.TestStart) => void): this;
448
+ on(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
449
+ on(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
450
+ on(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;
451
+ on(event: "test:watch:drained", listener: () => void): this;
452
+ on(event: "test:watch:restarted", listener: () => void): this;
453
+ on(event: string, listener: (...args: any[]) => void): this;
454
+ once(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
455
+ once(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;
456
+ once(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
457
+ once(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
458
+ once(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
459
+ once(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
460
+ once(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
461
+ once(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
462
+ once(event: "test:start", listener: (data: EventData.TestStart) => void): this;
463
+ once(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
464
+ once(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
465
+ once(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;
466
+ once(event: "test:watch:drained", listener: () => void): this;
467
+ once(event: "test:watch:restarted", listener: () => void): this;
468
+ once(event: string, listener: (...args: any[]) => void): this;
469
+ prependListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
470
+ prependListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;
471
+ prependListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
472
+ prependListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
473
+ prependListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
474
+ prependListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
475
+ prependListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
476
+ prependListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
477
+ prependListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;
478
+ prependListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
479
+ prependListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
480
+ prependListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;
481
+ prependListener(event: "test:watch:drained", listener: () => void): this;
482
+ prependListener(event: "test:watch:restarted", listener: () => void): this;
483
+ prependListener(event: string, listener: (...args: any[]) => void): this;
484
+ prependOnceListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
485
+ prependOnceListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;
486
+ prependOnceListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
487
+ prependOnceListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
488
+ prependOnceListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
489
+ prependOnceListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
490
+ prependOnceListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
491
+ prependOnceListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
492
+ prependOnceListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;
493
+ prependOnceListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
494
+ prependOnceListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
495
+ prependOnceListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;
496
+ prependOnceListener(event: "test:watch:drained", listener: () => void): this;
497
+ prependOnceListener(event: "test:watch:restarted", listener: () => void): this;
498
+ prependOnceListener(event: string, listener: (...args: any[]) => void): this;
499
+ }
500
+ namespace EventData {
501
+ interface Error extends globalThis.Error {
502
+ cause: globalThis.Error;
503
+ }
504
+ interface LocationInfo {
505
+ /**
506
+ * The column number where the test is defined, or
507
+ * `undefined` if the test was run through the REPL.
508
+ */
509
+ column?: number;
510
+ /**
511
+ * The path of the test file, `undefined` if test was run through the REPL.
512
+ */
513
+ file?: string;
514
+ /**
515
+ * The line number where the test is defined, or `undefined` if the test was run through the REPL.
516
+ */
517
+ line?: number;
518
+ }
519
+ interface TestDiagnostic extends LocationInfo {
520
+ /**
521
+ * The diagnostic message.
522
+ */
523
+ message: string;
524
+ /**
525
+ * The nesting level of the test.
526
+ */
527
+ nesting: number;
528
+ /**
529
+ * The severity level of the diagnostic message.
530
+ * Possible values are:
531
+ * * `'info'`: Informational messages.
532
+ * * `'warn'`: Warnings.
533
+ * * `'error'`: Errors.
534
+ */
535
+ level: "info" | "warn" | "error";
536
+ }
537
+ interface TestCoverage {
538
+ /**
539
+ * An object containing the coverage report.
540
+ */
541
+ summary: {
542
+ /**
543
+ * An array of coverage reports for individual files.
544
+ */
545
+ files: Array<{
546
+ /**
547
+ * The absolute path of the file.
548
+ */
549
+ path: string;
550
+ /**
551
+ * The total number of lines.
552
+ */
553
+ totalLineCount: number;
554
+ /**
555
+ * The total number of branches.
556
+ */
557
+ totalBranchCount: number;
558
+ /**
559
+ * The total number of functions.
560
+ */
561
+ totalFunctionCount: number;
562
+ /**
563
+ * The number of covered lines.
564
+ */
565
+ coveredLineCount: number;
566
+ /**
567
+ * The number of covered branches.
568
+ */
569
+ coveredBranchCount: number;
570
+ /**
571
+ * The number of covered functions.
572
+ */
573
+ coveredFunctionCount: number;
574
+ /**
575
+ * The percentage of lines covered.
576
+ */
577
+ coveredLinePercent: number;
578
+ /**
579
+ * The percentage of branches covered.
580
+ */
581
+ coveredBranchPercent: number;
582
+ /**
583
+ * The percentage of functions covered.
584
+ */
585
+ coveredFunctionPercent: number;
586
+ /**
587
+ * An array of functions representing function coverage.
588
+ */
589
+ functions: Array<{
590
+ /**
591
+ * The name of the function.
592
+ */
593
+ name: string;
594
+ /**
595
+ * The line number where the function is defined.
596
+ */
597
+ line: number;
598
+ /**
599
+ * The number of times the function was called.
600
+ */
601
+ count: number;
602
+ }>;
603
+ /**
604
+ * An array of branches representing branch coverage.
605
+ */
606
+ branches: Array<{
607
+ /**
608
+ * The line number where the branch is defined.
609
+ */
610
+ line: number;
611
+ /**
612
+ * The number of times the branch was taken.
613
+ */
614
+ count: number;
615
+ }>;
616
+ /**
617
+ * An array of lines representing line numbers and the number of times they were covered.
618
+ */
619
+ lines: Array<{
620
+ /**
621
+ * The line number.
622
+ */
623
+ line: number;
624
+ /**
625
+ * The number of times the line was covered.
626
+ */
627
+ count: number;
628
+ }>;
629
+ }>;
630
+ /**
631
+ * An object containing whether or not the coverage for
632
+ * each coverage type.
633
+ * @since v22.9.0
634
+ */
635
+ thresholds: {
636
+ /**
637
+ * The function coverage threshold.
638
+ */
639
+ function: number;
640
+ /**
641
+ * The branch coverage threshold.
642
+ */
643
+ branch: number;
644
+ /**
645
+ * The line coverage threshold.
646
+ */
647
+ line: number;
648
+ };
649
+ /**
650
+ * An object containing a summary of coverage for all files.
651
+ */
652
+ totals: {
653
+ /**
654
+ * The total number of lines.
655
+ */
656
+ totalLineCount: number;
657
+ /**
658
+ * The total number of branches.
659
+ */
660
+ totalBranchCount: number;
661
+ /**
662
+ * The total number of functions.
663
+ */
664
+ totalFunctionCount: number;
665
+ /**
666
+ * The number of covered lines.
667
+ */
668
+ coveredLineCount: number;
669
+ /**
670
+ * The number of covered branches.
671
+ */
672
+ coveredBranchCount: number;
673
+ /**
674
+ * The number of covered functions.
675
+ */
676
+ coveredFunctionCount: number;
677
+ /**
678
+ * The percentage of lines covered.
679
+ */
680
+ coveredLinePercent: number;
681
+ /**
682
+ * The percentage of branches covered.
683
+ */
684
+ coveredBranchPercent: number;
685
+ /**
686
+ * The percentage of functions covered.
687
+ */
688
+ coveredFunctionPercent: number;
689
+ };
690
+ /**
691
+ * The working directory when code coverage began. This
692
+ * is useful for displaying relative path names in case
693
+ * the tests changed the working directory of the Node.js process.
694
+ */
695
+ workingDirectory: string;
696
+ };
697
+ /**
698
+ * The nesting level of the test.
699
+ */
700
+ nesting: number;
701
+ }
702
+ interface TestComplete extends LocationInfo {
703
+ /**
704
+ * Additional execution metadata.
705
+ */
706
+ details: {
707
+ /**
708
+ * Whether the test passed or not.
709
+ */
710
+ passed: boolean;
711
+ /**
712
+ * The duration of the test in milliseconds.
713
+ */
714
+ duration_ms: number;
715
+ /**
716
+ * An error wrapping the error thrown by the test if it did not pass.
717
+ */
718
+ error?: Error;
719
+ /**
720
+ * The type of the test, used to denote whether this is a suite.
721
+ */
722
+ type?: "suite" | "test";
723
+ };
724
+ /**
725
+ * The test name.
726
+ */
727
+ name: string;
728
+ /**
729
+ * The nesting level of the test.
730
+ */
731
+ nesting: number;
732
+ /**
733
+ * The ordinal number of the test.
734
+ */
735
+ testNumber: number;
736
+ /**
737
+ * Present if `context.todo` is called.
738
+ */
739
+ todo?: string | boolean;
740
+ /**
741
+ * Present if `context.skip` is called.
742
+ */
743
+ skip?: string | boolean;
744
+ }
745
+ interface TestDequeue extends LocationInfo {
746
+ /**
747
+ * The test name.
748
+ */
749
+ name: string;
750
+ /**
751
+ * The nesting level of the test.
752
+ */
753
+ nesting: number;
754
+ /**
755
+ * The test type. Either `'suite'` or `'test'`.
756
+ * @since v22.15.0
757
+ */
758
+ type: "suite" | "test";
759
+ }
760
+ interface TestEnqueue extends LocationInfo {
761
+ /**
762
+ * The test name.
763
+ */
764
+ name: string;
765
+ /**
766
+ * The nesting level of the test.
767
+ */
768
+ nesting: number;
769
+ /**
770
+ * The test type. Either `'suite'` or `'test'`.
771
+ * @since v22.15.0
772
+ */
773
+ type: "suite" | "test";
774
+ }
775
+ interface TestFail extends LocationInfo {
776
+ /**
777
+ * Additional execution metadata.
778
+ */
779
+ details: {
780
+ /**
781
+ * The duration of the test in milliseconds.
782
+ */
783
+ duration_ms: number;
784
+ /**
785
+ * An error wrapping the error thrown by the test.
786
+ */
787
+ error: Error;
788
+ /**
789
+ * The type of the test, used to denote whether this is a suite.
790
+ * @since v20.0.0, v19.9.0, v18.17.0
791
+ */
792
+ type?: "suite" | "test";
793
+ /**
794
+ * The attempt number of the test run,
795
+ * present only when using the `--test-rerun-failures` flag.
796
+ * @since v24.7.0
797
+ */
798
+ attempt?: number;
799
+ };
800
+ /**
801
+ * The test name.
802
+ */
803
+ name: string;
804
+ /**
805
+ * The nesting level of the test.
806
+ */
807
+ nesting: number;
808
+ /**
809
+ * The ordinal number of the test.
810
+ */
811
+ testNumber: number;
812
+ /**
813
+ * Present if `context.todo` is called.
814
+ */
815
+ todo?: string | boolean;
816
+ /**
817
+ * Present if `context.skip` is called.
818
+ */
819
+ skip?: string | boolean;
820
+ }
821
+ interface TestPass extends LocationInfo {
822
+ /**
823
+ * Additional execution metadata.
824
+ */
825
+ details: {
826
+ /**
827
+ * The duration of the test in milliseconds.
828
+ */
829
+ duration_ms: number;
830
+ /**
831
+ * The type of the test, used to denote whether this is a suite.
832
+ * @since 20.0.0, 19.9.0, 18.17.0
833
+ */
834
+ type?: "suite" | "test";
835
+ /**
836
+ * The attempt number of the test run,
837
+ * present only when using the `--test-rerun-failures` flag.
838
+ * @since v24.7.0
839
+ */
840
+ attempt?: number;
841
+ /**
842
+ * The attempt number the test passed on,
843
+ * present only when using the `--test-rerun-failures` flag.
844
+ * @since v24.7.0
845
+ */
846
+ passed_on_attempt?: number;
847
+ };
848
+ /**
849
+ * The test name.
850
+ */
851
+ name: string;
852
+ /**
853
+ * The nesting level of the test.
854
+ */
855
+ nesting: number;
856
+ /**
857
+ * The ordinal number of the test.
858
+ */
859
+ testNumber: number;
860
+ /**
861
+ * Present if `context.todo` is called.
862
+ */
863
+ todo?: string | boolean;
864
+ /**
865
+ * Present if `context.skip` is called.
866
+ */
867
+ skip?: string | boolean;
868
+ }
869
+ interface TestPlan extends LocationInfo {
870
+ /**
871
+ * The nesting level of the test.
872
+ */
873
+ nesting: number;
874
+ /**
875
+ * The number of subtests that have ran.
876
+ */
877
+ count: number;
878
+ }
879
+ interface TestStart extends LocationInfo {
880
+ /**
881
+ * The test name.
882
+ */
883
+ name: string;
884
+ /**
885
+ * The nesting level of the test.
886
+ */
887
+ nesting: number;
888
+ }
889
+ interface TestStderr {
890
+ /**
891
+ * The path of the test file.
892
+ */
893
+ file: string;
894
+ /**
895
+ * The message written to `stderr`.
896
+ */
897
+ message: string;
898
+ }
899
+ interface TestStdout {
900
+ /**
901
+ * The path of the test file.
902
+ */
903
+ file: string;
904
+ /**
905
+ * The message written to `stdout`.
906
+ */
907
+ message: string;
908
+ }
909
+ interface TestSummary {
910
+ /**
911
+ * An object containing the counts of various test results.
912
+ */
913
+ counts: {
914
+ /**
915
+ * The total number of cancelled tests.
916
+ */
917
+ cancelled: number;
918
+ /**
919
+ * The total number of passed tests.
920
+ */
921
+ passed: number;
922
+ /**
923
+ * The total number of skipped tests.
924
+ */
925
+ skipped: number;
926
+ /**
927
+ * The total number of suites run.
928
+ */
929
+ suites: number;
930
+ /**
931
+ * The total number of tests run, excluding suites.
932
+ */
933
+ tests: number;
934
+ /**
935
+ * The total number of TODO tests.
936
+ */
937
+ todo: number;
938
+ /**
939
+ * The total number of top level tests and suites.
940
+ */
941
+ topLevel: number;
942
+ };
943
+ /**
944
+ * The duration of the test run in milliseconds.
945
+ */
946
+ duration_ms: number;
947
+ /**
948
+ * The path of the test file that generated the
949
+ * summary. If the summary corresponds to multiple files, this value is
950
+ * `undefined`.
951
+ */
952
+ file: string | undefined;
953
+ /**
954
+ * Indicates whether or not the test run is considered
955
+ * successful or not. If any error condition occurs, such as a failing test or
956
+ * unmet coverage threshold, this value will be set to `false`.
957
+ */
958
+ success: boolean;
959
+ }
960
+ }
961
+ /**
962
+ * An instance of `TestContext` is passed to each test function in order to
963
+ * interact with the test runner. However, the `TestContext` constructor is not
964
+ * exposed as part of the API.
454
965
  * @since v18.0.0, v16.17.0
455
- * @param shouldRunOnlyTests Whether or not to run `only` tests.
456
966
  */
457
- runOnly(shouldRunOnlyTests: boolean): void;
458
- /**
459
- * ```js
460
- * test('top level test', async (t) => {
461
- * await fetch('some/uri', { signal: t.signal });
462
- * });
463
- * ```
967
+ interface TestContext {
968
+ /**
969
+ * An object containing assertion methods bound to the test context.
970
+ * The top-level functions from the `node:assert` module are exposed here for the purpose of creating test plans.
971
+ *
972
+ * **Note:** Some of the functions from `node:assert` contain type assertions. If these are called via the
973
+ * TestContext `assert` object, then the context parameter in the test's function signature **must be explicitly typed**
974
+ * (ie. the parameter must have a type annotation), otherwise an error will be raised by the TypeScript compiler:
975
+ * ```ts
976
+ * import { test, type TestContext } from 'node:test';
977
+ *
978
+ * // The test function's context parameter must have a type annotation.
979
+ * test('example', (t: TestContext) => {
980
+ * t.assert.deepStrictEqual(actual, expected);
981
+ * });
982
+ *
983
+ * // Omitting the type annotation will result in a compilation error.
984
+ * test('example', t => {
985
+ * t.assert.deepStrictEqual(actual, expected); // Error: 't' needs an explicit type annotation.
986
+ * });
987
+ * ```
988
+ * @since v22.2.0, v20.15.0
989
+ */
990
+ readonly assert: TestContextAssert;
991
+ readonly attempt: number;
992
+ /**
993
+ * This function is used to create a hook running before subtest of the current test.
994
+ * @param fn The hook function. The first argument to this function is a `TestContext` object.
995
+ * If the hook uses callbacks, the callback function is passed as the second argument.
996
+ * @param options Configuration options for the hook.
997
+ * @since v20.1.0, v18.17.0
998
+ */
999
+ before(fn?: TestContextHookFn, options?: HookOptions): void;
1000
+ /**
1001
+ * This function is used to create a hook running before each subtest of the current test.
1002
+ * @param fn The hook function. The first argument to this function is a `TestContext` object.
1003
+ * If the hook uses callbacks, the callback function is passed as the second argument.
1004
+ * @param options Configuration options for the hook.
1005
+ * @since v18.8.0
1006
+ */
1007
+ beforeEach(fn?: TestContextHookFn, options?: HookOptions): void;
1008
+ /**
1009
+ * This function is used to create a hook that runs after the current test finishes.
1010
+ * @param fn The hook function. The first argument to this function is a `TestContext` object.
1011
+ * If the hook uses callbacks, the callback function is passed as the second argument.
1012
+ * @param options Configuration options for the hook.
1013
+ * @since v18.13.0
1014
+ */
1015
+ after(fn?: TestContextHookFn, options?: HookOptions): void;
1016
+ /**
1017
+ * This function is used to create a hook running after each subtest of the current test.
1018
+ * @param fn The hook function. The first argument to this function is a `TestContext` object.
1019
+ * If the hook uses callbacks, the callback function is passed as the second argument.
1020
+ * @param options Configuration options for the hook.
1021
+ * @since v18.8.0
1022
+ */
1023
+ afterEach(fn?: TestContextHookFn, options?: HookOptions): void;
1024
+ /**
1025
+ * This function is used to write diagnostics to the output. Any diagnostic
1026
+ * information is included at the end of the test's results. This function does
1027
+ * not return a value.
1028
+ *
1029
+ * ```js
1030
+ * test('top level test', (t) => {
1031
+ * t.diagnostic('A diagnostic message');
1032
+ * });
1033
+ * ```
1034
+ * @since v18.0.0, v16.17.0
1035
+ * @param message Message to be reported.
1036
+ */
1037
+ diagnostic(message: string): void;
1038
+ /**
1039
+ * The absolute path of the test file that created the current test. If a test file imports
1040
+ * additional modules that generate tests, the imported tests will return the path of the root test file.
1041
+ * @since v22.6.0
1042
+ */
1043
+ readonly filePath: string | undefined;
1044
+ /**
1045
+ * The name of the test and each of its ancestors, separated by `>`.
1046
+ * @since v22.3.0
1047
+ */
1048
+ readonly fullName: string;
1049
+ /**
1050
+ * The name of the test.
1051
+ * @since v18.8.0, v16.18.0
1052
+ */
1053
+ readonly name: string;
1054
+ /**
1055
+ * This function is used to set the number of assertions and subtests that are expected to run
1056
+ * within the test. If the number of assertions and subtests that run does not match the
1057
+ * expected count, the test will fail.
1058
+ *
1059
+ * > Note: To make sure assertions are tracked, `t.assert` must be used instead of `assert` directly.
1060
+ *
1061
+ * ```js
1062
+ * test('top level test', (t) => {
1063
+ * t.plan(2);
1064
+ * t.assert.ok('some relevant assertion here');
1065
+ * t.test('subtest', () => {});
1066
+ * });
1067
+ * ```
1068
+ *
1069
+ * When working with asynchronous code, the `plan` function can be used to ensure that the
1070
+ * correct number of assertions are run:
1071
+ *
1072
+ * ```js
1073
+ * test('planning with streams', (t, done) => {
1074
+ * function* generate() {
1075
+ * yield 'a';
1076
+ * yield 'b';
1077
+ * yield 'c';
1078
+ * }
1079
+ * const expected = ['a', 'b', 'c'];
1080
+ * t.plan(expected.length);
1081
+ * const stream = Readable.from(generate());
1082
+ * stream.on('data', (chunk) => {
1083
+ * t.assert.strictEqual(chunk, expected.shift());
1084
+ * });
1085
+ *
1086
+ * stream.on('end', () => {
1087
+ * done();
1088
+ * });
1089
+ * });
1090
+ * ```
1091
+ *
1092
+ * When using the `wait` option, you can control how long the test will wait for the expected assertions.
1093
+ * For example, setting a maximum wait time ensures that the test will wait for asynchronous assertions
1094
+ * to complete within the specified timeframe:
1095
+ *
1096
+ * ```js
1097
+ * test('plan with wait: 2000 waits for async assertions', (t) => {
1098
+ * t.plan(1, { wait: 2000 }); // Waits for up to 2 seconds for the assertion to complete.
1099
+ *
1100
+ * const asyncActivity = () => {
1101
+ * setTimeout(() => {
1102
+ * * t.assert.ok(true, 'Async assertion completed within the wait time');
1103
+ * }, 1000); // Completes after 1 second, within the 2-second wait time.
1104
+ * };
1105
+ *
1106
+ * asyncActivity(); // The test will pass because the assertion is completed in time.
1107
+ * });
1108
+ * ```
1109
+ *
1110
+ * Note: If a `wait` timeout is specified, it begins counting down only after the test function finishes executing.
1111
+ * @since v22.2.0
1112
+ */
1113
+ plan(count: number, options?: TestContextPlanOptions): void;
1114
+ /**
1115
+ * If `shouldRunOnlyTests` is truthy, the test context will only run tests that
1116
+ * have the `only` option set. Otherwise, all tests are run. If Node.js was not
1117
+ * started with the `--test-only` command-line option, this function is a
1118
+ * no-op.
1119
+ *
1120
+ * ```js
1121
+ * test('top level test', (t) => {
1122
+ * // The test context can be set to run subtests with the 'only' option.
1123
+ * t.runOnly(true);
1124
+ * return Promise.all([
1125
+ * t.test('this subtest is now skipped'),
1126
+ * t.test('this subtest is run', { only: true }),
1127
+ * ]);
1128
+ * });
1129
+ * ```
1130
+ * @since v18.0.0, v16.17.0
1131
+ * @param shouldRunOnlyTests Whether or not to run `only` tests.
1132
+ */
1133
+ runOnly(shouldRunOnlyTests: boolean): void;
1134
+ /**
1135
+ * ```js
1136
+ * test('top level test', async (t) => {
1137
+ * await fetch('some/uri', { signal: t.signal });
1138
+ * });
1139
+ * ```
1140
+ * @since v18.7.0, v16.17.0
1141
+ */
1142
+ readonly signal: AbortSignal;
1143
+ /**
1144
+ * This function causes the test's output to indicate the test as skipped. If `message` is provided, it is included in the output. Calling `skip()` does
1145
+ * not terminate execution of the test function. This function does not return a
1146
+ * value.
1147
+ *
1148
+ * ```js
1149
+ * test('top level test', (t) => {
1150
+ * // Make sure to return here as well if the test contains additional logic.
1151
+ * t.skip('this is skipped');
1152
+ * });
1153
+ * ```
1154
+ * @since v18.0.0, v16.17.0
1155
+ * @param message Optional skip message.
1156
+ */
1157
+ skip(message?: string): void;
1158
+ /**
1159
+ * This function adds a `TODO` directive to the test's output. If `message` is
1160
+ * provided, it is included in the output. Calling `todo()` does not terminate
1161
+ * execution of the test function. This function does not return a value.
1162
+ *
1163
+ * ```js
1164
+ * test('top level test', (t) => {
1165
+ * // This test is marked as `TODO`
1166
+ * t.todo('this is a todo');
1167
+ * });
1168
+ * ```
1169
+ * @since v18.0.0, v16.17.0
1170
+ * @param message Optional `TODO` message.
1171
+ */
1172
+ todo(message?: string): void;
1173
+ /**
1174
+ * This function is used to create subtests under the current test. This function behaves in
1175
+ * the same fashion as the top level {@link test} function.
1176
+ * @since v18.0.0
1177
+ * @param name The name of the test, which is displayed when reporting test results.
1178
+ * Defaults to the `name` property of `fn`, or `'<anonymous>'` if `fn` does not have a name.
1179
+ * @param options Configuration options for the test.
1180
+ * @param fn The function under test. This first argument to this function is a {@link TestContext} object.
1181
+ * If the test uses callbacks, the callback function is passed as the second argument.
1182
+ * @returns A {@link Promise} resolved with `undefined` once the test completes.
1183
+ */
1184
+ test: typeof test;
1185
+ /**
1186
+ * This method polls a `condition` function until that function either returns
1187
+ * successfully or the operation times out.
1188
+ * @since v22.14.0
1189
+ * @param condition An assertion function that is invoked
1190
+ * periodically until it completes successfully or the defined polling timeout
1191
+ * elapses. Successful completion is defined as not throwing or rejecting. This
1192
+ * function does not accept any arguments, and is allowed to return any value.
1193
+ * @param options An optional configuration object for the polling operation.
1194
+ * @returns Fulfilled with the value returned by `condition`.
1195
+ */
1196
+ waitFor<T>(condition: () => T, options?: TestContextWaitForOptions): Promise<Awaited<T>>;
1197
+ /**
1198
+ * Each test provides its own MockTracker instance.
1199
+ */
1200
+ readonly mock: MockTracker;
1201
+ }
1202
+ interface TestContextAssert extends Pick<typeof import("assert"), AssertMethodNames> {
1203
+ /**
1204
+ * This function serializes `value` and writes it to the file specified by `path`.
1205
+ *
1206
+ * ```js
1207
+ * test('snapshot test with default serialization', (t) => {
1208
+ * t.assert.fileSnapshot({ value1: 1, value2: 2 }, './snapshots/snapshot.json');
1209
+ * });
1210
+ * ```
1211
+ *
1212
+ * This function differs from `context.assert.snapshot()` in the following ways:
1213
+ *
1214
+ * * The snapshot file path is explicitly provided by the user.
1215
+ * * Each snapshot file is limited to a single snapshot value.
1216
+ * * No additional escaping is performed by the test runner.
1217
+ *
1218
+ * These differences allow snapshot files to better support features such as syntax
1219
+ * highlighting.
1220
+ * @since v22.14.0
1221
+ * @param value A value to serialize to a string. If Node.js was started with
1222
+ * the [`--test-update-snapshots`](https://nodejs.org/docs/latest-v24.x/api/cli.html#--test-update-snapshots)
1223
+ * flag, the serialized value is written to
1224
+ * `path`. Otherwise, the serialized value is compared to the contents of the
1225
+ * existing snapshot file.
1226
+ * @param path The file where the serialized `value` is written.
1227
+ * @param options Optional configuration options.
1228
+ */
1229
+ fileSnapshot(value: any, path: string, options?: AssertSnapshotOptions): void;
1230
+ /**
1231
+ * This function implements assertions for snapshot testing.
1232
+ * ```js
1233
+ * test('snapshot test with default serialization', (t) => {
1234
+ * t.assert.snapshot({ value1: 1, value2: 2 });
1235
+ * });
1236
+ *
1237
+ * test('snapshot test with custom serialization', (t) => {
1238
+ * t.assert.snapshot({ value3: 3, value4: 4 }, {
1239
+ * serializers: [(value) => JSON.stringify(value)]
1240
+ * });
1241
+ * });
1242
+ * ```
1243
+ * @since v22.3.0
1244
+ * @param value A value to serialize to a string. If Node.js was started with
1245
+ * the [`--test-update-snapshots`](https://nodejs.org/docs/latest-v24.x/api/cli.html#--test-update-snapshots)
1246
+ * flag, the serialized value is written to
1247
+ * the snapshot file. Otherwise, the serialized value is compared to the
1248
+ * corresponding value in the existing snapshot file.
1249
+ */
1250
+ snapshot(value: any, options?: AssertSnapshotOptions): void;
1251
+ /**
1252
+ * A custom assertion function registered with `assert.register()`.
1253
+ */
1254
+ [name: string]: (...args: any[]) => void;
1255
+ }
1256
+ interface AssertSnapshotOptions {
1257
+ /**
1258
+ * An array of synchronous functions used to serialize `value` into a string.
1259
+ * `value` is passed as the only argument to the first serializer function.
1260
+ * The return value of each serializer is passed as input to the next serializer.
1261
+ * Once all serializers have run, the resulting value is coerced to a string.
1262
+ *
1263
+ * If no serializers are provided, the test runner's default serializers are used.
1264
+ */
1265
+ serializers?: ReadonlyArray<(value: any) => any> | undefined;
1266
+ }
1267
+ interface TestContextPlanOptions {
1268
+ /**
1269
+ * The wait time for the plan:
1270
+ * * If `true`, the plan waits indefinitely for all assertions and subtests to run.
1271
+ * * If `false`, the plan performs an immediate check after the test function completes,
1272
+ * without waiting for any pending assertions or subtests.
1273
+ * Any assertions or subtests that complete after this check will not be counted towards the plan.
1274
+ * * If a number, it specifies the maximum wait time in milliseconds
1275
+ * before timing out while waiting for expected assertions and subtests to be matched.
1276
+ * If the timeout is reached, the test will fail.
1277
+ * @default false
1278
+ */
1279
+ wait?: boolean | number | undefined;
1280
+ }
1281
+ interface TestContextWaitForOptions {
1282
+ /**
1283
+ * The number of milliseconds to wait after an unsuccessful
1284
+ * invocation of `condition` before trying again.
1285
+ * @default 50
1286
+ */
1287
+ interval?: number | undefined;
1288
+ /**
1289
+ * The poll timeout in milliseconds. If `condition` has not
1290
+ * succeeded by the time this elapses, an error occurs.
1291
+ * @default 1000
1292
+ */
1293
+ timeout?: number | undefined;
1294
+ }
1295
+ /**
1296
+ * An instance of `SuiteContext` is passed to each suite function in order to
1297
+ * interact with the test runner. However, the `SuiteContext` constructor is not
1298
+ * exposed as part of the API.
464
1299
  * @since v18.7.0, v16.17.0
465
1300
  */
466
- readonly signal: AbortSignal;
467
- /**
468
- * This function causes the test's output to indicate the test as skipped. If`message` is provided, it is included in the output. Calling `skip()` does
469
- * not terminate execution of the test function. This function does not return a
470
- * value.
1301
+ interface SuiteContext {
1302
+ /**
1303
+ * The absolute path of the test file that created the current suite. If a test file imports
1304
+ * additional modules that generate suites, the imported suites will return the path of the root test file.
1305
+ * @since v22.6.0
1306
+ */
1307
+ readonly filePath: string | undefined;
1308
+ /**
1309
+ * The name of the suite and each of its ancestors, separated by `>`.
1310
+ * @since v22.3.0, v20.16.0
1311
+ */
1312
+ readonly fullName: string;
1313
+ /**
1314
+ * The name of the suite.
1315
+ * @since v18.8.0, v16.18.0
1316
+ */
1317
+ readonly name: string;
1318
+ /**
1319
+ * Can be used to abort test subtasks when the test has been aborted.
1320
+ * @since v18.7.0, v16.17.0
1321
+ */
1322
+ readonly signal: AbortSignal;
1323
+ }
1324
+ interface TestOptions {
1325
+ /**
1326
+ * If a number is provided, then that many tests would run in parallel.
1327
+ * If truthy, it would run (number of cpu cores - 1) tests in parallel.
1328
+ * For subtests, it will be `Infinity` tests in parallel.
1329
+ * If falsy, it would only run one test at a time.
1330
+ * If unspecified, subtests inherit this value from their parent.
1331
+ * @default false
1332
+ */
1333
+ concurrency?: number | boolean | undefined;
1334
+ /**
1335
+ * If truthy, and the test context is configured to run `only` tests, then this test will be
1336
+ * run. Otherwise, the test is skipped.
1337
+ * @default false
1338
+ */
1339
+ only?: boolean | undefined;
1340
+ /**
1341
+ * Allows aborting an in-progress test.
1342
+ * @since v18.8.0
1343
+ */
1344
+ signal?: AbortSignal | undefined;
1345
+ /**
1346
+ * If truthy, the test is skipped. If a string is provided, that string is displayed in the
1347
+ * test results as the reason for skipping the test.
1348
+ * @default false
1349
+ */
1350
+ skip?: boolean | string | undefined;
1351
+ /**
1352
+ * A number of milliseconds the test will fail after. If unspecified, subtests inherit this
1353
+ * value from their parent.
1354
+ * @default Infinity
1355
+ * @since v18.7.0
1356
+ */
1357
+ timeout?: number | undefined;
1358
+ /**
1359
+ * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in
1360
+ * the test results as the reason why the test is `TODO`.
1361
+ * @default false
1362
+ */
1363
+ todo?: boolean | string | undefined;
1364
+ /**
1365
+ * The number of assertions and subtests expected to be run in the test.
1366
+ * If the number of assertions run in the test does not match the number
1367
+ * specified in the plan, the test will fail.
1368
+ * @default undefined
1369
+ * @since v22.2.0
1370
+ */
1371
+ plan?: number | undefined;
1372
+ }
1373
+ /**
1374
+ * This function creates a hook that runs before executing a suite.
471
1375
  *
472
1376
  * ```js
473
- * test('top level test', (t) => {
474
- * // Make sure to return here as well if the test contains additional logic.
475
- * t.skip('this is skipped');
1377
+ * describe('tests', async () => {
1378
+ * before(() => console.log('about to run some test'));
1379
+ * it('is a subtest', () => {
1380
+ * assert.ok('some relevant assertion here');
1381
+ * });
476
1382
  * });
477
1383
  * ```
478
- * @since v18.0.0, v16.17.0
479
- * @param message Optional skip message.
1384
+ * @since v18.8.0, v16.18.0
1385
+ * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument.
1386
+ * @param options Configuration options for the hook.
480
1387
  */
481
- skip(message?: string): void;
1388
+ function before(fn?: HookFn, options?: HookOptions): void;
482
1389
  /**
483
- * This function adds a `TODO` directive to the test's output. If `message` is
484
- * provided, it is included in the output. Calling `todo()` does not terminate
485
- * execution of the test function. This function does not return a value.
1390
+ * This function creates a hook that runs after executing a suite.
486
1391
  *
487
1392
  * ```js
488
- * test('top level test', (t) => {
489
- * // This test is marked as `TODO`
490
- * t.todo('this is a todo');
1393
+ * describe('tests', async () => {
1394
+ * after(() => console.log('finished running tests'));
1395
+ * it('is a subtest', () => {
1396
+ * assert.ok('some relevant assertion here');
1397
+ * });
491
1398
  * });
492
1399
  * ```
493
- * @since v18.0.0, v16.17.0
494
- * @param message Optional `TODO` message.
495
- */
496
- todo(message?: string): void;
497
- /**
498
- * This function is used to create subtests under the current test. This function behaves in
499
- * the same fashion as the top level {@link test} function.
500
- * @since v18.0.0
501
- * @param name The name of the test, which is displayed when reporting test results.
502
- * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
503
- * @param options Configuration options for the test
504
- * @param fn The function under test. This first argument to this function is a
505
- * {@link TestContext} object. If the test uses callbacks, the callback function is
506
- * passed as the second argument. Default: A no-op function.
507
- * @returns A {@link Promise} resolved with `undefined` once the test completes.
508
- */
509
- test: typeof test;
510
- /**
511
- * Each test provides its own MockTracker instance.
512
- */
513
- readonly mock: MockTracker;
514
- }
515
- /**
516
- * An instance of `SuiteContext` is passed to each suite function in order to
517
- * interact with the test runner. However, the `SuiteContext` constructor is not
518
- * exposed as part of the API.
519
- * @since v18.7.0, v16.17.0
520
- */
521
- class SuiteContext {
522
- /**
523
- * The name of the suite.
524
1400
  * @since v18.8.0, v16.18.0
1401
+ * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument.
1402
+ * @param options Configuration options for the hook.
525
1403
  */
526
- readonly name: string;
527
- /**
528
- * Can be used to abort test subtasks when the test has been aborted.
529
- * @since v18.7.0, v16.17.0
530
- */
531
- readonly signal: AbortSignal;
532
- }
533
- interface TestOptions {
534
- /**
535
- * If a number is provided, then that many tests would run in parallel.
536
- * If truthy, it would run (number of cpu cores - 1) tests in parallel.
537
- * For subtests, it will be `Infinity` tests in parallel.
538
- * If falsy, it would only run one test at a time.
539
- * If unspecified, subtests inherit this value from their parent.
540
- * @default false
541
- */
542
- concurrency?: number | boolean | undefined;
543
- /**
544
- * If truthy, and the test context is configured to run `only` tests, then this test will be
545
- * run. Otherwise, the test is skipped.
546
- * @default false
547
- */
548
- only?: boolean | undefined;
549
- /**
550
- * Allows aborting an in-progress test.
551
- * @since v18.8.0
552
- */
553
- signal?: AbortSignal | undefined;
554
- /**
555
- * If truthy, the test is skipped. If a string is provided, that string is displayed in the
556
- * test results as the reason for skipping the test.
557
- * @default false
558
- */
559
- skip?: boolean | string | undefined;
560
- /**
561
- * A number of milliseconds the test will fail after. If unspecified, subtests inherit this
562
- * value from their parent.
563
- * @default Infinity
564
- * @since v18.7.0
565
- */
566
- timeout?: number | undefined;
567
- /**
568
- * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in
569
- * the test results as the reason why the test is `TODO`.
570
- * @default false
571
- */
572
- todo?: boolean | string | undefined;
573
- }
574
- /**
575
- * This function is used to create a hook running before running a suite.
576
- *
577
- * ```js
578
- * describe('tests', async () => {
579
- * before(() => console.log('about to run some test'));
580
- * it('is a subtest', () => {
581
- * assert.ok('some relevant assertion here');
582
- * });
583
- * });
584
- * ```
585
- * @since v18.8.0, v16.18.0
586
- * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument.
587
- * @param options Configuration options for the hook. The following properties are supported:
588
- */
589
- function before(fn?: HookFn, options?: HookOptions): void;
590
- /**
591
- * This function is used to create a hook running after running a suite.
592
- *
593
- * ```js
594
- * describe('tests', async () => {
595
- * after(() => console.log('finished running tests'));
596
- * it('is a subtest', () => {
597
- * assert.ok('some relevant assertion here');
598
- * });
599
- * });
600
- * ```
601
- * @since v18.8.0, v16.18.0
602
- * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument.
603
- * @param options Configuration options for the hook. The following properties are supported:
604
- */
605
- function after(fn?: HookFn, options?: HookOptions): void;
606
- /**
607
- * This function is used to create a hook running
608
- * before each subtest of the current suite.
609
- *
610
- * ```js
611
- * describe('tests', async () => {
612
- * beforeEach(() => console.log('about to run a test'));
613
- * it('is a subtest', () => {
614
- * assert.ok('some relevant assertion here');
615
- * });
616
- * });
617
- * ```
618
- * @since v18.8.0, v16.18.0
619
- * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument.
620
- * @param options Configuration options for the hook. The following properties are supported:
621
- */
622
- function beforeEach(fn?: HookFn, options?: HookOptions): void;
623
- /**
624
- * This function is used to create a hook running
625
- * after each subtest of the current test.
626
- *
627
- * ```js
628
- * describe('tests', async () => {
629
- * afterEach(() => console.log('finished running a test'));
630
- * it('is a subtest', () => {
631
- * assert.ok('some relevant assertion here');
632
- * });
633
- * });
634
- * ```
635
- * @since v18.8.0, v16.18.0
636
- * @param [fn='A no-op function'] The hook function. If the hook uses callbacks, the callback function is passed as the second argument.
637
- * @param options Configuration options for the hook. The following properties are supported:
638
- */
639
- function afterEach(fn?: HookFn, options?: HookOptions): void;
640
- /**
641
- * The hook function. If the hook uses callbacks, the callback function is passed as the
642
- * second argument.
643
- */
644
- type HookFn = (s: SuiteContext, done: (result?: any) => void) => any;
645
- /**
646
- * Configuration options for hooks.
647
- * @since v18.8.0
648
- */
649
- interface HookOptions {
650
- /**
651
- * Allows aborting an in-progress hook.
652
- */
653
- signal?: AbortSignal | undefined;
654
- /**
655
- * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this
656
- * value from their parent.
657
- * @default Infinity
658
- */
659
- timeout?: number | undefined;
660
- }
661
- interface MockFunctionOptions {
662
- /**
663
- * The number of times that the mock will use the behavior of `implementation`.
664
- * Once the mock function has been called `times` times,
665
- * it will automatically restore the behavior of `original`.
666
- * This value must be an integer greater than zero.
667
- * @default Infinity
668
- */
669
- times?: number | undefined;
670
- }
671
- interface MockMethodOptions extends MockFunctionOptions {
672
- /**
673
- * If `true`, `object[methodName]` is treated as a getter.
674
- * This option cannot be used with the `setter` option.
675
- */
676
- getter?: boolean | undefined;
677
- /**
678
- * If `true`, `object[methodName]` is treated as a setter.
679
- * This option cannot be used with the `getter` option.
680
- */
681
- setter?: boolean | undefined;
682
- }
683
- type Mock<F extends Function> = F & {
684
- mock: MockFunctionContext<F>;
685
- };
686
- type NoOpFunction = (...args: any[]) => undefined;
687
- type FunctionPropertyNames<T> = {
688
- [K in keyof T]: T[K] extends Function ? K : never;
689
- }[keyof T];
690
- /**
691
- * The `MockTracker` class is used to manage mocking functionality. The test runner
692
- * module provides a top level `mock` export which is a `MockTracker` instance.
693
- * Each test also provides its own `MockTracker` instance via the test context's`mock` property.
694
- * @since v19.1.0, v18.13.0
695
- */
696
- class MockTracker {
1404
+ function after(fn?: HookFn, options?: HookOptions): void;
697
1405
  /**
698
- * This function is used to create a mock function.
699
- *
700
- * The following example creates a mock function that increments a counter by one
701
- * on each invocation. The `times` option is used to modify the mock behavior such
702
- * that the first two invocations add two to the counter instead of one.
1406
+ * This function creates a hook that runs before each test in the current suite.
703
1407
  *
704
1408
  * ```js
705
- * test('mocks a counting function', (t) => {
706
- * let cnt = 0;
707
- *
708
- * function addOne() {
709
- * cnt++;
710
- * return cnt;
711
- * }
712
- *
713
- * function addTwo() {
714
- * cnt += 2;
715
- * return cnt;
716
- * }
717
- *
718
- * const fn = t.mock.fn(addOne, addTwo, { times: 2 });
719
- *
720
- * assert.strictEqual(fn(), 2);
721
- * assert.strictEqual(fn(), 4);
722
- * assert.strictEqual(fn(), 5);
723
- * assert.strictEqual(fn(), 6);
1409
+ * describe('tests', async () => {
1410
+ * beforeEach(() => console.log('about to run a test'));
1411
+ * it('is a subtest', () => {
1412
+ * assert.ok('some relevant assertion here');
1413
+ * });
724
1414
  * });
725
1415
  * ```
726
- * @since v19.1.0, v18.13.0
727
- * @param [original='A no-op function'] An optional function to create a mock on.
728
- * @param implementation An optional function used as the mock implementation for `original`. This is useful for creating mocks that exhibit one behavior for a specified number of calls and
729
- * then restore the behavior of `original`.
730
- * @param options Optional configuration options for the mock function. The following properties are supported:
731
- * @return The mocked function. The mocked function contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the
732
- * behavior of the mocked function.
1416
+ * @since v18.8.0, v16.18.0
1417
+ * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument.
1418
+ * @param options Configuration options for the hook.
733
1419
  */
734
- fn<F extends Function = NoOpFunction>(original?: F, options?: MockFunctionOptions): Mock<F>;
735
- fn<F extends Function = NoOpFunction, Implementation extends Function = F>(
736
- original?: F,
737
- implementation?: Implementation,
738
- options?: MockFunctionOptions,
739
- ): Mock<F | Implementation>;
1420
+ function beforeEach(fn?: HookFn, options?: HookOptions): void;
740
1421
  /**
741
- * This function is used to create a mock on an existing object method. The
742
- * following example demonstrates how a mock is created on an existing object
743
- * method.
1422
+ * This function creates a hook that runs after each test in the current suite.
1423
+ * The `afterEach()` hook is run even if the test fails.
744
1424
  *
745
1425
  * ```js
746
- * test('spies on an object method', (t) => {
747
- * const number = {
748
- * value: 5,
749
- * subtract(a) {
750
- * return this.value - a;
751
- * },
752
- * };
753
- *
754
- * t.mock.method(number, 'subtract');
755
- * assert.strictEqual(number.subtract.mock.calls.length, 0);
756
- * assert.strictEqual(number.subtract(3), 2);
757
- * assert.strictEqual(number.subtract.mock.calls.length, 1);
758
- *
759
- * const call = number.subtract.mock.calls[0];
760
- *
761
- * assert.deepStrictEqual(call.arguments, [3]);
762
- * assert.strictEqual(call.result, 2);
763
- * assert.strictEqual(call.error, undefined);
764
- * assert.strictEqual(call.target, undefined);
765
- * assert.strictEqual(call.this, number);
1426
+ * describe('tests', async () => {
1427
+ * afterEach(() => console.log('finished running a test'));
1428
+ * it('is a subtest', () => {
1429
+ * assert.ok('some relevant assertion here');
1430
+ * });
766
1431
  * });
767
1432
  * ```
768
- * @since v19.1.0, v18.13.0
769
- * @param object The object whose method is being mocked.
770
- * @param methodName The identifier of the method on `object` to mock. If `object[methodName]` is not a function, an error is thrown.
771
- * @param implementation An optional function used as the mock implementation for `object[methodName]`.
772
- * @param options Optional configuration options for the mock method. The following properties are supported:
773
- * @return The mocked method. The mocked method contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the
774
- * behavior of the mocked method.
775
- */
776
- method<
777
- MockedObject extends object,
778
- MethodName extends FunctionPropertyNames<MockedObject>,
779
- >(
780
- object: MockedObject,
781
- methodName: MethodName,
782
- options?: MockFunctionOptions,
783
- ): MockedObject[MethodName] extends Function ? Mock<MockedObject[MethodName]>
784
- : never;
785
- method<
786
- MockedObject extends object,
787
- MethodName extends FunctionPropertyNames<MockedObject>,
788
- Implementation extends Function,
789
- >(
790
- object: MockedObject,
791
- methodName: MethodName,
792
- implementation: Implementation,
793
- options?: MockFunctionOptions,
794
- ): MockedObject[MethodName] extends Function ? Mock<MockedObject[MethodName] | Implementation>
795
- : never;
796
- method<MockedObject extends object>(
797
- object: MockedObject,
798
- methodName: keyof MockedObject,
799
- options: MockMethodOptions,
800
- ): Mock<Function>;
801
- method<MockedObject extends object>(
802
- object: MockedObject,
803
- methodName: keyof MockedObject,
804
- implementation: Function,
805
- options: MockMethodOptions,
806
- ): Mock<Function>;
807
-
808
- /**
809
- * This function is syntax sugar for `MockTracker.method` with `options.getter`set to `true`.
810
- * @since v19.3.0, v18.13.0
811
- */
812
- getter<
813
- MockedObject extends object,
814
- MethodName extends keyof MockedObject,
815
- >(
816
- object: MockedObject,
817
- methodName: MethodName,
818
- options?: MockFunctionOptions,
819
- ): Mock<() => MockedObject[MethodName]>;
820
- getter<
821
- MockedObject extends object,
822
- MethodName extends keyof MockedObject,
823
- Implementation extends Function,
824
- >(
825
- object: MockedObject,
826
- methodName: MethodName,
827
- implementation?: Implementation,
828
- options?: MockFunctionOptions,
829
- ): Mock<(() => MockedObject[MethodName]) | Implementation>;
830
- /**
831
- * This function is syntax sugar for `MockTracker.method` with `options.setter`set to `true`.
832
- * @since v19.3.0, v18.13.0
833
- */
834
- setter<
835
- MockedObject extends object,
836
- MethodName extends keyof MockedObject,
837
- >(
838
- object: MockedObject,
839
- methodName: MethodName,
840
- options?: MockFunctionOptions,
841
- ): Mock<(value: MockedObject[MethodName]) => void>;
842
- setter<
843
- MockedObject extends object,
844
- MethodName extends keyof MockedObject,
845
- Implementation extends Function,
846
- >(
847
- object: MockedObject,
848
- methodName: MethodName,
849
- implementation?: Implementation,
850
- options?: MockFunctionOptions,
851
- ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>;
852
- /**
853
- * This function restores the default behavior of all mocks that were previously
854
- * created by this `MockTracker` and disassociates the mocks from the`MockTracker` instance. Once disassociated, the mocks can still be used, but the`MockTracker` instance can no longer be
855
- * used to reset their behavior or
856
- * otherwise interact with them.
857
- *
858
- * After each test completes, this function is called on the test context's`MockTracker`. If the global `MockTracker` is used extensively, calling this
859
- * function manually is recommended.
860
- * @since v19.1.0, v18.13.0
861
- */
862
- reset(): void;
863
- /**
864
- * This function restores the default behavior of all mocks that were previously
865
- * created by this `MockTracker`. Unlike `mock.reset()`, `mock.restoreAll()` does
866
- * not disassociate the mocks from the `MockTracker` instance.
867
- * @since v19.1.0, v18.13.0
868
- */
869
- restoreAll(): void;
870
- timers: MockTimers;
871
- }
872
- const mock: MockTracker;
873
- interface MockFunctionCall<
874
- F extends Function,
875
- ReturnType = F extends (...args: any) => infer T ? T
876
- : F extends abstract new(...args: any) => infer T ? T
877
- : unknown,
878
- Args = F extends (...args: infer Y) => any ? Y
879
- : F extends abstract new(...args: infer Y) => any ? Y
880
- : unknown[],
881
- > {
882
- /**
883
- * An array of the arguments passed to the mock function.
884
- */
885
- arguments: Args;
886
- /**
887
- * If the mocked function threw then this property contains the thrown value.
888
- */
889
- error: unknown | undefined;
890
- /**
891
- * The value returned by the mocked function.
892
- *
893
- * If the mocked function threw, it will be `undefined`.
894
- */
895
- result: ReturnType | undefined;
896
- /**
897
- * An `Error` object whose stack can be used to determine the callsite of the mocked function invocation.
1433
+ * @since v18.8.0, v16.18.0
1434
+ * @param fn The hook function. If the hook uses callbacks, the callback function is passed as the second argument.
1435
+ * @param options Configuration options for the hook.
898
1436
  */
899
- stack: Error;
1437
+ function afterEach(fn?: HookFn, options?: HookOptions): void;
900
1438
  /**
901
- * If the mocked function is a constructor, this field contains the class being constructed.
902
- * Otherwise this will be `undefined`.
1439
+ * The hook function. The first argument is the context in which the hook is called.
1440
+ * If the hook uses callbacks, the callback function is passed as the second argument.
903
1441
  */
904
- target: F extends abstract new(...args: any) => any ? F : undefined;
1442
+ type HookFn = (c: TestContext | SuiteContext, done: (result?: any) => void) => any;
905
1443
  /**
906
- * The mocked function's `this` value.
1444
+ * The hook function. The first argument is a `TestContext` object.
1445
+ * If the hook uses callbacks, the callback function is passed as the second argument.
907
1446
  */
908
- this: unknown;
909
- }
910
- /**
911
- * The `MockFunctionContext` class is used to inspect or manipulate the behavior of
912
- * mocks created via the `MockTracker` APIs.
913
- * @since v19.1.0, v18.13.0
914
- */
915
- class MockFunctionContext<F extends Function> {
1447
+ type TestContextHookFn = (t: TestContext, done: (result?: any) => void) => any;
916
1448
  /**
917
- * A getter that returns a copy of the internal array used to track calls to the
918
- * mock. Each entry in the array is an object with the following properties.
919
- * @since v19.1.0, v18.13.0
1449
+ * Configuration options for hooks.
1450
+ * @since v18.8.0
920
1451
  */
921
- readonly calls: Array<MockFunctionCall<F>>;
922
- /**
923
- * This function returns the number of times that this mock has been invoked. This
924
- * function is more efficient than checking `ctx.calls.length` because `ctx.calls`is a getter that creates a copy of the internal call tracking array.
1452
+ interface HookOptions {
1453
+ /**
1454
+ * Allows aborting an in-progress hook.
1455
+ */
1456
+ signal?: AbortSignal | undefined;
1457
+ /**
1458
+ * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this
1459
+ * value from their parent.
1460
+ * @default Infinity
1461
+ */
1462
+ timeout?: number | undefined;
1463
+ }
1464
+ interface MockFunctionOptions {
1465
+ /**
1466
+ * The number of times that the mock will use the behavior of `implementation`.
1467
+ * Once the mock function has been called `times` times,
1468
+ * it will automatically restore the behavior of `original`.
1469
+ * This value must be an integer greater than zero.
1470
+ * @default Infinity
1471
+ */
1472
+ times?: number | undefined;
1473
+ }
1474
+ interface MockMethodOptions extends MockFunctionOptions {
1475
+ /**
1476
+ * If `true`, `object[methodName]` is treated as a getter.
1477
+ * This option cannot be used with the `setter` option.
1478
+ */
1479
+ getter?: boolean | undefined;
1480
+ /**
1481
+ * If `true`, `object[methodName]` is treated as a setter.
1482
+ * This option cannot be used with the `getter` option.
1483
+ */
1484
+ setter?: boolean | undefined;
1485
+ }
1486
+ type Mock<F extends Function> = F & {
1487
+ mock: MockFunctionContext<F>;
1488
+ };
1489
+ interface MockModuleOptions {
1490
+ /**
1491
+ * If false, each call to `require()` or `import()` generates a new mock module.
1492
+ * If true, subsequent calls will return the same module mock, and the mock module is inserted into the CommonJS cache.
1493
+ * @default false
1494
+ */
1495
+ cache?: boolean | undefined;
1496
+ /**
1497
+ * The value to use as the mocked module's default export.
1498
+ *
1499
+ * If this value is not provided, ESM mocks do not include a default export.
1500
+ * If the mock is a CommonJS or builtin module, this setting is used as the value of `module.exports`.
1501
+ * If this value is not provided, CJS and builtin mocks use an empty object as the value of `module.exports`.
1502
+ */
1503
+ defaultExport?: any;
1504
+ /**
1505
+ * An object whose keys and values are used to create the named exports of the mock module.
1506
+ *
1507
+ * If the mock is a CommonJS or builtin module, these values are copied onto `module.exports`.
1508
+ * Therefore, if a mock is created with both named exports and a non-object default export,
1509
+ * the mock will throw an exception when used as a CJS or builtin module.
1510
+ */
1511
+ namedExports?: object | undefined;
1512
+ }
1513
+ /**
1514
+ * The `MockTracker` class is used to manage mocking functionality. The test runner
1515
+ * module provides a top level `mock` export which is a `MockTracker` instance.
1516
+ * Each test also provides its own `MockTracker` instance via the test context's `mock` property.
925
1517
  * @since v19.1.0, v18.13.0
926
- * @return The number of times that this mock has been invoked.
927
1518
  */
928
- callCount(): number;
929
- /**
930
- * This function is used to change the behavior of an existing mock.
931
- *
932
- * The following example creates a mock function using `t.mock.fn()`, calls the
933
- * mock function, and then changes the mock implementation to a different function.
934
- *
935
- * ```js
936
- * test('changes a mock behavior', (t) => {
937
- * let cnt = 0;
938
- *
939
- * function addOne() {
940
- * cnt++;
941
- * return cnt;
942
- * }
943
- *
944
- * function addTwo() {
945
- * cnt += 2;
946
- * return cnt;
947
- * }
948
- *
949
- * const fn = t.mock.fn(addOne);
950
- *
951
- * assert.strictEqual(fn(), 1);
952
- * fn.mock.mockImplementation(addTwo);
953
- * assert.strictEqual(fn(), 3);
954
- * assert.strictEqual(fn(), 5);
955
- * });
956
- * ```
1519
+ interface MockTracker {
1520
+ /**
1521
+ * This function is used to create a mock function.
1522
+ *
1523
+ * The following example creates a mock function that increments a counter by one
1524
+ * on each invocation. The `times` option is used to modify the mock behavior such
1525
+ * that the first two invocations add two to the counter instead of one.
1526
+ *
1527
+ * ```js
1528
+ * test('mocks a counting function', (t) => {
1529
+ * let cnt = 0;
1530
+ *
1531
+ * function addOne() {
1532
+ * cnt++;
1533
+ * return cnt;
1534
+ * }
1535
+ *
1536
+ * function addTwo() {
1537
+ * cnt += 2;
1538
+ * return cnt;
1539
+ * }
1540
+ *
1541
+ * const fn = t.mock.fn(addOne, addTwo, { times: 2 });
1542
+ *
1543
+ * assert.strictEqual(fn(), 2);
1544
+ * assert.strictEqual(fn(), 4);
1545
+ * assert.strictEqual(fn(), 5);
1546
+ * assert.strictEqual(fn(), 6);
1547
+ * });
1548
+ * ```
1549
+ * @since v19.1.0, v18.13.0
1550
+ * @param original An optional function to create a mock on.
1551
+ * @param implementation An optional function used as the mock implementation for `original`. This is useful for creating mocks that exhibit one behavior for a specified number of calls and
1552
+ * then restore the behavior of `original`.
1553
+ * @param options Optional configuration options for the mock function.
1554
+ * @return The mocked function. The mocked function contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the
1555
+ * behavior of the mocked function.
1556
+ */
1557
+ fn<F extends Function = (...args: any[]) => undefined>(
1558
+ original?: F,
1559
+ options?: MockFunctionOptions,
1560
+ ): Mock<F>;
1561
+ fn<F extends Function = (...args: any[]) => undefined, Implementation extends Function = F>(
1562
+ original?: F,
1563
+ implementation?: Implementation,
1564
+ options?: MockFunctionOptions,
1565
+ ): Mock<F | Implementation>;
1566
+ /**
1567
+ * This function is used to create a mock on an existing object method. The
1568
+ * following example demonstrates how a mock is created on an existing object
1569
+ * method.
1570
+ *
1571
+ * ```js
1572
+ * test('spies on an object method', (t) => {
1573
+ * const number = {
1574
+ * value: 5,
1575
+ * subtract(a) {
1576
+ * return this.value - a;
1577
+ * },
1578
+ * };
1579
+ *
1580
+ * t.mock.method(number, 'subtract');
1581
+ * assert.strictEqual(number.subtract.mock.calls.length, 0);
1582
+ * assert.strictEqual(number.subtract(3), 2);
1583
+ * assert.strictEqual(number.subtract.mock.calls.length, 1);
1584
+ *
1585
+ * const call = number.subtract.mock.calls[0];
1586
+ *
1587
+ * assert.deepStrictEqual(call.arguments, [3]);
1588
+ * assert.strictEqual(call.result, 2);
1589
+ * assert.strictEqual(call.error, undefined);
1590
+ * assert.strictEqual(call.target, undefined);
1591
+ * assert.strictEqual(call.this, number);
1592
+ * });
1593
+ * ```
1594
+ * @since v19.1.0, v18.13.0
1595
+ * @param object The object whose method is being mocked.
1596
+ * @param methodName The identifier of the method on `object` to mock. If `object[methodName]` is not a function, an error is thrown.
1597
+ * @param implementation An optional function used as the mock implementation for `object[methodName]`.
1598
+ * @param options Optional configuration options for the mock method.
1599
+ * @return The mocked method. The mocked method contains a special `mock` property, which is an instance of {@link MockFunctionContext}, and can be used for inspecting and changing the
1600
+ * behavior of the mocked method.
1601
+ */
1602
+ method<
1603
+ MockedObject extends object,
1604
+ MethodName extends FunctionPropertyNames<MockedObject>,
1605
+ >(
1606
+ object: MockedObject,
1607
+ methodName: MethodName,
1608
+ options?: MockFunctionOptions,
1609
+ ): MockedObject[MethodName] extends Function ? Mock<MockedObject[MethodName]>
1610
+ : never;
1611
+ method<
1612
+ MockedObject extends object,
1613
+ MethodName extends FunctionPropertyNames<MockedObject>,
1614
+ Implementation extends Function,
1615
+ >(
1616
+ object: MockedObject,
1617
+ methodName: MethodName,
1618
+ implementation: Implementation,
1619
+ options?: MockFunctionOptions,
1620
+ ): MockedObject[MethodName] extends Function ? Mock<MockedObject[MethodName] | Implementation>
1621
+ : never;
1622
+ method<MockedObject extends object>(
1623
+ object: MockedObject,
1624
+ methodName: keyof MockedObject,
1625
+ options: MockMethodOptions,
1626
+ ): Mock<Function>;
1627
+ method<MockedObject extends object>(
1628
+ object: MockedObject,
1629
+ methodName: keyof MockedObject,
1630
+ implementation: Function,
1631
+ options: MockMethodOptions,
1632
+ ): Mock<Function>;
1633
+ /**
1634
+ * This function is syntax sugar for `MockTracker.method` with `options.getter` set to `true`.
1635
+ * @since v19.3.0, v18.13.0
1636
+ */
1637
+ getter<
1638
+ MockedObject extends object,
1639
+ MethodName extends keyof MockedObject,
1640
+ >(
1641
+ object: MockedObject,
1642
+ methodName: MethodName,
1643
+ options?: MockFunctionOptions,
1644
+ ): Mock<() => MockedObject[MethodName]>;
1645
+ getter<
1646
+ MockedObject extends object,
1647
+ MethodName extends keyof MockedObject,
1648
+ Implementation extends Function,
1649
+ >(
1650
+ object: MockedObject,
1651
+ methodName: MethodName,
1652
+ implementation?: Implementation,
1653
+ options?: MockFunctionOptions,
1654
+ ): Mock<(() => MockedObject[MethodName]) | Implementation>;
1655
+ /**
1656
+ * This function is syntax sugar for `MockTracker.method` with `options.setter` set to `true`.
1657
+ * @since v19.3.0, v18.13.0
1658
+ */
1659
+ setter<
1660
+ MockedObject extends object,
1661
+ MethodName extends keyof MockedObject,
1662
+ >(
1663
+ object: MockedObject,
1664
+ methodName: MethodName,
1665
+ options?: MockFunctionOptions,
1666
+ ): Mock<(value: MockedObject[MethodName]) => void>;
1667
+ setter<
1668
+ MockedObject extends object,
1669
+ MethodName extends keyof MockedObject,
1670
+ Implementation extends Function,
1671
+ >(
1672
+ object: MockedObject,
1673
+ methodName: MethodName,
1674
+ implementation?: Implementation,
1675
+ options?: MockFunctionOptions,
1676
+ ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>;
1677
+ /**
1678
+ * This function is used to mock the exports of ECMAScript modules, CommonJS modules, JSON modules, and
1679
+ * Node.js builtin modules. Any references to the original module prior to mocking are not impacted. In
1680
+ * order to enable module mocking, Node.js must be started with the
1681
+ * [`--experimental-test-module-mocks`](https://nodejs.org/docs/latest-v24.x/api/cli.html#--experimental-test-module-mocks)
1682
+ * command-line flag.
1683
+ *
1684
+ * The following example demonstrates how a mock is created for a module.
1685
+ *
1686
+ * ```js
1687
+ * test('mocks a builtin module in both module systems', async (t) => {
1688
+ * // Create a mock of 'node:readline' with a named export named 'fn', which
1689
+ * // does not exist in the original 'node:readline' module.
1690
+ * const mock = t.mock.module('node:readline', {
1691
+ * namedExports: { fn() { return 42; } },
1692
+ * });
1693
+ *
1694
+ * let esmImpl = await import('node:readline');
1695
+ * let cjsImpl = require('node:readline');
1696
+ *
1697
+ * // cursorTo() is an export of the original 'node:readline' module.
1698
+ * assert.strictEqual(esmImpl.cursorTo, undefined);
1699
+ * assert.strictEqual(cjsImpl.cursorTo, undefined);
1700
+ * assert.strictEqual(esmImpl.fn(), 42);
1701
+ * assert.strictEqual(cjsImpl.fn(), 42);
1702
+ *
1703
+ * mock.restore();
1704
+ *
1705
+ * // The mock is restored, so the original builtin module is returned.
1706
+ * esmImpl = await import('node:readline');
1707
+ * cjsImpl = require('node:readline');
1708
+ *
1709
+ * assert.strictEqual(typeof esmImpl.cursorTo, 'function');
1710
+ * assert.strictEqual(typeof cjsImpl.cursorTo, 'function');
1711
+ * assert.strictEqual(esmImpl.fn, undefined);
1712
+ * assert.strictEqual(cjsImpl.fn, undefined);
1713
+ * });
1714
+ * ```
1715
+ * @since v22.3.0
1716
+ * @experimental
1717
+ * @param specifier A string identifying the module to mock.
1718
+ * @param options Optional configuration options for the mock module.
1719
+ */
1720
+ module(specifier: string | URL, options?: MockModuleOptions): MockModuleContext;
1721
+ /**
1722
+ * Creates a mock for a property value on an object. This allows you to track and control access to a specific property,
1723
+ * including how many times it is read (getter) or written (setter), and to restore the original value after mocking.
1724
+ *
1725
+ * ```js
1726
+ * test('mocks a property value', (t) => {
1727
+ * const obj = { foo: 42 };
1728
+ * const prop = t.mock.property(obj, 'foo', 100);
1729
+ *
1730
+ * assert.strictEqual(obj.foo, 100);
1731
+ * assert.strictEqual(prop.mock.accessCount(), 1);
1732
+ * assert.strictEqual(prop.mock.accesses[0].type, 'get');
1733
+ * assert.strictEqual(prop.mock.accesses[0].value, 100);
1734
+ *
1735
+ * obj.foo = 200;
1736
+ * assert.strictEqual(prop.mock.accessCount(), 2);
1737
+ * assert.strictEqual(prop.mock.accesses[1].type, 'set');
1738
+ * assert.strictEqual(prop.mock.accesses[1].value, 200);
1739
+ *
1740
+ * prop.mock.restore();
1741
+ * assert.strictEqual(obj.foo, 42);
1742
+ * });
1743
+ * ```
1744
+ * @since v24.3.0
1745
+ * @param object The object whose value is being mocked.
1746
+ * @param propertyName The identifier of the property on `object` to mock.
1747
+ * @param value An optional value used as the mock value
1748
+ * for `object[propertyName]`. **Default:** The original property value.
1749
+ * @returns A proxy to the mocked object. The mocked object contains a
1750
+ * special `mock` property, which is an instance of [`MockPropertyContext`][], and
1751
+ * can be used for inspecting and changing the behavior of the mocked property.
1752
+ */
1753
+ property<
1754
+ MockedObject extends object,
1755
+ PropertyName extends keyof MockedObject,
1756
+ >(
1757
+ object: MockedObject,
1758
+ property: PropertyName,
1759
+ value?: MockedObject[PropertyName],
1760
+ ): MockedObject & { mock: MockPropertyContext<MockedObject[PropertyName]> };
1761
+ /**
1762
+ * This function restores the default behavior of all mocks that were previously
1763
+ * created by this `MockTracker` and disassociates the mocks from the `MockTracker` instance. Once disassociated, the mocks can still be used, but the `MockTracker` instance can no longer be
1764
+ * used to reset their behavior or
1765
+ * otherwise interact with them.
1766
+ *
1767
+ * After each test completes, this function is called on the test context's `MockTracker`. If the global `MockTracker` is used extensively, calling this
1768
+ * function manually is recommended.
1769
+ * @since v19.1.0, v18.13.0
1770
+ */
1771
+ reset(): void;
1772
+ /**
1773
+ * This function restores the default behavior of all mocks that were previously
1774
+ * created by this `MockTracker`. Unlike `mock.reset()`, `mock.restoreAll()` does
1775
+ * not disassociate the mocks from the `MockTracker` instance.
1776
+ * @since v19.1.0, v18.13.0
1777
+ */
1778
+ restoreAll(): void;
1779
+ readonly timers: MockTimers;
1780
+ }
1781
+ const mock: MockTracker;
1782
+ interface MockFunctionCall<
1783
+ F extends Function,
1784
+ ReturnType = F extends (...args: any) => infer T ? T
1785
+ : F extends abstract new(...args: any) => infer T ? T
1786
+ : unknown,
1787
+ Args = F extends (...args: infer Y) => any ? Y
1788
+ : F extends abstract new(...args: infer Y) => any ? Y
1789
+ : unknown[],
1790
+ > {
1791
+ /**
1792
+ * An array of the arguments passed to the mock function.
1793
+ */
1794
+ arguments: Args;
1795
+ /**
1796
+ * If the mocked function threw then this property contains the thrown value.
1797
+ */
1798
+ error: unknown | undefined;
1799
+ /**
1800
+ * The value returned by the mocked function.
1801
+ *
1802
+ * If the mocked function threw, it will be `undefined`.
1803
+ */
1804
+ result: ReturnType | undefined;
1805
+ /**
1806
+ * An `Error` object whose stack can be used to determine the callsite of the mocked function invocation.
1807
+ */
1808
+ stack: Error;
1809
+ /**
1810
+ * If the mocked function is a constructor, this field contains the class being constructed.
1811
+ * Otherwise this will be `undefined`.
1812
+ */
1813
+ target: F extends abstract new(...args: any) => any ? F : undefined;
1814
+ /**
1815
+ * The mocked function's `this` value.
1816
+ */
1817
+ this: unknown;
1818
+ }
1819
+ /**
1820
+ * The `MockFunctionContext` class is used to inspect or manipulate the behavior of
1821
+ * mocks created via the `MockTracker` APIs.
957
1822
  * @since v19.1.0, v18.13.0
958
- * @param implementation The function to be used as the mock's new implementation.
959
1823
  */
960
- mockImplementation(implementation: Function): void;
961
- /**
962
- * This function is used to change the behavior of an existing mock for a single
963
- * invocation. Once invocation `onCall` has occurred, the mock will revert to
964
- * whatever behavior it would have used had `mockImplementationOnce()` not been
965
- * called.
966
- *
967
- * The following example creates a mock function using `t.mock.fn()`, calls the
968
- * mock function, changes the mock implementation to a different function for the
969
- * next invocation, and then resumes its previous behavior.
1824
+ interface MockFunctionContext<F extends Function> {
1825
+ /**
1826
+ * A getter that returns a copy of the internal array used to track calls to the
1827
+ * mock. Each entry in the array is an object with the following properties.
1828
+ * @since v19.1.0, v18.13.0
1829
+ */
1830
+ readonly calls: MockFunctionCall<F>[];
1831
+ /**
1832
+ * This function returns the number of times that this mock has been invoked. This
1833
+ * function is more efficient than checking `ctx.calls.length` because `ctx.calls` is a getter that creates a copy of the internal call tracking array.
1834
+ * @since v19.1.0, v18.13.0
1835
+ * @return The number of times that this mock has been invoked.
1836
+ */
1837
+ callCount(): number;
1838
+ /**
1839
+ * This function is used to change the behavior of an existing mock.
1840
+ *
1841
+ * The following example creates a mock function using `t.mock.fn()`, calls the
1842
+ * mock function, and then changes the mock implementation to a different function.
1843
+ *
1844
+ * ```js
1845
+ * test('changes a mock behavior', (t) => {
1846
+ * let cnt = 0;
1847
+ *
1848
+ * function addOne() {
1849
+ * cnt++;
1850
+ * return cnt;
1851
+ * }
1852
+ *
1853
+ * function addTwo() {
1854
+ * cnt += 2;
1855
+ * return cnt;
1856
+ * }
1857
+ *
1858
+ * const fn = t.mock.fn(addOne);
1859
+ *
1860
+ * assert.strictEqual(fn(), 1);
1861
+ * fn.mock.mockImplementation(addTwo);
1862
+ * assert.strictEqual(fn(), 3);
1863
+ * assert.strictEqual(fn(), 5);
1864
+ * });
1865
+ * ```
1866
+ * @since v19.1.0, v18.13.0
1867
+ * @param implementation The function to be used as the mock's new implementation.
1868
+ */
1869
+ mockImplementation(implementation: F): void;
1870
+ /**
1871
+ * This function is used to change the behavior of an existing mock for a single
1872
+ * invocation. Once invocation `onCall` has occurred, the mock will revert to
1873
+ * whatever behavior it would have used had `mockImplementationOnce()` not been
1874
+ * called.
1875
+ *
1876
+ * The following example creates a mock function using `t.mock.fn()`, calls the
1877
+ * mock function, changes the mock implementation to a different function for the
1878
+ * next invocation, and then resumes its previous behavior.
1879
+ *
1880
+ * ```js
1881
+ * test('changes a mock behavior once', (t) => {
1882
+ * let cnt = 0;
1883
+ *
1884
+ * function addOne() {
1885
+ * cnt++;
1886
+ * return cnt;
1887
+ * }
1888
+ *
1889
+ * function addTwo() {
1890
+ * cnt += 2;
1891
+ * return cnt;
1892
+ * }
1893
+ *
1894
+ * const fn = t.mock.fn(addOne);
1895
+ *
1896
+ * assert.strictEqual(fn(), 1);
1897
+ * fn.mock.mockImplementationOnce(addTwo);
1898
+ * assert.strictEqual(fn(), 3);
1899
+ * assert.strictEqual(fn(), 4);
1900
+ * });
1901
+ * ```
1902
+ * @since v19.1.0, v18.13.0
1903
+ * @param implementation The function to be used as the mock's implementation for the invocation number specified by `onCall`.
1904
+ * @param onCall The invocation number that will use `implementation`. If the specified invocation has already occurred then an exception is thrown.
1905
+ */
1906
+ mockImplementationOnce(implementation: F, onCall?: number): void;
1907
+ /**
1908
+ * Resets the call history of the mock function.
1909
+ * @since v19.3.0, v18.13.0
1910
+ */
1911
+ resetCalls(): void;
1912
+ /**
1913
+ * Resets the implementation of the mock function to its original behavior. The
1914
+ * mock can still be used after calling this function.
1915
+ * @since v19.1.0, v18.13.0
1916
+ */
1917
+ restore(): void;
1918
+ }
1919
+ /**
1920
+ * @since v22.3.0
1921
+ * @experimental
1922
+ */
1923
+ interface MockModuleContext {
1924
+ /**
1925
+ * Resets the implementation of the mock module.
1926
+ * @since v22.3.0
1927
+ */
1928
+ restore(): void;
1929
+ }
1930
+ /**
1931
+ * @since v24.3.0
1932
+ */
1933
+ class MockPropertyContext<PropertyType = any> {
1934
+ /**
1935
+ * A getter that returns a copy of the internal array used to track accesses (get/set) to
1936
+ * the mocked property. Each entry in the array is an object with the following properties:
1937
+ */
1938
+ readonly accesses: Array<{
1939
+ type: "get" | "set";
1940
+ value: PropertyType;
1941
+ stack: Error;
1942
+ }>;
1943
+ /**
1944
+ * This function returns the number of times that the property was accessed.
1945
+ * This function is more efficient than checking `ctx.accesses.length` because
1946
+ * `ctx.accesses` is a getter that creates a copy of the internal access tracking array.
1947
+ * @returns The number of times that the property was accessed (read or written).
1948
+ */
1949
+ accessCount(): number;
1950
+ /**
1951
+ * This function is used to change the value returned by the mocked property getter.
1952
+ * @param value The new value to be set as the mocked property value.
1953
+ */
1954
+ mockImplementation(value: PropertyType): void;
1955
+ /**
1956
+ * This function is used to change the behavior of an existing mock for a single
1957
+ * invocation. Once invocation `onAccess` has occurred, the mock will revert to
1958
+ * whatever behavior it would have used had `mockImplementationOnce()` not been
1959
+ * called.
1960
+ *
1961
+ * The following example creates a mock function using `t.mock.property()`, calls the
1962
+ * mock property, changes the mock implementation to a different value for the
1963
+ * next invocation, and then resumes its previous behavior.
1964
+ *
1965
+ * ```js
1966
+ * test('changes a mock behavior once', (t) => {
1967
+ * const obj = { foo: 1 };
1968
+ *
1969
+ * const prop = t.mock.property(obj, 'foo', 5);
1970
+ *
1971
+ * assert.strictEqual(obj.foo, 5);
1972
+ * prop.mock.mockImplementationOnce(25);
1973
+ * assert.strictEqual(obj.foo, 25);
1974
+ * assert.strictEqual(obj.foo, 5);
1975
+ * });
1976
+ * ```
1977
+ * @param value The value to be used as the mock's
1978
+ * implementation for the invocation number specified by `onAccess`.
1979
+ * @param onAccess The invocation number that will use `value`. If
1980
+ * the specified invocation has already occurred then an exception is thrown.
1981
+ * **Default:** The number of the next invocation.
1982
+ */
1983
+ mockImplementationOnce(value: PropertyType, onAccess?: number): void;
1984
+ /**
1985
+ * Resets the access history of the mocked property.
1986
+ */
1987
+ resetAccesses(): void;
1988
+ /**
1989
+ * Resets the implementation of the mock property to its original behavior. The
1990
+ * mock can still be used after calling this function.
1991
+ */
1992
+ restore(): void;
1993
+ }
1994
+ interface MockTimersOptions {
1995
+ apis: ReadonlyArray<"setInterval" | "setTimeout" | "setImmediate" | "Date">;
1996
+ now?: number | Date | undefined;
1997
+ }
1998
+ /**
1999
+ * Mocking timers is a technique commonly used in software testing to simulate and
2000
+ * control the behavior of timers, such as `setInterval` and `setTimeout`,
2001
+ * without actually waiting for the specified time intervals.
970
2002
  *
971
- * ```js
972
- * test('changes a mock behavior once', (t) => {
973
- * let cnt = 0;
2003
+ * The MockTimers API also allows for mocking of the `Date` constructor and
2004
+ * `setImmediate`/`clearImmediate` functions.
974
2005
  *
975
- * function addOne() {
976
- * cnt++;
977
- * return cnt;
978
- * }
979
- *
980
- * function addTwo() {
981
- * cnt += 2;
982
- * return cnt;
983
- * }
984
- *
985
- * const fn = t.mock.fn(addOne);
986
- *
987
- * assert.strictEqual(fn(), 1);
988
- * fn.mock.mockImplementationOnce(addTwo);
989
- * assert.strictEqual(fn(), 3);
990
- * assert.strictEqual(fn(), 4);
991
- * });
992
- * ```
993
- * @since v19.1.0, v18.13.0
994
- * @param implementation The function to be used as the mock's implementation for the invocation number specified by `onCall`.
995
- * @param onCall The invocation number that will use `implementation`. If the specified invocation has already occurred then an exception is thrown.
996
- */
997
- mockImplementationOnce(implementation: Function, onCall?: number): void;
998
- /**
999
- * Resets the call history of the mock function.
1000
- * @since v19.3.0, v18.13.0
1001
- */
1002
- resetCalls(): void;
1003
- /**
1004
- * Resets the implementation of the mock function to its original behavior. The
1005
- * mock can still be used after calling this function.
1006
- * @since v19.1.0, v18.13.0
1007
- */
1008
- restore(): void;
1009
- }
1010
- type Timer = "setInterval" | "clearInterval" | "setTimeout" | "clearTimeout";
1011
- /**
1012
- * Mocking timers is a technique commonly used in software testing to simulate and
1013
- * control the behavior of timers, such as `setInterval` and `setTimeout`,
1014
- * without actually waiting for the specified time intervals.
1015
- *
1016
- * The `MockTracker` provides a top-level `timers` export
1017
- * which is a `MockTimers` instance.
1018
- * @since v20.4.0
1019
- * @experimental
1020
- */
1021
- class MockTimers {
1022
- /**
1023
- * Enables timer mocking for the specified timers.
1024
- *
1025
- * **Note:** When you enable mocking for a specific timer, its associated
1026
- * clear function will also be implicitly mocked.
1027
- *
1028
- * Example usage:
1029
- *
1030
- * ```js
1031
- * import { mock } from 'node:test';
1032
- * mock.timers.enable(['setInterval']);
1033
- * ```
1034
- *
1035
- * The above example enables mocking for the `setInterval` timer and
1036
- * implicitly mocks the `clearInterval` function. Only the `setInterval`and `clearInterval` functions from `node:timers`,`node:timers/promises`, and`globalThis` will be mocked.
1037
- *
1038
- * Alternatively, if you call `mock.timers.enable()` without any parameters:
1039
- *
1040
- * All timers (`'setInterval'`, `'clearInterval'`, `'setTimeout'`, and `'clearTimeout'`)
1041
- * will be mocked. The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout`functions from `node:timers`, `node:timers/promises`,
1042
- * and `globalThis` will be mocked.
2006
+ * The `MockTracker` provides a top-level `timers` export
2007
+ * which is a `MockTimers` instance.
1043
2008
  * @since v20.4.0
1044
2009
  */
1045
- enable(timers?: Timer[]): void;
1046
- /**
1047
- * This function restores the default behavior of all mocks that were previously
1048
- * created by this `MockTimers` instance and disassociates the mocks
1049
- * from the `MockTracker` instance.
1050
- *
1051
- * **Note:** After each test completes, this function is called on
1052
- * the test context's `MockTracker`.
1053
- *
1054
- * ```js
1055
- * import { mock } from 'node:test';
1056
- * mock.timers.reset();
1057
- * ```
1058
- * @since v20.4.0
1059
- */
1060
- reset(): void;
1061
- /**
1062
- * Advances time for all mocked timers.
1063
- *
1064
- * **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts
1065
- * only positive numbers. In Node.js, `setTimeout` with negative numbers is
1066
- * only supported for web compatibility reasons.
1067
- *
1068
- * The following example mocks a `setTimeout` function and
1069
- * by using `.tick` advances in
1070
- * time triggering all pending timers.
1071
- *
1072
- * ```js
1073
- * import assert from 'node:assert';
1074
- * import { test } from 'node:test';
1075
- *
1076
- * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
1077
- * const fn = context.mock.fn();
1078
- *
1079
- * context.mock.timers.enable(['setTimeout']);
1080
- *
1081
- * setTimeout(fn, 9999);
1082
- *
1083
- * assert.strictEqual(fn.mock.callCount(), 0);
1084
- *
1085
- * // Advance in time
1086
- * context.mock.timers.tick(9999);
1087
- *
1088
- * assert.strictEqual(fn.mock.callCount(), 1);
1089
- * });
1090
- * ```
1091
- *
1092
- * Alternativelly, the `.tick` function can be called many times
1093
- *
1094
- * ```js
1095
- * import assert from 'node:assert';
1096
- * import { test } from 'node:test';
1097
- *
1098
- * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
1099
- * const fn = context.mock.fn();
1100
- * context.mock.timers.enable(['setTimeout']);
1101
- * const nineSecs = 9000;
1102
- * setTimeout(fn, nineSecs);
1103
- *
1104
- * const twoSeconds = 3000;
1105
- * context.mock.timers.tick(twoSeconds);
1106
- * context.mock.timers.tick(twoSeconds);
1107
- * context.mock.timers.tick(twoSeconds);
1108
- *
1109
- * assert.strictEqual(fn.mock.callCount(), 1);
1110
- * });
1111
- * ```
1112
- * @since v20.4.0
1113
- */
1114
- tick(milliseconds: number): void;
1115
- /**
1116
- * Triggers all pending mocked timers immediately.
1117
- *
1118
- * The example below triggers all pending timers immediately,
1119
- * causing them to execute without any delay.
1120
- *
1121
- * ```js
1122
- * import assert from 'node:assert';
1123
- * import { test } from 'node:test';
1124
- *
1125
- * test('runAll functions following the given order', (context) => {
1126
- * context.mock.timers.enable(['setTimeout']);
1127
- * const results = [];
1128
- * setTimeout(() => results.push(1), 9999);
1129
- *
1130
- * // Notice that if both timers have the same timeout,
1131
- * // the order of execution is guaranteed
1132
- * setTimeout(() => results.push(3), 8888);
1133
- * setTimeout(() => results.push(2), 8888);
2010
+ interface MockTimers {
2011
+ /**
2012
+ * Enables timer mocking for the specified timers.
2013
+ *
2014
+ * **Note:** When you enable mocking for a specific timer, its associated
2015
+ * clear function will also be implicitly mocked.
2016
+ *
2017
+ * **Note:** Mocking `Date` will affect the behavior of the mocked timers
2018
+ * as they use the same internal clock.
2019
+ *
2020
+ * Example usage without setting initial time:
2021
+ *
2022
+ * ```js
2023
+ * import { mock } from 'node:test';
2024
+ * mock.timers.enable({ apis: ['setInterval', 'Date'], now: 1234 });
2025
+ * ```
2026
+ *
2027
+ * The above example enables mocking for the `Date` constructor, `setInterval` timer and
2028
+ * implicitly mocks the `clearInterval` function. Only the `Date` constructor from `globalThis`,
2029
+ * `setInterval` and `clearInterval` functions from `node:timers`, `node:timers/promises`, and `globalThis` will be mocked.
2030
+ *
2031
+ * Example usage with initial time set
2032
+ *
2033
+ * ```js
2034
+ * import { mock } from 'node:test';
2035
+ * mock.timers.enable({ apis: ['Date'], now: 1000 });
2036
+ * ```
2037
+ *
2038
+ * Example usage with initial Date object as time set
2039
+ *
2040
+ * ```js
2041
+ * import { mock } from 'node:test';
2042
+ * mock.timers.enable({ apis: ['Date'], now: new Date() });
2043
+ * ```
2044
+ *
2045
+ * Alternatively, if you call `mock.timers.enable()` without any parameters:
2046
+ *
2047
+ * All timers (`'setInterval'`, `'clearInterval'`, `'Date'`, `'setImmediate'`, `'clearImmediate'`, `'setTimeout'`, and `'clearTimeout'`)
2048
+ * will be mocked.
2049
+ *
2050
+ * The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout` functions from `node:timers`, `node:timers/promises`,
2051
+ * and `globalThis` will be mocked.
2052
+ * The `Date` constructor from `globalThis` will be mocked.
2053
+ *
2054
+ * If there is no initial epoch set, the initial date will be based on 0 in the Unix epoch. This is `January 1st, 1970, 00:00:00 UTC`. You can
2055
+ * set an initial date by passing a now property to the `.enable()` method. This value will be used as the initial date for the mocked Date
2056
+ * object. It can either be a positive integer, or another Date object.
2057
+ * @since v20.4.0
2058
+ */
2059
+ enable(options?: MockTimersOptions): void;
2060
+ /**
2061
+ * Sets the current Unix timestamp that will be used as reference for any mocked
2062
+ * `Date` objects.
2063
+ *
2064
+ * ```js
2065
+ * import assert from 'node:assert';
2066
+ * import { test } from 'node:test';
2067
+ *
2068
+ * test('runAll functions following the given order', (context) => {
2069
+ * const now = Date.now();
2070
+ * const setTime = 1000;
2071
+ * // Date.now is not mocked
2072
+ * assert.deepStrictEqual(Date.now(), now);
2073
+ *
2074
+ * context.mock.timers.enable({ apis: ['Date'] });
2075
+ * context.mock.timers.setTime(setTime);
2076
+ * // Date.now is now 1000
2077
+ * assert.strictEqual(Date.now(), setTime);
2078
+ * });
2079
+ * ```
2080
+ * @since v21.2.0, v20.11.0
2081
+ */
2082
+ setTime(milliseconds: number): void;
2083
+ /**
2084
+ * This function restores the default behavior of all mocks that were previously
2085
+ * created by this `MockTimers` instance and disassociates the mocks
2086
+ * from the `MockTracker` instance.
2087
+ *
2088
+ * **Note:** After each test completes, this function is called on
2089
+ * the test context's `MockTracker`.
2090
+ *
2091
+ * ```js
2092
+ * import { mock } from 'node:test';
2093
+ * mock.timers.reset();
2094
+ * ```
2095
+ * @since v20.4.0
2096
+ */
2097
+ reset(): void;
2098
+ /**
2099
+ * Advances time for all mocked timers.
2100
+ *
2101
+ * **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts
2102
+ * only positive numbers. In Node.js, `setTimeout` with negative numbers is
2103
+ * only supported for web compatibility reasons.
2104
+ *
2105
+ * The following example mocks a `setTimeout` function and
2106
+ * by using `.tick` advances in
2107
+ * time triggering all pending timers.
2108
+ *
2109
+ * ```js
2110
+ * import assert from 'node:assert';
2111
+ * import { test } from 'node:test';
2112
+ *
2113
+ * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
2114
+ * const fn = context.mock.fn();
2115
+ *
2116
+ * context.mock.timers.enable({ apis: ['setTimeout'] });
2117
+ *
2118
+ * setTimeout(fn, 9999);
2119
+ *
2120
+ * assert.strictEqual(fn.mock.callCount(), 0);
2121
+ *
2122
+ * // Advance in time
2123
+ * context.mock.timers.tick(9999);
2124
+ *
2125
+ * assert.strictEqual(fn.mock.callCount(), 1);
2126
+ * });
2127
+ * ```
2128
+ *
2129
+ * Alternativelly, the `.tick` function can be called many times
2130
+ *
2131
+ * ```js
2132
+ * import assert from 'node:assert';
2133
+ * import { test } from 'node:test';
2134
+ *
2135
+ * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
2136
+ * const fn = context.mock.fn();
2137
+ * context.mock.timers.enable({ apis: ['setTimeout'] });
2138
+ * const nineSecs = 9000;
2139
+ * setTimeout(fn, nineSecs);
2140
+ *
2141
+ * const twoSeconds = 3000;
2142
+ * context.mock.timers.tick(twoSeconds);
2143
+ * context.mock.timers.tick(twoSeconds);
2144
+ * context.mock.timers.tick(twoSeconds);
2145
+ *
2146
+ * assert.strictEqual(fn.mock.callCount(), 1);
2147
+ * });
2148
+ * ```
2149
+ *
2150
+ * Advancing time using `.tick` will also advance the time for any `Date` object
2151
+ * created after the mock was enabled (if `Date` was also set to be mocked).
2152
+ *
2153
+ * ```js
2154
+ * import assert from 'node:assert';
2155
+ * import { test } from 'node:test';
2156
+ *
2157
+ * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
2158
+ * const fn = context.mock.fn();
2159
+ *
2160
+ * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
2161
+ * setTimeout(fn, 9999);
2162
+ *
2163
+ * assert.strictEqual(fn.mock.callCount(), 0);
2164
+ * assert.strictEqual(Date.now(), 0);
2165
+ *
2166
+ * // Advance in time
2167
+ * context.mock.timers.tick(9999);
2168
+ * assert.strictEqual(fn.mock.callCount(), 1);
2169
+ * assert.strictEqual(Date.now(), 9999);
2170
+ * });
2171
+ * ```
2172
+ * @since v20.4.0
2173
+ */
2174
+ tick(milliseconds: number): void;
2175
+ /**
2176
+ * Triggers all pending mocked timers immediately. If the `Date` object is also
2177
+ * mocked, it will also advance the `Date` object to the furthest timer's time.
2178
+ *
2179
+ * The example below triggers all pending timers immediately,
2180
+ * causing them to execute without any delay.
2181
+ *
2182
+ * ```js
2183
+ * import assert from 'node:assert';
2184
+ * import { test } from 'node:test';
2185
+ *
2186
+ * test('runAll functions following the given order', (context) => {
2187
+ * context.mock.timers.enable({ apis: ['setTimeout', 'Date'] });
2188
+ * const results = [];
2189
+ * setTimeout(() => results.push(1), 9999);
2190
+ *
2191
+ * // Notice that if both timers have the same timeout,
2192
+ * // the order of execution is guaranteed
2193
+ * setTimeout(() => results.push(3), 8888);
2194
+ * setTimeout(() => results.push(2), 8888);
2195
+ *
2196
+ * assert.deepStrictEqual(results, []);
2197
+ *
2198
+ * context.mock.timers.runAll();
2199
+ * assert.deepStrictEqual(results, [3, 2, 1]);
2200
+ * // The Date object is also advanced to the furthest timer's time
2201
+ * assert.strictEqual(Date.now(), 9999);
2202
+ * });
2203
+ * ```
2204
+ *
2205
+ * **Note:** The `runAll()` function is specifically designed for
2206
+ * triggering timers in the context of timer mocking.
2207
+ * It does not have any effect on real-time system
2208
+ * clocks or actual timers outside of the mocking environment.
2209
+ * @since v20.4.0
2210
+ */
2211
+ runAll(): void;
2212
+ /**
2213
+ * Calls {@link MockTimers.reset()}.
2214
+ */
2215
+ [Symbol.dispose](): void;
2216
+ }
2217
+ /**
2218
+ * An object whose methods are used to configure available assertions on the
2219
+ * `TestContext` objects in the current process. The methods from `node:assert`
2220
+ * and snapshot testing functions are available by default.
1134
2221
  *
1135
- * assert.deepStrictEqual(results, []);
1136
- *
1137
- * context.mock.timers.runAll();
1138
- *
1139
- * assert.deepStrictEqual(results, [3, 2, 1]);
1140
- * });
1141
- * ```
1142
- *
1143
- * **Note:** The `runAll()` function is specifically designed for
1144
- * triggering timers in the context of timer mocking.
1145
- * It does not have any effect on real-time system
1146
- * clocks or actual timers outside of the mocking environment.
1147
- * @since v20.4.0
1148
- */
1149
- runAll(): void;
1150
- /**
1151
- * Calls {@link MockTimers.reset()}.
1152
- */
1153
- [Symbol.dispose](): void;
2222
+ * It is possible to apply the same configuration to all files by placing common
2223
+ * configuration code in a module
2224
+ * preloaded with `--require` or `--import`.
2225
+ * @since v22.14.0
2226
+ */
2227
+ namespace assert {
2228
+ /**
2229
+ * Defines a new assertion function with the provided name and function. If an
2230
+ * assertion already exists with the same name, it is overwritten.
2231
+ * @since v22.14.0
2232
+ */
2233
+ function register(name: string, fn: (this: TestContext, ...args: any[]) => void): void;
2234
+ }
2235
+ /**
2236
+ * @since v22.3.0
2237
+ */
2238
+ namespace snapshot {
2239
+ /**
2240
+ * This function is used to customize the default serialization mechanism used by the test runner.
2241
+ *
2242
+ * By default, the test runner performs serialization by calling `JSON.stringify(value, null, 2)` on the provided value.
2243
+ * `JSON.stringify()` does have limitations regarding circular structures and supported data types.
2244
+ * If a more robust serialization mechanism is required, this function should be used to specify a list of custom serializers.
2245
+ *
2246
+ * Serializers are called in order, with the output of the previous serializer passed as input to the next.
2247
+ * The final result must be a string value.
2248
+ * @since v22.3.0
2249
+ * @param serializers An array of synchronous functions used as the default serializers for snapshot tests.
2250
+ */
2251
+ function setDefaultSnapshotSerializers(serializers: ReadonlyArray<(value: any) => any>): void;
2252
+ /**
2253
+ * This function is used to set a custom resolver for the location of the snapshot file used for snapshot testing.
2254
+ * By default, the snapshot filename is the same as the entry point filename with `.snapshot` appended.
2255
+ * @since v22.3.0
2256
+ * @param fn A function used to compute the location of the snapshot file.
2257
+ * The function receives the path of the test file as its only argument. If the
2258
+ * test is not associated with a file (for example in the REPL), the input is
2259
+ * undefined. `fn()` must return a string specifying the location of the snapshot file.
2260
+ */
2261
+ function setResolveSnapshotPath(fn: (path: string | undefined) => string): void;
2262
+ }
1154
2263
  }
1155
- export {
1156
- after,
1157
- afterEach,
1158
- before,
1159
- beforeEach,
1160
- describe,
1161
- it,
1162
- Mock,
1163
- mock,
1164
- only,
1165
- run,
1166
- skip,
1167
- test,
1168
- test as default,
1169
- todo,
1170
- };
1171
- }
1172
-
1173
- interface TestLocationInfo {
1174
- /**
1175
- * The column number where the test is defined, or
1176
- * `undefined` if the test was run through the REPL.
1177
- */
1178
- column?: number;
1179
- /**
1180
- * The path of the test file, `undefined` if test is not ran through a file.
1181
- */
1182
- file?: string;
1183
- /**
1184
- * The line number where the test is defined, or
1185
- * `undefined` if the test was run through the REPL.
1186
- */
1187
- line?: number;
1188
- }
1189
- interface DiagnosticData extends TestLocationInfo {
1190
- /**
1191
- * The diagnostic message.
1192
- */
1193
- message: string;
1194
- /**
1195
- * The nesting level of the test.
1196
- */
1197
- nesting: number;
1198
- }
1199
- interface TestFail extends TestLocationInfo {
1200
- /**
1201
- * Additional execution metadata.
1202
- */
1203
- details: {
1204
- /**
1205
- * The duration of the test in milliseconds.
1206
- */
1207
- duration_ms: number;
1208
- /**
1209
- * The error thrown by the test.
1210
- */
1211
- error: Error;
1212
- /**
1213
- * The type of the test, used to denote whether this is a suite.
1214
- * @since 20.0.0, 19.9.0, 18.17.0
1215
- */
1216
- type?: "suite";
1217
- };
1218
- /**
1219
- * The test name.
1220
- */
1221
- name: string;
1222
- /**
1223
- * The nesting level of the test.
1224
- */
1225
- nesting: number;
1226
- /**
1227
- * The ordinal number of the test.
1228
- */
1229
- testNumber: number;
1230
- /**
1231
- * Present if `context.todo` is called.
1232
- */
1233
- todo?: string | boolean;
1234
- /**
1235
- * Present if `context.skip` is called.
1236
- */
1237
- skip?: string | boolean;
1238
- }
1239
- interface TestPass extends TestLocationInfo {
1240
- /**
1241
- * Additional execution metadata.
1242
- */
1243
- details: {
1244
- /**
1245
- * The duration of the test in milliseconds.
1246
- */
1247
- duration_ms: number;
1248
- /**
1249
- * The type of the test, used to denote whether this is a suite.
1250
- * @since 20.0.0, 19.9.0, 18.17.0
1251
- */
1252
- type?: "suite";
1253
- };
1254
- /**
1255
- * The test name.
1256
- */
1257
- name: string;
1258
- /**
1259
- * The nesting level of the test.
1260
- */
1261
- nesting: number;
1262
- /**
1263
- * The ordinal number of the test.
1264
- */
1265
- testNumber: number;
1266
- /**
1267
- * Present if `context.todo` is called.
1268
- */
1269
- todo?: string | boolean;
1270
- /**
1271
- * Present if `context.skip` is called.
1272
- */
1273
- skip?: string | boolean;
1274
- }
1275
- interface TestPlan extends TestLocationInfo {
1276
- /**
1277
- * The nesting level of the test.
1278
- */
1279
- nesting: number;
1280
- /**
1281
- * The number of subtests that have ran.
1282
- */
1283
- count: number;
1284
- }
1285
- interface TestStart extends TestLocationInfo {
1286
- /**
1287
- * The test name.
1288
- */
1289
- name: string;
1290
- /**
1291
- * The nesting level of the test.
1292
- */
1293
- nesting: number;
1294
- }
1295
- interface TestStderr extends TestLocationInfo {
1296
- /**
1297
- * The message written to `stderr`
1298
- */
1299
- message: string;
1300
- }
1301
- interface TestStdout extends TestLocationInfo {
1302
- /**
1303
- * The message written to `stdout`
1304
- */
1305
- message: string;
1306
- }
1307
- interface TestEnqueue extends TestLocationInfo {
1308
- /**
1309
- * The test name
1310
- */
1311
- name: string;
1312
- /**
1313
- * The nesting level of the test.
1314
- */
1315
- nesting: number;
1316
- }
1317
- interface TestDequeue extends TestLocationInfo {
1318
- /**
1319
- * The test name
1320
- */
1321
- name: string;
1322
- /**
1323
- * The nesting level of the test.
1324
- */
1325
- nesting: number;
2264
+ type FunctionPropertyNames<T> = {
2265
+ [K in keyof T]: T[K] extends Function ? K : never;
2266
+ }[keyof T];
2267
+ export = test;
1326
2268
  }
1327
2269
 
1328
2270
  /**
@@ -1337,46 +2279,71 @@ interface TestDequeue extends TestLocationInfo {
1337
2279
  * work:
1338
2280
  *
1339
2281
  * ```js
1340
- * import test from 'test/reporters';
2282
+ * import test from 'node:test/reporters';
1341
2283
  * ```
1342
2284
  * @since v19.9.0
1343
- * @see [source](https://github.com/nodejs/node/blob/v20.2.0/lib/test/reporters.js)
2285
+ * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/test/reporters.js)
1344
2286
  */
1345
2287
  declare module "node:test/reporters" {
1346
- import { Transform } from "node:stream";
2288
+ import { Transform, TransformOptions } from "node:stream";
2289
+ import { EventData } from "node:test";
1347
2290
 
1348
2291
  type TestEvent =
1349
- | { type: "test:diagnostic"; data: DiagnosticData }
1350
- | { type: "test:fail"; data: TestFail }
1351
- | { type: "test:pass"; data: TestPass }
1352
- | { type: "test:plan"; data: TestPlan }
1353
- | { type: "test:start"; data: TestStart }
1354
- | { type: "test:stderr"; data: TestStderr }
1355
- | { type: "test:stdout"; data: TestStdout }
1356
- | { type: "test:enqueue"; data: TestEnqueue }
1357
- | { type: "test:dequeue"; data: TestDequeue }
1358
- | { type: "test:watch:drained" };
2292
+ | { type: "test:coverage"; data: EventData.TestCoverage }
2293
+ | { type: "test:complete"; data: EventData.TestComplete }
2294
+ | { type: "test:dequeue"; data: EventData.TestDequeue }
2295
+ | { type: "test:diagnostic"; data: EventData.TestDiagnostic }
2296
+ | { type: "test:enqueue"; data: EventData.TestEnqueue }
2297
+ | { type: "test:fail"; data: EventData.TestFail }
2298
+ | { type: "test:pass"; data: EventData.TestPass }
2299
+ | { type: "test:plan"; data: EventData.TestPlan }
2300
+ | { type: "test:start"; data: EventData.TestStart }
2301
+ | { type: "test:stderr"; data: EventData.TestStderr }
2302
+ | { type: "test:stdout"; data: EventData.TestStdout }
2303
+ | { type: "test:summary"; data: EventData.TestSummary }
2304
+ | { type: "test:watch:drained"; data: undefined }
2305
+ | { type: "test:watch:restarted"; data: undefined };
1359
2306
  type TestEventGenerator = AsyncGenerator<TestEvent, void>;
1360
2307
 
2308
+ interface ReporterConstructorWrapper<T extends new(...args: any[]) => Transform> {
2309
+ new(...args: ConstructorParameters<T>): InstanceType<T>;
2310
+ (...args: ConstructorParameters<T>): InstanceType<T>;
2311
+ }
2312
+
1361
2313
  /**
1362
2314
  * The `dot` reporter outputs the test results in a compact format,
1363
2315
  * where each passing test is represented by a `.`,
1364
2316
  * and each failing test is represented by a `X`.
2317
+ * @since v20.0.0
1365
2318
  */
1366
2319
  function dot(source: TestEventGenerator): AsyncGenerator<"\n" | "." | "X", void>;
1367
2320
  /**
1368
2321
  * The `tap` reporter outputs the test results in the [TAP](https://testanything.org/) format.
2322
+ * @since v20.0.0
1369
2323
  */
1370
2324
  function tap(source: TestEventGenerator): AsyncGenerator<string, void>;
2325
+ class SpecReporter extends Transform {
2326
+ constructor();
2327
+ }
1371
2328
  /**
1372
2329
  * The `spec` reporter outputs the test results in a human-readable format.
2330
+ * @since v20.0.0
1373
2331
  */
1374
- class Spec extends Transform {
1375
- constructor();
1376
- }
2332
+ const spec: ReporterConstructorWrapper<typeof SpecReporter>;
1377
2333
  /**
1378
- * The `junit` reporter outputs test results in a jUnit XML format
2334
+ * The `junit` reporter outputs test results in a jUnit XML format.
2335
+ * @since v21.0.0
1379
2336
  */
1380
2337
  function junit(source: TestEventGenerator): AsyncGenerator<string, void>;
1381
- export { dot, junit, Spec as spec, tap, TestEvent };
2338
+ class LcovReporter extends Transform {
2339
+ constructor(opts?: Omit<TransformOptions, "writableObjectMode">);
2340
+ }
2341
+ /**
2342
+ * The `lcov` reporter outputs test coverage when used with the
2343
+ * [`--experimental-test-coverage`](https://nodejs.org/docs/latest-v24.x/api/cli.html#--experimental-test-coverage) flag.
2344
+ * @since v22.0.0
2345
+ */
2346
+ const lcov: ReporterConstructorWrapper<typeof LcovReporter>;
2347
+
2348
+ export { dot, junit, lcov, spec, tap, TestEvent };
1382
2349
  }