@types/node 18.19.113 → 18.19.114

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 (3) hide show
  1. node v18.19/README.md +1 -1
  2. node v18.19/package.json +2 -2
  3. node v18.19/test.d.ts +1021 -1058
node v18.19/test.d.ts CHANGED
@@ -3,13 +3,8 @@
3
3
  * @see [source](https://github.com/nodejs/node/blob/v18.x/lib/test.js)
4
4
  */
5
5
  declare module "node:test" {
6
- /**
7
- * Programmatically start the test runner.
8
- * @since v18.9.0
9
- * @param options Configuration options for running tests.
10
- * @returns A {@link TestsStream} that emits events about the test execution.
11
- */
12
- function run(options?: RunOptions): TestsStream;
6
+ import TestFn = test.TestFn;
7
+ import TestOptions = test.TestOptions;
13
8
  /**
14
9
  * The `test()` function is the value imported from the test module. Each invocation of this
15
10
  * function results in reporting the test to the {@link TestsStream}.
@@ -49,1142 +44,1109 @@ declare module "node:test" {
49
44
  function test(options?: TestOptions, fn?: TestFn): Promise<void>;
50
45
  function test(fn?: TestFn): Promise<void>;
51
46
  namespace test {
52
- export { after, afterEach, before, beforeEach, describe, it, mock, only, run, skip, test, todo };
47
+ export { test };
53
48
  }
54
- /**
55
- * @since v18.6.0
56
- * @param name The name of the suite, which is displayed when reporting suite results.
57
- * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
58
- * @param options Configuration options for the suite
59
- * @param fn The function under suite. Default: A no-op function.
60
- */
61
- function describe(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
62
- function describe(name?: string, fn?: SuiteFn): Promise<void>;
63
- function describe(options?: TestOptions, fn?: SuiteFn): Promise<void>;
64
- function describe(fn?: SuiteFn): Promise<void>;
65
- namespace describe {
49
+ namespace test {
66
50
  /**
67
- * Shorthand for skipping a suite, same as `describe([name], { skip: true }[, fn])`.
51
+ * Programmatically start the test runner.
52
+ * @since v18.9.0
53
+ * @param options Configuration options for running tests.
54
+ * @returns A {@link TestsStream} that emits events about the test execution.
68
55
  */
69
- function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
70
- function skip(name?: string, fn?: SuiteFn): Promise<void>;
71
- function skip(options?: TestOptions, fn?: SuiteFn): Promise<void>;
72
- function skip(fn?: SuiteFn): Promise<void>;
56
+ function run(options?: RunOptions): TestsStream;
73
57
  /**
74
- * Shorthand for marking a suite as `TODO`, same as `describe([name], { todo: true }[, fn])`.
75
- */
76
- function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
77
- function todo(name?: string, fn?: SuiteFn): Promise<void>;
78
- function todo(options?: TestOptions, fn?: SuiteFn): Promise<void>;
79
- function todo(fn?: SuiteFn): Promise<void>;
58
+ * @since v18.6.0
59
+ * @param name The name of the suite, which is displayed when reporting suite results.
60
+ * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
61
+ * @param options Configuration options for the suite
62
+ * @param fn The function under suite. Default: A no-op function.
63
+ */
64
+ function describe(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
65
+ function describe(name?: string, fn?: SuiteFn): Promise<void>;
66
+ function describe(options?: TestOptions, fn?: SuiteFn): Promise<void>;
67
+ function describe(fn?: SuiteFn): Promise<void>;
68
+ namespace describe {
69
+ /**
70
+ * Shorthand for skipping a suite, same as `describe([name], { skip: true }[, fn])`.
71
+ */
72
+ function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
73
+ function skip(name?: string, fn?: SuiteFn): Promise<void>;
74
+ function skip(options?: TestOptions, fn?: SuiteFn): Promise<void>;
75
+ function skip(fn?: SuiteFn): Promise<void>;
76
+ /**
77
+ * Shorthand for marking a suite as `TODO`, same as `describe([name], { todo: true }[, fn])`.
78
+ */
79
+ function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
80
+ function todo(name?: string, fn?: SuiteFn): Promise<void>;
81
+ function todo(options?: TestOptions, fn?: SuiteFn): Promise<void>;
82
+ function todo(fn?: SuiteFn): Promise<void>;
83
+ /**
84
+ * Shorthand for marking a suite as `only`, same as `describe([name], { only: true }[, fn])`.
85
+ * @since v18.15.0
86
+ */
87
+ function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
88
+ function only(name?: string, fn?: SuiteFn): Promise<void>;
89
+ function only(options?: TestOptions, fn?: SuiteFn): Promise<void>;
90
+ function only(fn?: SuiteFn): Promise<void>;
91
+ }
80
92
  /**
81
- * Shorthand for marking a suite as `only`, same as `describe([name], { only: true }[, fn])`.
82
- * @since v18.15.0
93
+ * @since v18.6.0
94
+ * @param name The name of the test, which is displayed when reporting test results.
95
+ * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
96
+ * @param options Configuration options for the test
97
+ * @param fn The function under test. If the test uses callbacks, the callback function is
98
+ * passed as the second argument. Default: A no-op function.
83
99
  */
84
- function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;
85
- function only(name?: string, fn?: SuiteFn): Promise<void>;
86
- function only(options?: TestOptions, fn?: SuiteFn): Promise<void>;
87
- function only(fn?: SuiteFn): Promise<void>;
88
- }
89
-
90
- /**
91
- * @since v18.6.0
92
- * @param name The name of the test, which is displayed when reporting test results.
93
- * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
94
- * @param options Configuration options for the test
95
- * @param fn The function under test. If the test uses callbacks, the callback function is
96
- * passed as the second argument. Default: A no-op function.
97
- */
98
- function it(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
99
- function it(name?: string, fn?: TestFn): Promise<void>;
100
- function it(options?: TestOptions, fn?: TestFn): Promise<void>;
101
- function it(fn?: TestFn): Promise<void>;
102
- namespace it {
100
+ function it(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
101
+ function it(name?: string, fn?: TestFn): Promise<void>;
102
+ function it(options?: TestOptions, fn?: TestFn): Promise<void>;
103
+ function it(fn?: TestFn): Promise<void>;
104
+ namespace it {
105
+ /**
106
+ * Shorthand for skipping a test, same as `it([name], { skip: true }[, fn])`.
107
+ */
108
+ function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
109
+ function skip(name?: string, fn?: TestFn): Promise<void>;
110
+ function skip(options?: TestOptions, fn?: TestFn): Promise<void>;
111
+ function skip(fn?: TestFn): Promise<void>;
112
+ /**
113
+ * Shorthand for marking a test as `TODO`, same as `it([name], { todo: true }[, fn])`.
114
+ */
115
+ function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
116
+ function todo(name?: string, fn?: TestFn): Promise<void>;
117
+ function todo(options?: TestOptions, fn?: TestFn): Promise<void>;
118
+ function todo(fn?: TestFn): Promise<void>;
119
+ /**
120
+ * Shorthand for marking a test as `only`, same as `it([name], { only: true }[, fn])`.
121
+ * @since v18.15.0
122
+ */
123
+ function only(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
124
+ function only(name?: string, fn?: TestFn): Promise<void>;
125
+ function only(options?: TestOptions, fn?: TestFn): Promise<void>;
126
+ function only(fn?: TestFn): Promise<void>;
127
+ }
103
128
  /**
104
- * Shorthand for skipping a test, same as `it([name], { skip: true }[, fn])`.
129
+ * Shorthand for skipping a test, same as `test([name], { skip: true }[, fn])`.
130
+ * @since v18.17.0
105
131
  */
106
132
  function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
107
133
  function skip(name?: string, fn?: TestFn): Promise<void>;
108
134
  function skip(options?: TestOptions, fn?: TestFn): Promise<void>;
109
135
  function skip(fn?: TestFn): Promise<void>;
110
136
  /**
111
- * Shorthand for marking a test as `TODO`, same as `it([name], { todo: true }[, fn])`.
137
+ * Shorthand for marking a test as `TODO`, same as `test([name], { todo: true }[, fn])`.
138
+ * @since v18.17.0
112
139
  */
113
140
  function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
114
141
  function todo(name?: string, fn?: TestFn): Promise<void>;
115
142
  function todo(options?: TestOptions, fn?: TestFn): Promise<void>;
116
143
  function todo(fn?: TestFn): Promise<void>;
117
144
  /**
118
- * Shorthand for marking a test as `only`, same as `it([name], { only: true }[, fn])`.
119
- * @since v18.15.0
145
+ * Shorthand for marking a test as `only`, same as `test([name], { only: true }[, fn])`.
146
+ * @since v18.17.0
120
147
  */
121
148
  function only(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
122
149
  function only(name?: string, fn?: TestFn): Promise<void>;
123
150
  function only(options?: TestOptions, fn?: TestFn): Promise<void>;
124
151
  function only(fn?: TestFn): Promise<void>;
125
- }
126
- /**
127
- * Shorthand for skipping a test, same as `test([name], { skip: true }[, fn])`.
128
- * @since v18.17.0
129
- */
130
- function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
131
- function skip(name?: string, fn?: TestFn): Promise<void>;
132
- function skip(options?: TestOptions, fn?: TestFn): Promise<void>;
133
- function skip(fn?: TestFn): Promise<void>;
134
- /**
135
- * Shorthand for marking a test as `TODO`, same as `test([name], { todo: true }[, fn])`.
136
- * @since v18.17.0
137
- */
138
- function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
139
- function todo(name?: string, fn?: TestFn): Promise<void>;
140
- function todo(options?: TestOptions, fn?: TestFn): Promise<void>;
141
- function todo(fn?: TestFn): Promise<void>;
142
- /**
143
- * Shorthand for marking a test as `only`, same as `test([name], { only: true }[, fn])`.
144
- * @since v18.17.0
145
- */
146
- function only(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
147
- function only(name?: string, fn?: TestFn): Promise<void>;
148
- function only(options?: TestOptions, fn?: TestFn): Promise<void>;
149
- function only(fn?: TestFn): Promise<void>;
150
- /**
151
- * The type of a function under test. The first argument to this function is a
152
- * {@link TestContext} object. If the test uses callbacks, the callback function is passed as
153
- * the second argument.
154
- */
155
- type TestFn = (t: TestContext, done: (result?: any) => void) => any;
156
- /**
157
- * The type of a function under Suite.
158
- */
159
- type SuiteFn = (s: SuiteContext) => void | Promise<void>;
160
- interface TestShard {
161
- /**
162
- * A positive integer between 1 and `<total>` that specifies the index of the shard to run.
163
- */
164
- index: number;
165
- /**
166
- * A positive integer that specifies the total number of shards to split the test files to.
167
- */
168
- total: number;
169
- }
170
- interface RunOptions {
171
- /**
172
- * If a number is provided, then that many files would run in parallel.
173
- * If truthy, it would run (number of cpu cores - 1) files in parallel.
174
- * If falsy, it would only run one file at a time.
175
- * If unspecified, subtests inherit this value from their parent.
176
- * @default true
177
- */
178
- concurrency?: number | boolean | undefined;
179
- /**
180
- * An array containing the list of files to run.
181
- * If unspecified, the test runner execution model will be used.
182
- */
183
- files?: readonly string[] | undefined;
184
- /**
185
- * Allows aborting an in-progress test execution.
186
- * @default undefined
187
- */
188
- signal?: AbortSignal | undefined;
189
152
  /**
190
- * A number of milliseconds the test will fail after.
191
- * If unspecified, subtests inherit this value from their parent.
192
- * @default Infinity
153
+ * The type of a function under test. The first argument to this function is a
154
+ * {@link TestContext} object. If the test uses callbacks, the callback function is passed as
155
+ * the second argument.
193
156
  */
194
- timeout?: number | undefined;
157
+ type TestFn = (t: TestContext, done: (result?: any) => void) => any;
195
158
  /**
196
- * Sets inspector port of test child process.
197
- * If a nullish value is provided, each process gets its own port,
198
- * incremented from the primary's `process.debugPort`.
159
+ * The type of a function under Suite.
199
160
  */
200
- inspectPort?: number | (() => number) | undefined;
201
- /**
202
- * That can be used to only run tests whose name matches the provided pattern.
203
- * Test name patterns are interpreted as JavaScript regular expressions.
204
- * For each test that is executed, any corresponding test hooks, such as `beforeEach()`, are also run.
205
- */
206
- testNamePatterns?: string | RegExp | ReadonlyArray<string | RegExp> | undefined;
207
- /**
208
- * If truthy, the test context will only run tests that have the `only` option set
209
- * @since v18.19.0
210
- */
211
- only?: boolean | undefined;
212
- /**
213
- * A function that accepts the TestsStream instance and can be used to setup listeners before any tests are run.
214
- */
215
- setup?: ((reporter: TestsStream) => void | Promise<void>) | undefined;
216
- /**
217
- * Whether to run in watch mode or not.
218
- * @default false
161
+ type SuiteFn = (s: SuiteContext) => void | Promise<void>;
162
+ interface TestShard {
163
+ /**
164
+ * A positive integer between 1 and `<total>` that specifies the index of the shard to run.
165
+ */
166
+ index: number;
167
+ /**
168
+ * A positive integer that specifies the total number of shards to split the test files to.
169
+ */
170
+ total: number;
171
+ }
172
+ interface RunOptions {
173
+ /**
174
+ * If a number is provided, then that many files would run in parallel.
175
+ * If truthy, it would run (number of cpu cores - 1) files in parallel.
176
+ * If falsy, it would only run one file at a time.
177
+ * If unspecified, subtests inherit this value from their parent.
178
+ * @default true
179
+ */
180
+ concurrency?: number | boolean | undefined;
181
+ /**
182
+ * An array containing the list of files to run.
183
+ * If unspecified, the test runner execution model will be used.
184
+ */
185
+ files?: readonly string[] | undefined;
186
+ /**
187
+ * Allows aborting an in-progress test execution.
188
+ * @default undefined
189
+ */
190
+ signal?: AbortSignal | undefined;
191
+ /**
192
+ * A number of milliseconds the test will fail after.
193
+ * If unspecified, subtests inherit this value from their parent.
194
+ * @default Infinity
195
+ */
196
+ timeout?: number | undefined;
197
+ /**
198
+ * Sets inspector port of test child process.
199
+ * If a nullish value is provided, each process gets its own port,
200
+ * incremented from the primary's `process.debugPort`.
201
+ */
202
+ inspectPort?: number | (() => number) | undefined;
203
+ /**
204
+ * That can be used to only run tests whose name matches the provided pattern.
205
+ * Test name patterns are interpreted as JavaScript regular expressions.
206
+ * For each test that is executed, any corresponding test hooks, such as `beforeEach()`, are also run.
207
+ */
208
+ testNamePatterns?: string | RegExp | ReadonlyArray<string | RegExp> | undefined;
209
+ /**
210
+ * If truthy, the test context will only run tests that have the `only` option set
211
+ * @since v18.19.0
212
+ */
213
+ only?: boolean | undefined;
214
+ /**
215
+ * A function that accepts the TestsStream instance and can be used to setup listeners before any tests are run.
216
+ */
217
+ setup?: ((reporter: TestsStream) => void | Promise<void>) | undefined;
218
+ /**
219
+ * Whether to run in watch mode or not.
220
+ * @default false
221
+ */
222
+ watch?: boolean | undefined;
223
+ /**
224
+ * Running tests in a specific shard.
225
+ * @since v18.19.0
226
+ * @default undefined
227
+ */
228
+ shard?: TestShard | undefined;
229
+ }
230
+ /**
231
+ * A successful call of the `run()` method will return a new `TestsStream` object,
232
+ * streaming a series of events representing the execution of the tests.
233
+ * `TestsStream` will emit events in the order of the tests' definitions.
234
+ * @since v18.9.0
235
+ */
236
+ interface TestsStream extends NodeJS.ReadableStream {
237
+ addListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
238
+ addListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
239
+ addListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
240
+ addListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
241
+ addListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
242
+ addListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
243
+ addListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
244
+ addListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;
245
+ addListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
246
+ addListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
247
+ addListener(event: "test:watch:drained", listener: () => void): this;
248
+ addListener(event: string, listener: (...args: any[]) => void): this;
249
+ emit(event: "test:coverage", data: EventData.TestCoverage): boolean;
250
+ emit(event: "test:dequeue", data: EventData.TestDequeue): boolean;
251
+ emit(event: "test:diagnostic", data: EventData.TestDiagnostic): boolean;
252
+ emit(event: "test:enqueue", data: EventData.TestEnqueue): boolean;
253
+ emit(event: "test:fail", data: EventData.TestFail): boolean;
254
+ emit(event: "test:pass", data: EventData.TestPass): boolean;
255
+ emit(event: "test:plan", data: EventData.TestPlan): boolean;
256
+ emit(event: "test:start", data: EventData.TestStart): boolean;
257
+ emit(event: "test:stderr", data: EventData.TestStderr): boolean;
258
+ emit(event: "test:stdout", data: EventData.TestStdout): boolean;
259
+ emit(event: "test:watch:drained"): boolean;
260
+ emit(event: string | symbol, ...args: any[]): boolean;
261
+ on(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
262
+ on(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
263
+ on(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
264
+ on(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
265
+ on(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
266
+ on(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
267
+ on(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
268
+ on(event: "test:start", listener: (data: EventData.TestStart) => void): this;
269
+ on(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
270
+ on(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
271
+ on(event: "test:watch:drained", listener: () => void): this;
272
+ on(event: string, listener: (...args: any[]) => void): this;
273
+ once(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
274
+ once(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
275
+ once(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
276
+ once(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
277
+ once(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
278
+ once(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
279
+ once(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
280
+ once(event: "test:start", listener: (data: EventData.TestStart) => void): this;
281
+ once(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
282
+ once(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
283
+ once(event: "test:watch:drained", listener: () => void): this;
284
+ once(event: string, listener: (...args: any[]) => void): this;
285
+ prependListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
286
+ prependListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
287
+ prependListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
288
+ prependListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
289
+ prependListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
290
+ prependListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
291
+ prependListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
292
+ prependListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;
293
+ prependListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
294
+ prependListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
295
+ prependListener(event: "test:watch:drained", listener: () => void): this;
296
+ prependListener(event: string, listener: (...args: any[]) => void): this;
297
+ prependOnceListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;
298
+ prependOnceListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;
299
+ prependOnceListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;
300
+ prependOnceListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;
301
+ prependOnceListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;
302
+ prependOnceListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;
303
+ prependOnceListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;
304
+ prependOnceListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;
305
+ prependOnceListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;
306
+ prependOnceListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;
307
+ prependOnceListener(event: "test:watch:drained", listener: () => void): this;
308
+ prependOnceListener(event: string, listener: (...args: any[]) => void): this;
309
+ }
310
+ namespace EventData {
311
+ interface Error extends globalThis.Error {
312
+ cause: globalThis.Error;
313
+ }
314
+ interface LocationInfo {
315
+ /**
316
+ * The column number where the test is defined, or
317
+ * `undefined` if the test was run through the REPL.
318
+ */
319
+ column?: number;
320
+ /**
321
+ * The path of the test file, `undefined` if test is not ran through a file.
322
+ */
323
+ file?: string;
324
+ /**
325
+ * The line number where the test is defined, or
326
+ * `undefined` if the test was run through the REPL.
327
+ */
328
+ line?: number;
329
+ }
330
+ interface TestDiagnostic extends LocationInfo {
331
+ /**
332
+ * The diagnostic message.
333
+ */
334
+ message: string;
335
+ /**
336
+ * The nesting level of the test.
337
+ */
338
+ nesting: number;
339
+ }
340
+ interface TestCoverage {
341
+ /**
342
+ * An object containing the coverage report.
343
+ */
344
+ summary: {
345
+ /**
346
+ * An array of coverage reports for individual files.
347
+ */
348
+ files: Array<{
349
+ /**
350
+ * The absolute path of the file.
351
+ */
352
+ path: string;
353
+ /**
354
+ * The total number of lines.
355
+ */
356
+ totalLineCount: number;
357
+ /**
358
+ * The total number of branches.
359
+ */
360
+ totalBranchCount: number;
361
+ /**
362
+ * The total number of functions.
363
+ */
364
+ totalFunctionCount: number;
365
+ /**
366
+ * The number of covered lines.
367
+ */
368
+ coveredLineCount: number;
369
+ /**
370
+ * The number of covered branches.
371
+ */
372
+ coveredBranchCount: number;
373
+ /**
374
+ * The number of covered functions.
375
+ */
376
+ coveredFunctionCount: number;
377
+ /**
378
+ * The percentage of lines covered.
379
+ */
380
+ coveredLinePercent: number;
381
+ /**
382
+ * The percentage of branches covered.
383
+ */
384
+ coveredBranchPercent: number;
385
+ /**
386
+ * The percentage of functions covered.
387
+ */
388
+ coveredFunctionPercent: number;
389
+ /**
390
+ * An array of integers representing line numbers that are uncovered.
391
+ */
392
+ uncoveredLineNumbers: number[];
393
+ }>;
394
+ /**
395
+ * An object containing a summary of coverage for all files.
396
+ */
397
+ totals: {
398
+ /**
399
+ * The total number of lines.
400
+ */
401
+ totalLineCount: number;
402
+ /**
403
+ * The total number of branches.
404
+ */
405
+ totalBranchCount: number;
406
+ /**
407
+ * The total number of functions.
408
+ */
409
+ totalFunctionCount: number;
410
+ /**
411
+ * The number of covered lines.
412
+ */
413
+ coveredLineCount: number;
414
+ /**
415
+ * The number of covered branches.
416
+ */
417
+ coveredBranchCount: number;
418
+ /**
419
+ * The number of covered functions.
420
+ */
421
+ coveredFunctionCount: number;
422
+ /**
423
+ * The percentage of lines covered.
424
+ */
425
+ coveredLinePercent: number;
426
+ /**
427
+ * The percentage of branches covered.
428
+ */
429
+ coveredBranchPercent: number;
430
+ /**
431
+ * The percentage of functions covered.
432
+ */
433
+ coveredFunctionPercent: number;
434
+ };
435
+ /**
436
+ * The working directory when code coverage began. This
437
+ * is useful for displaying relative path names in case
438
+ * the tests changed the working directory of the Node.js process.
439
+ */
440
+ workingDirectory: string;
441
+ };
442
+ /**
443
+ * The nesting level of the test.
444
+ */
445
+ nesting: number;
446
+ }
447
+ interface TestDequeue extends LocationInfo {
448
+ /**
449
+ * The test name
450
+ */
451
+ name: string;
452
+ /**
453
+ * The nesting level of the test.
454
+ */
455
+ nesting: number;
456
+ }
457
+ interface TestEnqueue extends LocationInfo {
458
+ /**
459
+ * The test name
460
+ */
461
+ name: string;
462
+ /**
463
+ * The nesting level of the test.
464
+ */
465
+ nesting: number;
466
+ }
467
+ interface TestFail extends LocationInfo {
468
+ /**
469
+ * Additional execution metadata.
470
+ */
471
+ details: {
472
+ /**
473
+ * The duration of the test in milliseconds.
474
+ */
475
+ duration_ms: number;
476
+ /**
477
+ * The error thrown by the test.
478
+ */
479
+ error: Error;
480
+ /**
481
+ * The type of the test, used to denote whether this is a suite.
482
+ * @since 18.17.0
483
+ */
484
+ type?: "suite";
485
+ };
486
+ /**
487
+ * The test name.
488
+ */
489
+ name: string;
490
+ /**
491
+ * The nesting level of the test.
492
+ */
493
+ nesting: number;
494
+ /**
495
+ * The ordinal number of the test.
496
+ */
497
+ testNumber: number;
498
+ /**
499
+ * Present if `context.todo` is called.
500
+ */
501
+ todo?: string | boolean;
502
+ /**
503
+ * Present if `context.skip` is called.
504
+ */
505
+ skip?: string | boolean;
506
+ }
507
+ interface TestPass extends LocationInfo {
508
+ /**
509
+ * Additional execution metadata.
510
+ */
511
+ details: {
512
+ /**
513
+ * The duration of the test in milliseconds.
514
+ */
515
+ duration_ms: number;
516
+ /**
517
+ * The type of the test, used to denote whether this is a suite.
518
+ * @since 18.17.0
519
+ */
520
+ type?: "suite";
521
+ };
522
+ /**
523
+ * The test name.
524
+ */
525
+ name: string;
526
+ /**
527
+ * The nesting level of the test.
528
+ */
529
+ nesting: number;
530
+ /**
531
+ * The ordinal number of the test.
532
+ */
533
+ testNumber: number;
534
+ /**
535
+ * Present if `context.todo` is called.
536
+ */
537
+ todo?: string | boolean;
538
+ /**
539
+ * Present if `context.skip` is called.
540
+ */
541
+ skip?: string | boolean;
542
+ }
543
+ interface TestPlan extends LocationInfo {
544
+ /**
545
+ * The nesting level of the test.
546
+ */
547
+ nesting: number;
548
+ /**
549
+ * The number of subtests that have ran.
550
+ */
551
+ count: number;
552
+ }
553
+ interface TestStart extends LocationInfo {
554
+ /**
555
+ * The test name.
556
+ */
557
+ name: string;
558
+ /**
559
+ * The nesting level of the test.
560
+ */
561
+ nesting: number;
562
+ }
563
+ interface TestStderr extends LocationInfo {
564
+ /**
565
+ * The message written to `stderr`
566
+ */
567
+ message: string;
568
+ }
569
+ interface TestStdout extends LocationInfo {
570
+ /**
571
+ * The message written to `stdout`
572
+ */
573
+ message: string;
574
+ }
575
+ }
576
+ /**
577
+ * An instance of `TestContext` is passed to each test function in order to interact with the
578
+ * test runner. However, the `TestContext` constructor is not exposed as part of the API.
579
+ * @since v18.0.0
219
580
  */
220
- watch?: boolean | undefined;
581
+ interface TestContext {
582
+ /**
583
+ * This function is used to create a hook running before subtest of the current test.
584
+ * @param fn The hook function. The first argument to this function is a `TestContext` object.
585
+ * If the hook uses callbacks, the callback function is passed as the second argument.
586
+ * @param options Configuration options for the hook.
587
+ * @since v18.17.0
588
+ */
589
+ before(fn?: TestContextHookFn, options?: HookOptions): void;
590
+ /**
591
+ * This function is used to create a hook running before each subtest of the current test.
592
+ * @param fn The hook function. The first argument to this function is a `TestContext` object.
593
+ * If the hook uses callbacks, the callback function is passed as the second argument.
594
+ * @param options Configuration options for the hook.
595
+ * @since v18.8.0
596
+ */
597
+ beforeEach(fn?: TestContextHookFn, options?: HookOptions): void;
598
+ /**
599
+ * This function is used to create a hook that runs after the current test finishes.
600
+ * @param fn The hook function. The first argument to this function is a `TestContext` object.
601
+ * If the hook uses callbacks, the callback function is passed as the second argument.
602
+ * @param options Configuration options for the hook.
603
+ * @since v18.13.0
604
+ */
605
+ after(fn?: TestContextHookFn, options?: HookOptions): void;
606
+ /**
607
+ * This function is used to create a hook running after each subtest of the current test.
608
+ * @param fn The hook function. The first argument to this function is a `TestContext` object.
609
+ * If the hook uses callbacks, the callback function is passed as the second argument.
610
+ * @param options Configuration options for the hook.
611
+ * @since v18.8.0
612
+ */
613
+ afterEach(fn?: TestContextHookFn, options?: HookOptions): void;
614
+ /**
615
+ * This function is used to write diagnostics to the output. Any diagnostic information is
616
+ * included at the end of the test's results. This function does not return a value.
617
+ * @param message Message to be reported.
618
+ * @since v18.0.0
619
+ */
620
+ diagnostic(message: string): void;
621
+ /**
622
+ * The name of the test.
623
+ * @since v18.8.0
624
+ */
625
+ readonly name: string;
626
+ /**
627
+ * If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only`
628
+ * option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only`
629
+ * command-line option, this function is a no-op.
630
+ * @param shouldRunOnlyTests Whether or not to run `only` tests.
631
+ * @since v18.0.0
632
+ */
633
+ runOnly(shouldRunOnlyTests: boolean): void;
634
+ /**
635
+ * Can be used to abort test subtasks when the test has been aborted.
636
+ * @since v18.7.0
637
+ */
638
+ readonly signal: AbortSignal;
639
+ /**
640
+ * This function causes the test's output to indicate the test as skipped. If `message` is
641
+ * provided, it is included in the output. Calling `skip()` does not terminate execution of
642
+ * the test function. This function does not return a value.
643
+ * @param message Optional skip message.
644
+ * @since v18.0.0
645
+ */
646
+ skip(message?: string): void;
647
+ /**
648
+ * This function adds a `TODO` directive to the test's output. If `message` is provided, it is
649
+ * included in the output. Calling `todo()` does not terminate execution of the test
650
+ * function. This function does not return a value.
651
+ * @param message Optional `TODO` message.
652
+ * @since v18.0.0
653
+ */
654
+ todo(message?: string): void;
655
+ /**
656
+ * This function is used to create subtests under the current test. This function behaves in
657
+ * the same fashion as the top level {@link test} function.
658
+ * @since v18.0.0
659
+ * @param name The name of the test, which is displayed when reporting test results.
660
+ * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
661
+ * @param options Configuration options for the test
662
+ * @param fn The function under test. This first argument to this function is a
663
+ * {@link TestContext} object. If the test uses callbacks, the callback function is
664
+ * passed as the second argument. Default: A no-op function.
665
+ * @returns A {@link Promise} resolved with `undefined` once the test completes.
666
+ */
667
+ test: typeof test;
668
+ /**
669
+ * Each test provides its own MockTracker instance.
670
+ */
671
+ readonly mock: MockTracker;
672
+ }
221
673
  /**
222
- * Running tests in a specific shard.
223
- * @since v18.19.0
224
- * @default undefined
674
+ * An instance of `SuiteContext` is passed to each suite function in order to
675
+ * interact with the test runner. However, the `SuiteContext` constructor is not
676
+ * exposed as part of the API.
677
+ * @since v18.7.0, v16.17.0
225
678
  */
226
- shard?: TestShard | undefined;
227
- }
228
-
229
- /**
230
- * A successful call of the `run()` method will return a new `TestsStream` object,
231
- * streaming a series of events representing the execution of the tests.
232
- * `TestsStream` will emit events in the order of the tests' definitions.
233
- * @since v18.9.0
234
- */
235
- interface TestsStream extends NodeJS.ReadableStream {
236
- addListener(event: "test:coverage", listener: (data: TestCoverage) => void): this;
237
- addListener(event: "test:dequeue", listener: (data: TestDequeue) => void): this;
238
- addListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
239
- addListener(event: "test:enqueue", listener: (data: TestEnqueue) => void): this;
240
- addListener(event: "test:fail", listener: (data: TestFail) => void): this;
241
- addListener(event: "test:pass", listener: (data: TestPass) => void): this;
242
- addListener(event: "test:plan", listener: (data: TestPlan) => void): this;
243
- addListener(event: "test:start", listener: (data: TestStart) => void): this;
244
- addListener(event: "test:stderr", listener: (data: TestStderr) => void): this;
245
- addListener(event: "test:stdout", listener: (data: TestStdout) => void): this;
246
- addListener(event: "test:watch:drained", listener: () => void): this;
247
- addListener(event: string, listener: (...args: any[]) => void): this;
248
- emit(event: "test:coverage", data: TestCoverage): boolean;
249
- emit(event: "test:dequeue", data: TestDequeue): boolean;
250
- emit(event: "test:diagnostic", data: DiagnosticData): boolean;
251
- emit(event: "test:enqueue", data: TestEnqueue): boolean;
252
- emit(event: "test:fail", data: TestFail): boolean;
253
- emit(event: "test:pass", data: TestPass): boolean;
254
- emit(event: "test:plan", data: TestPlan): boolean;
255
- emit(event: "test:start", data: TestStart): boolean;
256
- emit(event: "test:stderr", data: TestStderr): boolean;
257
- emit(event: "test:stdout", data: TestStdout): boolean;
258
- emit(event: "test:watch:drained"): boolean;
259
- emit(event: string | symbol, ...args: any[]): boolean;
260
- on(event: "test:coverage", listener: (data: TestCoverage) => void): this;
261
- on(event: "test:dequeue", listener: (data: TestDequeue) => void): this;
262
- on(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
263
- on(event: "test:enqueue", listener: (data: TestEnqueue) => void): this;
264
- on(event: "test:fail", listener: (data: TestFail) => void): this;
265
- on(event: "test:pass", listener: (data: TestPass) => void): this;
266
- on(event: "test:plan", listener: (data: TestPlan) => void): this;
267
- on(event: "test:start", listener: (data: TestStart) => void): this;
268
- on(event: "test:stderr", listener: (data: TestStderr) => void): this;
269
- on(event: "test:stdout", listener: (data: TestStdout) => void): this;
270
- on(event: "test:watch:drained", listener: () => void): this;
271
- on(event: string, listener: (...args: any[]) => void): this;
272
- once(event: "test:coverage", listener: (data: TestCoverage) => void): this;
273
- once(event: "test:dequeue", listener: (data: TestDequeue) => void): this;
274
- once(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
275
- once(event: "test:enqueue", listener: (data: TestEnqueue) => void): this;
276
- once(event: "test:fail", listener: (data: TestFail) => void): this;
277
- once(event: "test:pass", listener: (data: TestPass) => void): this;
278
- once(event: "test:plan", listener: (data: TestPlan) => void): this;
279
- once(event: "test:start", listener: (data: TestStart) => void): this;
280
- once(event: "test:stderr", listener: (data: TestStderr) => void): this;
281
- once(event: "test:stdout", listener: (data: TestStdout) => void): this;
282
- once(event: "test:watch:drained", listener: () => void): this;
283
- once(event: string, listener: (...args: any[]) => void): this;
284
- prependListener(event: "test:coverage", listener: (data: TestCoverage) => void): this;
285
- prependListener(event: "test:dequeue", listener: (data: TestDequeue) => void): this;
286
- prependListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
287
- prependListener(event: "test:enqueue", listener: (data: TestEnqueue) => void): this;
288
- prependListener(event: "test:fail", listener: (data: TestFail) => void): this;
289
- prependListener(event: "test:pass", listener: (data: TestPass) => void): this;
290
- prependListener(event: "test:plan", listener: (data: TestPlan) => void): this;
291
- prependListener(event: "test:start", listener: (data: TestStart) => void): this;
292
- prependListener(event: "test:stderr", listener: (data: TestStderr) => void): this;
293
- prependListener(event: "test:stdout", listener: (data: TestStdout) => void): this;
294
- prependListener(event: "test:watch:drained", listener: () => void): this;
295
- prependListener(event: string, listener: (...args: any[]) => void): this;
296
- prependOnceListener(event: "test:coverage", listener: (data: TestCoverage) => void): this;
297
- prependOnceListener(event: "test:dequeue", listener: (data: TestDequeue) => void): this;
298
- prependOnceListener(event: "test:diagnostic", listener: (data: DiagnosticData) => void): this;
299
- prependOnceListener(event: "test:enqueue", listener: (data: TestEnqueue) => void): this;
300
- prependOnceListener(event: "test:fail", listener: (data: TestFail) => void): this;
301
- prependOnceListener(event: "test:pass", listener: (data: TestPass) => void): this;
302
- prependOnceListener(event: "test:plan", listener: (data: TestPlan) => void): this;
303
- prependOnceListener(event: "test:start", listener: (data: TestStart) => void): this;
304
- prependOnceListener(event: "test:stderr", listener: (data: TestStderr) => void): this;
305
- prependOnceListener(event: "test:stdout", listener: (data: TestStdout) => void): this;
306
- prependOnceListener(event: "test:watch:drained", listener: () => void): this;
307
- prependOnceListener(event: string, listener: (...args: any[]) => void): this;
308
- }
309
-
310
- /**
311
- * An instance of `TestContext` is passed to each test function in order to interact with the
312
- * test runner. However, the `TestContext` constructor is not exposed as part of the API.
313
- * @since v18.0.0
314
- */
315
- export interface TestContext {
679
+ interface SuiteContext {
680
+ /**
681
+ * The name of the suite.
682
+ * @since v18.8.0, v16.18.0
683
+ */
684
+ readonly name: string;
685
+ /**
686
+ * Can be used to abort test subtasks when the test has been aborted.
687
+ * @since v18.7.0, v16.17.0
688
+ */
689
+ readonly signal: AbortSignal;
690
+ }
691
+ interface TestOptions {
692
+ /**
693
+ * If a number is provided, then that many tests would run in parallel.
694
+ * If truthy, it would run (number of cpu cores - 1) tests in parallel.
695
+ * For subtests, it will be `Infinity` tests in parallel.
696
+ * If falsy, it would only run one test at a time.
697
+ * If unspecified, subtests inherit this value from their parent.
698
+ * @default false
699
+ */
700
+ concurrency?: number | boolean | undefined;
701
+ /**
702
+ * If truthy, and the test context is configured to run `only` tests, then this test will be
703
+ * run. Otherwise, the test is skipped.
704
+ * @default false
705
+ */
706
+ only?: boolean | undefined;
707
+ /**
708
+ * Allows aborting an in-progress test.
709
+ * @since v18.8.0
710
+ */
711
+ signal?: AbortSignal | undefined;
712
+ /**
713
+ * If truthy, the test is skipped. If a string is provided, that string is displayed in the
714
+ * test results as the reason for skipping the test.
715
+ * @default false
716
+ */
717
+ skip?: boolean | string | undefined;
718
+ /**
719
+ * A number of milliseconds the test will fail after. If unspecified, subtests inherit this
720
+ * value from their parent.
721
+ * @default Infinity
722
+ * @since v18.7.0
723
+ */
724
+ timeout?: number | undefined;
725
+ /**
726
+ * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in
727
+ * the test results as the reason why the test is `TODO`.
728
+ * @default false
729
+ */
730
+ todo?: boolean | string | undefined;
731
+ }
316
732
  /**
317
- * This function is used to create a hook running before subtest of the current test.
318
- * @param fn The hook function. The first argument to this function is a `TestContext` object.
319
- * If the hook uses callbacks, the callback function is passed as the second argument.
733
+ * This function is used to create a hook running before running a suite.
734
+ * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
735
+ * the second argument. Default: A no-op function.
320
736
  * @param options Configuration options for the hook.
321
- * @since v18.17.0
737
+ * @since v18.8.0
322
738
  */
323
- before(fn?: TestContextHookFn, options?: HookOptions): void;
324
-
739
+ function before(fn?: HookFn, options?: HookOptions): void;
325
740
  /**
326
- * This function is used to create a hook running before each subtest of the current test.
327
- * @param fn The hook function. The first argument to this function is a `TestContext` object.
328
- * If the hook uses callbacks, the callback function is passed as the second argument.
741
+ * This function is used to create a hook running after running a suite.
742
+ * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
743
+ * the second argument. Default: A no-op function.
329
744
  * @param options Configuration options for the hook.
330
745
  * @since v18.8.0
331
746
  */
332
- beforeEach(fn?: TestContextHookFn, options?: HookOptions): void;
333
-
747
+ function after(fn?: HookFn, options?: HookOptions): void;
334
748
  /**
335
- * This function is used to create a hook that runs after the current test finishes.
336
- * @param fn The hook function. The first argument to this function is a `TestContext` object.
337
- * If the hook uses callbacks, the callback function is passed as the second argument.
749
+ * This function is used to create a hook running before each subtest of the current suite.
750
+ * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
751
+ * the second argument. Default: A no-op function.
338
752
  * @param options Configuration options for the hook.
339
- * @since v18.13.0
753
+ * @since v18.8.0
340
754
  */
341
- after(fn?: TestContextHookFn, options?: HookOptions): void;
342
-
755
+ function beforeEach(fn?: HookFn, options?: HookOptions): void;
343
756
  /**
344
757
  * This function is used to create a hook running after each subtest of the current test.
345
- * @param fn The hook function. The first argument to this function is a `TestContext` object.
346
- * If the hook uses callbacks, the callback function is passed as the second argument.
758
+ * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
759
+ * the second argument. Default: A no-op function.
347
760
  * @param options Configuration options for the hook.
348
761
  * @since v18.8.0
349
762
  */
350
- afterEach(fn?: TestContextHookFn, options?: HookOptions): void;
351
-
352
- /**
353
- * This function is used to write diagnostics to the output. Any diagnostic information is
354
- * included at the end of the test's results. This function does not return a value.
355
- * @param message Message to be reported.
356
- * @since v18.0.0
357
- */
358
- diagnostic(message: string): void;
359
-
360
- /**
361
- * The name of the test.
362
- * @since v18.8.0
363
- */
364
- readonly name: string;
365
-
366
- /**
367
- * If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only`
368
- * option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only`
369
- * command-line option, this function is a no-op.
370
- * @param shouldRunOnlyTests Whether or not to run `only` tests.
371
- * @since v18.0.0
372
- */
373
- runOnly(shouldRunOnlyTests: boolean): void;
374
-
375
- /**
376
- * Can be used to abort test subtasks when the test has been aborted.
377
- * @since v18.7.0
378
- */
379
- readonly signal: AbortSignal;
380
-
381
- /**
382
- * This function causes the test's output to indicate the test as skipped. If `message` is
383
- * provided, it is included in the output. Calling `skip()` does not terminate execution of
384
- * the test function. This function does not return a value.
385
- * @param message Optional skip message.
386
- * @since v18.0.0
387
- */
388
- skip(message?: string): void;
389
-
390
- /**
391
- * This function adds a `TODO` directive to the test's output. If `message` is provided, it is
392
- * included in the output. Calling `todo()` does not terminate execution of the test
393
- * function. This function does not return a value.
394
- * @param message Optional `TODO` message.
395
- * @since v18.0.0
396
- */
397
- todo(message?: string): void;
398
-
399
- /**
400
- * This function is used to create subtests under the current test. This function behaves in
401
- * the same fashion as the top level {@link test} function.
402
- * @since v18.0.0
403
- * @param name The name of the test, which is displayed when reporting test results.
404
- * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
405
- * @param options Configuration options for the test
406
- * @param fn The function under test. This first argument to this function is a
407
- * {@link TestContext} object. If the test uses callbacks, the callback function is
408
- * passed as the second argument. Default: A no-op function.
409
- * @returns A {@link Promise} resolved with `undefined` once the test completes.
410
- */
411
- test: typeof test;
763
+ function afterEach(fn?: HookFn, options?: HookOptions): void;
412
764
  /**
413
- * Each test provides its own MockTracker instance.
765
+ * The hook function. The first argument is the context in which the hook is called.
766
+ * If the hook uses callbacks, the callback function is passed as the second argument.
414
767
  */
415
- readonly mock: MockTracker;
416
- }
417
-
418
- /**
419
- * An instance of `SuiteContext` is passed to each suite function in order to
420
- * interact with the test runner. However, the `SuiteContext` constructor is not
421
- * exposed as part of the API.
422
- * @since v18.7.0, v16.17.0
423
- */
424
- export interface SuiteContext {
768
+ type HookFn = (c: TestContext | SuiteContext, done: (result?: any) => void) => any;
425
769
  /**
426
- * The name of the suite.
427
- * @since v18.8.0, v16.18.0
770
+ * The hook function. The first argument is a `TestContext` object.
771
+ * If the hook uses callbacks, the callback function is passed as the second argument.
428
772
  */
429
- readonly name: string;
430
- /**
431
- * Can be used to abort test subtasks when the test has been aborted.
432
- * @since v18.7.0, v16.17.0
433
- */
434
- readonly signal: AbortSignal;
435
- }
436
- interface TestOptions {
773
+ type TestContextHookFn = (t: TestContext, done: (result?: any) => void) => any;
437
774
  /**
438
- * If a number is provided, then that many tests would run in parallel.
439
- * If truthy, it would run (number of cpu cores - 1) tests in parallel.
440
- * For subtests, it will be `Infinity` tests in parallel.
441
- * If falsy, it would only run one test at a time.
442
- * If unspecified, subtests inherit this value from their parent.
443
- * @default false
444
- */
445
- concurrency?: number | boolean | undefined;
446
-
447
- /**
448
- * If truthy, and the test context is configured to run `only` tests, then this test will be
449
- * run. Otherwise, the test is skipped.
450
- * @default false
451
- */
452
- only?: boolean | undefined;
453
-
454
- /**
455
- * Allows aborting an in-progress test.
775
+ * Configuration options for hooks.
456
776
  * @since v18.8.0
457
777
  */
458
- signal?: AbortSignal | undefined;
459
-
460
- /**
461
- * If truthy, the test is skipped. If a string is provided, that string is displayed in the
462
- * test results as the reason for skipping the test.
463
- * @default false
464
- */
465
- skip?: boolean | string | undefined;
466
-
467
- /**
468
- * A number of milliseconds the test will fail after. If unspecified, subtests inherit this
469
- * value from their parent.
470
- * @default Infinity
471
- * @since v18.7.0
472
- */
473
- timeout?: number | undefined;
474
-
475
- /**
476
- * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in
477
- * the test results as the reason why the test is `TODO`.
478
- * @default false
479
- */
480
- todo?: boolean | string | undefined;
481
- }
482
-
483
- /**
484
- * This function is used to create a hook running before running a suite.
485
- * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
486
- * the second argument. Default: A no-op function.
487
- * @param options Configuration options for the hook.
488
- * @since v18.8.0
489
- */
490
- function before(fn?: HookFn, options?: HookOptions): void;
491
-
492
- /**
493
- * This function is used to create a hook running after running a suite.
494
- * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
495
- * the second argument. Default: A no-op function.
496
- * @param options Configuration options for the hook.
497
- * @since v18.8.0
498
- */
499
- function after(fn?: HookFn, options?: HookOptions): void;
500
-
501
- /**
502
- * This function is used to create a hook running before each subtest of the current suite.
503
- * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
504
- * the second argument. Default: A no-op function.
505
- * @param options Configuration options for the hook.
506
- * @since v18.8.0
507
- */
508
- function beforeEach(fn?: HookFn, options?: HookOptions): void;
509
-
510
- /**
511
- * This function is used to create a hook running after each subtest of the current test.
512
- * @param fn The hook function. If the hook uses callbacks, the callback function is passed as
513
- * the second argument. Default: A no-op function.
514
- * @param options Configuration options for the hook.
515
- * @since v18.8.0
516
- */
517
- function afterEach(fn?: HookFn, options?: HookOptions): void;
518
-
519
- /**
520
- * The hook function. The first argument is the context in which the hook is called.
521
- * If the hook uses callbacks, the callback function is passed as the second argument.
522
- */
523
- type HookFn = (c: TestContext | SuiteContext, done: (result?: any) => void) => any;
524
-
525
- /**
526
- * The hook function. The first argument is a `TestContext` object.
527
- * If the hook uses callbacks, the callback function is passed as the second argument.
528
- */
529
- type TestContextHookFn = (t: TestContext, done: (result?: any) => void) => any;
530
-
531
- /**
532
- * Configuration options for hooks.
533
- * @since v18.8.0
534
- */
535
- interface HookOptions {
536
- /**
537
- * Allows aborting an in-progress hook.
538
- */
539
- signal?: AbortSignal | undefined;
540
-
541
- /**
542
- * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this
543
- * value from their parent.
544
- * @default Infinity
545
- */
546
- timeout?: number | undefined;
547
- }
548
-
549
- interface MockFunctionOptions {
550
- /**
551
- * The number of times that the mock will use the behavior of `implementation`.
552
- * Once the mock function has been called `times` times,
553
- * it will automatically restore the behavior of `original`.
554
- * This value must be an integer greater than zero.
555
- * @default Infinity
556
- */
557
- times?: number | undefined;
558
- }
559
-
560
- interface MockMethodOptions extends MockFunctionOptions {
561
- /**
562
- * If `true`, `object[methodName]` is treated as a getter.
563
- * This option cannot be used with the `setter` option.
564
- */
565
- getter?: boolean | undefined;
566
-
567
- /**
568
- * If `true`, `object[methodName]` is treated as a setter.
569
- * This option cannot be used with the `getter` option.
570
- */
571
- setter?: boolean | undefined;
572
- }
573
-
574
- type Mock<F extends Function> = F & {
575
- mock: MockFunctionContext<F>;
576
- };
577
-
578
- type NoOpFunction = (...args: any[]) => undefined;
579
-
580
- type FunctionPropertyNames<T> = {
581
- [K in keyof T]: T[K] extends Function ? K : never;
582
- }[keyof T];
583
-
584
- interface MockTracker {
585
- /**
586
- * This function is used to create a mock function.
587
- * @param original An optional function to create a mock on.
588
- * @param implementation An optional function used as the mock implementation for `original`.
589
- * This is useful for creating mocks that exhibit one behavior for a specified number of calls and then restore the behavior of `original`.
590
- * @param options Optional configuration options for the mock function.
591
- */
592
- fn<F extends Function = NoOpFunction>(original?: F, options?: MockFunctionOptions): Mock<F>;
593
- fn<F extends Function = NoOpFunction, Implementation extends Function = F>(
594
- original?: F,
595
- implementation?: Implementation,
596
- options?: MockFunctionOptions,
597
- ): Mock<F | Implementation>;
598
- /**
599
- * This function is used to create a mock on an existing object method.
600
- * @param object The object whose method is being mocked.
601
- * @param methodName The identifier of the method on `object` to mock. If `object[methodName]` is not a function, an error is thrown.
602
- * @param implementation An optional function used as the mock implementation for `object[methodName]`.
603
- * @param options Optional configuration options for the mock method.
604
- */
605
- method<
606
- MockedObject extends object,
607
- MethodName extends FunctionPropertyNames<MockedObject>,
608
- >(
609
- object: MockedObject,
610
- methodName: MethodName,
611
- options?: MockFunctionOptions,
612
- ): MockedObject[MethodName] extends Function ? Mock<MockedObject[MethodName]>
613
- : never;
614
- method<
615
- MockedObject extends object,
616
- MethodName extends FunctionPropertyNames<MockedObject>,
617
- Implementation extends Function,
618
- >(
619
- object: MockedObject,
620
- methodName: MethodName,
621
- implementation: Implementation,
622
- options?: MockFunctionOptions,
623
- ): MockedObject[MethodName] extends Function ? Mock<MockedObject[MethodName] | Implementation>
624
- : never;
625
- method<MockedObject extends object>(
626
- object: MockedObject,
627
- methodName: keyof MockedObject,
628
- options: MockMethodOptions,
629
- ): Mock<Function>;
630
- method<MockedObject extends object>(
631
- object: MockedObject,
632
- methodName: keyof MockedObject,
633
- implementation: Function,
634
- options: MockMethodOptions,
635
- ): Mock<Function>;
636
- /**
637
- * This function is syntax sugar for {@link MockTracker.method} with `options.getter` set to `true`.
638
- */
639
- getter<
640
- MockedObject extends object,
641
- MethodName extends keyof MockedObject,
642
- >(
643
- object: MockedObject,
644
- methodName: MethodName,
645
- options?: MockFunctionOptions,
646
- ): Mock<() => MockedObject[MethodName]>;
647
- getter<
648
- MockedObject extends object,
649
- MethodName extends keyof MockedObject,
650
- Implementation extends Function,
651
- >(
652
- object: MockedObject,
653
- methodName: MethodName,
654
- implementation?: Implementation,
655
- options?: MockFunctionOptions,
656
- ): Mock<(() => MockedObject[MethodName]) | Implementation>;
657
- /**
658
- * This function is syntax sugar for {@link MockTracker.method} with `options.setter` set to `true`.
659
- */
660
- setter<
661
- MockedObject extends object,
662
- MethodName extends keyof MockedObject,
663
- >(
664
- object: MockedObject,
665
- methodName: MethodName,
666
- options?: MockFunctionOptions,
667
- ): Mock<(value: MockedObject[MethodName]) => void>;
668
- setter<
669
- MockedObject extends object,
670
- MethodName extends keyof MockedObject,
671
- Implementation extends Function,
672
- >(
673
- object: MockedObject,
674
- methodName: MethodName,
675
- implementation?: Implementation,
676
- options?: MockFunctionOptions,
677
- ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>;
678
- /**
679
- * This function restores the default behavior of all mocks that were previously created by this `MockTracker`
680
- * and disassociates the mocks from the `MockTracker` instance. Once disassociated, the mocks can still be used,
681
- * but the `MockTracker` instance can no longer be used to reset their behavior or otherwise interact with them.
682
- *
683
- * After each test completes, this function is called on the test context's `MockTracker`.
684
- * If the global `MockTracker` is used extensively, calling this function manually is recommended.
685
- */
686
- reset(): void;
687
- /**
688
- * This function restores the default behavior of all mocks that were previously created by this `MockTracker`.
689
- * Unlike `mock.reset()`, `mock.restoreAll()` does not disassociate the mocks from the `MockTracker` instance.
690
- */
691
- restoreAll(): void;
692
- timers: MockTimers;
693
- }
694
-
695
- const mock: MockTracker;
696
-
697
- interface MockFunctionCall<
698
- F extends Function,
699
- ReturnType = F extends (...args: any) => infer T ? T
700
- : F extends abstract new(...args: any) => infer T ? T
701
- : unknown,
702
- Args = F extends (...args: infer Y) => any ? Y
703
- : F extends abstract new(...args: infer Y) => any ? Y
704
- : unknown[],
705
- > {
706
- /**
707
- * An array of the arguments passed to the mock function.
708
- */
709
- arguments: Args;
710
- /**
711
- * If the mocked function threw then this property contains the thrown value.
712
- */
713
- error: unknown | undefined;
714
- /**
715
- * The value returned by the mocked function.
716
- *
717
- * If the mocked function threw, it will be `undefined`.
718
- */
719
- result: ReturnType | undefined;
720
- /**
721
- * An `Error` object whose stack can be used to determine the callsite of the mocked function invocation.
722
- */
723
- stack: Error;
724
- /**
725
- * If the mocked function is a constructor, this field contains the class being constructed.
726
- * Otherwise this will be `undefined`.
727
- */
728
- target: F extends abstract new(...args: any) => any ? F : undefined;
729
- /**
730
- * The mocked function's `this` value.
731
- */
732
- this: unknown;
733
- }
734
-
735
- interface MockFunctionContext<F extends Function> {
736
- /**
737
- * A getter that returns a copy of the internal array used to track calls to the mock.
738
- */
739
- readonly calls: Array<MockFunctionCall<F>>;
740
-
741
- /**
742
- * This function returns the number of times that this mock has been invoked.
743
- * This function is more efficient than checking `ctx.calls.length`
744
- * because `ctx.calls` is a getter that creates a copy of the internal call tracking array.
745
- */
746
- callCount(): number;
747
-
748
- /**
749
- * This function is used to change the behavior of an existing mock.
750
- * @param implementation The function to be used as the mock's new implementation.
751
- */
752
- mockImplementation(implementation: F): void;
753
-
754
- /**
755
- * This function is used to change the behavior of an existing mock for a single invocation.
756
- * Once invocation `onCall` has occurred, the mock will revert to whatever behavior
757
- * it would have used had `mockImplementationOnce()` not been called.
758
- * @param implementation The function to be used as the mock's implementation for the invocation number specified by `onCall`.
759
- * @param onCall The invocation number that will use `implementation`.
760
- * If the specified invocation has already occurred then an exception is thrown.
761
- */
762
- mockImplementationOnce(implementation: F, onCall?: number): void;
763
-
764
- /**
765
- * Resets the call history of the mock function.
766
- */
767
- resetCalls(): void;
768
-
769
- /**
770
- * Resets the implementation of the mock function to its original behavior.
771
- * The mock can still be used after calling this function.
772
- */
773
- restore(): void;
774
- }
775
-
776
- type Timer = "setInterval" | "clearInterval" | "setTimeout" | "clearTimeout";
777
- /**
778
- * Mocking timers is a technique commonly used in software testing to simulate and
779
- * control the behavior of timers, such as `setInterval` and `setTimeout`,
780
- * without actually waiting for the specified time intervals.
781
- *
782
- * The `MockTracker` provides a top-level `timers` export
783
- * which is a `MockTimers` instance.
784
- * @since v18.19.0
785
- * @experimental
786
- */
787
- class MockTimers {
788
- /**
789
- * Enables timer mocking for the specified timers.
790
- *
791
- * **Note:** When you enable mocking for a specific timer, its associated
792
- * clear function will also be implicitly mocked.
793
- *
794
- * Example usage:
795
- *
796
- * ```js
797
- * import { mock } from 'node:test';
798
- * mock.timers.enable(['setInterval']);
799
- * ```
800
- *
801
- * The above example enables mocking for the `setInterval` timer and
802
- * implicitly mocks the `clearInterval` function. Only the `setInterval` and `clearInterval` functions from `node:timers`, `node:timers/promises`, and`globalThis` will be mocked.
803
- *
804
- * Alternatively, if you call `mock.timers.enable()` without any parameters:
805
- *
806
- * All timers (`'setInterval'`, `'clearInterval'`, `'setTimeout'`, and `'clearTimeout'`)
807
- * will be mocked. The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout` functions from `node:timers`, `node:timers/promises`,
808
- * and `globalThis` will be mocked.
809
- * @since v18.19.0
810
- */
811
- enable(timers?: Timer[]): void;
812
- /**
813
- * This function restores the default behavior of all mocks that were previously
814
- * created by this `MockTimers` instance and disassociates the mocks
815
- * from the `MockTracker` instance.
816
- *
817
- * **Note:** After each test completes, this function is called on
818
- * the test context's `MockTracker`.
819
- *
820
- * ```js
821
- * import { mock } from 'node:test';
822
- * mock.timers.reset();
823
- * ```
824
- * @since v18.19.0
825
- */
826
- reset(): void;
827
- /**
828
- * Advances time for all mocked timers.
829
- *
830
- * **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts
831
- * only positive numbers. In Node.js, `setTimeout` with negative numbers is
832
- * only supported for web compatibility reasons.
833
- *
834
- * The following example mocks a `setTimeout` function and
835
- * by using `.tick` advances in
836
- * time triggering all pending timers.
837
- *
838
- * ```js
839
- * import assert from 'node:assert';
840
- * import { test } from 'node:test';
841
- *
842
- * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
843
- * const fn = context.mock.fn();
844
- *
845
- * context.mock.timers.enable(['setTimeout']);
846
- *
847
- * setTimeout(fn, 9999);
848
- *
849
- * assert.strictEqual(fn.mock.callCount(), 0);
850
- *
851
- * // Advance in time
852
- * context.mock.timers.tick(9999);
853
- *
854
- * assert.strictEqual(fn.mock.callCount(), 1);
855
- * });
856
- * ```
857
- *
858
- * Alternativelly, the `.tick` function can be called many times
859
- *
860
- * ```js
861
- * import assert from 'node:assert';
862
- * import { test } from 'node:test';
863
- *
864
- * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
865
- * const fn = context.mock.fn();
866
- * context.mock.timers.enable(['setTimeout']);
867
- * const nineSecs = 9000;
868
- * setTimeout(fn, nineSecs);
869
- *
870
- * const twoSeconds = 3000;
871
- * context.mock.timers.tick(twoSeconds);
872
- * context.mock.timers.tick(twoSeconds);
873
- * context.mock.timers.tick(twoSeconds);
874
- *
875
- * assert.strictEqual(fn.mock.callCount(), 1);
876
- * });
877
- * ```
878
- * @since v18.19.0
879
- */
880
- tick(milliseconds: number): void;
881
- /**
882
- * Triggers all pending mocked timers immediately.
883
- *
884
- * The example below triggers all pending timers immediately,
885
- * causing them to execute without any delay.
886
- *
887
- * ```js
888
- * import assert from 'node:assert';
889
- * import { test } from 'node:test';
890
- *
891
- * test('runAll functions following the given order', (context) => {
892
- * context.mock.timers.enable(['setTimeout']);
893
- * const results = [];
894
- * setTimeout(() => results.push(1), 9999);
895
- *
896
- * // Notice that if both timers have the same timeout,
897
- * // the order of execution is guaranteed
898
- * setTimeout(() => results.push(3), 8888);
899
- * setTimeout(() => results.push(2), 8888);
900
- *
901
- * assert.deepStrictEqual(results, []);
902
- *
903
- * context.mock.timers.runAll();
904
- *
905
- * assert.deepStrictEqual(results, [3, 2, 1]);
906
- * });
907
- * ```
908
- *
909
- * **Note:** The `runAll()` function is specifically designed for
910
- * triggering timers in the context of timer mocking.
911
- * It does not have any effect on real-time system
912
- * clocks or actual timers outside of the mocking environment.
913
- * @since v18.19.0
914
- */
915
- runAll(): void;
916
- /**
917
- * Calls {@link MockTimers.reset()}.
918
- */
919
- [Symbol.dispose](): void;
920
- }
921
-
922
- export { after, afterEach, before, beforeEach, describe, it, mock, run, test, test as default };
923
- }
924
-
925
- interface TestError extends Error {
926
- cause: Error;
927
- }
928
- interface TestLocationInfo {
929
- /**
930
- * The column number where the test is defined, or
931
- * `undefined` if the test was run through the REPL.
932
- */
933
- column?: number;
934
- /**
935
- * The path of the test file, `undefined` if test is not ran through a file.
936
- */
937
- file?: string;
938
- /**
939
- * The line number where the test is defined, or
940
- * `undefined` if the test was run through the REPL.
941
- */
942
- line?: number;
943
- }
944
- interface DiagnosticData extends TestLocationInfo {
945
- /**
946
- * The diagnostic message.
947
- */
948
- message: string;
949
- /**
950
- * The nesting level of the test.
951
- */
952
- nesting: number;
953
- }
954
- interface TestCoverage {
955
- /**
956
- * An object containing the coverage report.
957
- */
958
- summary: {
959
- /**
960
- * An array of coverage reports for individual files.
961
- */
962
- files: Array<{
778
+ interface HookOptions {
963
779
  /**
964
- * The absolute path of the file.
780
+ * Allows aborting an in-progress hook.
965
781
  */
966
- path: string;
782
+ signal?: AbortSignal | undefined;
967
783
  /**
968
- * The total number of lines.
784
+ * A number of milliseconds the hook will fail after. If unspecified, subtests inherit this
785
+ * value from their parent.
786
+ * @default Infinity
969
787
  */
970
- totalLineCount: number;
788
+ timeout?: number | undefined;
789
+ }
790
+ interface MockFunctionOptions {
971
791
  /**
972
- * The total number of branches.
792
+ * The number of times that the mock will use the behavior of `implementation`.
793
+ * Once the mock function has been called `times` times,
794
+ * it will automatically restore the behavior of `original`.
795
+ * This value must be an integer greater than zero.
796
+ * @default Infinity
973
797
  */
974
- totalBranchCount: number;
798
+ times?: number | undefined;
799
+ }
800
+ interface MockMethodOptions extends MockFunctionOptions {
975
801
  /**
976
- * The total number of functions.
802
+ * If `true`, `object[methodName]` is treated as a getter.
803
+ * This option cannot be used with the `setter` option.
977
804
  */
978
- totalFunctionCount: number;
805
+ getter?: boolean | undefined;
979
806
  /**
980
- * The number of covered lines.
807
+ * If `true`, `object[methodName]` is treated as a setter.
808
+ * This option cannot be used with the `getter` option.
981
809
  */
982
- coveredLineCount: number;
810
+ setter?: boolean | undefined;
811
+ }
812
+ type Mock<F extends Function> = F & {
813
+ mock: MockFunctionContext<F>;
814
+ };
815
+ interface MockTracker {
983
816
  /**
984
- * The number of covered branches.
817
+ * This function is used to create a mock function.
818
+ * @param original An optional function to create a mock on.
819
+ * @param implementation An optional function used as the mock implementation for `original`.
820
+ * This is useful for creating mocks that exhibit one behavior for a specified number of calls and then restore the behavior of `original`.
821
+ * @param options Optional configuration options for the mock function.
985
822
  */
986
- coveredBranchCount: number;
823
+ fn<F extends Function = (...args: any[]) => undefined>(
824
+ original?: F,
825
+ options?: MockFunctionOptions,
826
+ ): Mock<F>;
827
+ fn<F extends Function = (...args: any[]) => undefined, Implementation extends Function = F>(
828
+ original?: F,
829
+ implementation?: Implementation,
830
+ options?: MockFunctionOptions,
831
+ ): Mock<F | Implementation>;
987
832
  /**
988
- * The number of covered functions.
833
+ * This function is used to create a mock on an existing object method.
834
+ * @param object The object whose method is being mocked.
835
+ * @param methodName The identifier of the method on `object` to mock. If `object[methodName]` is not a function, an error is thrown.
836
+ * @param implementation An optional function used as the mock implementation for `object[methodName]`.
837
+ * @param options Optional configuration options for the mock method.
989
838
  */
990
- coveredFunctionCount: number;
839
+ method<
840
+ MockedObject extends object,
841
+ MethodName extends FunctionPropertyNames<MockedObject>,
842
+ >(
843
+ object: MockedObject,
844
+ methodName: MethodName,
845
+ options?: MockFunctionOptions,
846
+ ): MockedObject[MethodName] extends Function ? Mock<MockedObject[MethodName]>
847
+ : never;
848
+ method<
849
+ MockedObject extends object,
850
+ MethodName extends FunctionPropertyNames<MockedObject>,
851
+ Implementation extends Function,
852
+ >(
853
+ object: MockedObject,
854
+ methodName: MethodName,
855
+ implementation: Implementation,
856
+ options?: MockFunctionOptions,
857
+ ): MockedObject[MethodName] extends Function ? Mock<MockedObject[MethodName] | Implementation>
858
+ : never;
859
+ method<MockedObject extends object>(
860
+ object: MockedObject,
861
+ methodName: keyof MockedObject,
862
+ options: MockMethodOptions,
863
+ ): Mock<Function>;
864
+ method<MockedObject extends object>(
865
+ object: MockedObject,
866
+ methodName: keyof MockedObject,
867
+ implementation: Function,
868
+ options: MockMethodOptions,
869
+ ): Mock<Function>;
991
870
  /**
992
- * The percentage of lines covered.
871
+ * This function is syntax sugar for {@link MockTracker.method} with `options.getter` set to `true`.
993
872
  */
994
- coveredLinePercent: number;
873
+ getter<
874
+ MockedObject extends object,
875
+ MethodName extends keyof MockedObject,
876
+ >(
877
+ object: MockedObject,
878
+ methodName: MethodName,
879
+ options?: MockFunctionOptions,
880
+ ): Mock<() => MockedObject[MethodName]>;
881
+ getter<
882
+ MockedObject extends object,
883
+ MethodName extends keyof MockedObject,
884
+ Implementation extends Function,
885
+ >(
886
+ object: MockedObject,
887
+ methodName: MethodName,
888
+ implementation?: Implementation,
889
+ options?: MockFunctionOptions,
890
+ ): Mock<(() => MockedObject[MethodName]) | Implementation>;
995
891
  /**
996
- * The percentage of branches covered.
892
+ * This function is syntax sugar for {@link MockTracker.method} with `options.setter` set to `true`.
997
893
  */
998
- coveredBranchPercent: number;
894
+ setter<
895
+ MockedObject extends object,
896
+ MethodName extends keyof MockedObject,
897
+ >(
898
+ object: MockedObject,
899
+ methodName: MethodName,
900
+ options?: MockFunctionOptions,
901
+ ): Mock<(value: MockedObject[MethodName]) => void>;
902
+ setter<
903
+ MockedObject extends object,
904
+ MethodName extends keyof MockedObject,
905
+ Implementation extends Function,
906
+ >(
907
+ object: MockedObject,
908
+ methodName: MethodName,
909
+ implementation?: Implementation,
910
+ options?: MockFunctionOptions,
911
+ ): Mock<((value: MockedObject[MethodName]) => void) | Implementation>;
999
912
  /**
1000
- * The percentage of functions covered.
913
+ * This function restores the default behavior of all mocks that were previously created by this `MockTracker`
914
+ * and disassociates the mocks from the `MockTracker` instance. Once disassociated, the mocks can still be used,
915
+ * but the `MockTracker` instance can no longer be used to reset their behavior or otherwise interact with them.
916
+ *
917
+ * After each test completes, this function is called on the test context's `MockTracker`.
918
+ * If the global `MockTracker` is used extensively, calling this function manually is recommended.
1001
919
  */
1002
- coveredFunctionPercent: number;
920
+ reset(): void;
1003
921
  /**
1004
- * An array of integers representing line numbers that are uncovered.
922
+ * This function restores the default behavior of all mocks that were previously created by this `MockTracker`.
923
+ * Unlike `mock.reset()`, `mock.restoreAll()` does not disassociate the mocks from the `MockTracker` instance.
1005
924
  */
1006
- uncoveredLineNumbers: number[];
1007
- }>;
1008
- /**
1009
- * An object containing a summary of coverage for all files.
1010
- */
1011
- totals: {
925
+ restoreAll(): void;
926
+ readonly timers: MockTimers;
927
+ }
928
+ const mock: MockTracker;
929
+ interface MockFunctionCall<
930
+ F extends Function,
931
+ ReturnType = F extends (...args: any) => infer T ? T
932
+ : F extends abstract new(...args: any) => infer T ? T
933
+ : unknown,
934
+ Args = F extends (...args: infer Y) => any ? Y
935
+ : F extends abstract new(...args: infer Y) => any ? Y
936
+ : unknown[],
937
+ > {
1012
938
  /**
1013
- * The total number of lines.
939
+ * An array of the arguments passed to the mock function.
1014
940
  */
1015
- totalLineCount: number;
941
+ arguments: Args;
1016
942
  /**
1017
- * The total number of branches.
943
+ * If the mocked function threw then this property contains the thrown value.
1018
944
  */
1019
- totalBranchCount: number;
945
+ error: unknown | undefined;
1020
946
  /**
1021
- * The total number of functions.
947
+ * The value returned by the mocked function.
948
+ *
949
+ * If the mocked function threw, it will be `undefined`.
1022
950
  */
1023
- totalFunctionCount: number;
951
+ result: ReturnType | undefined;
1024
952
  /**
1025
- * The number of covered lines.
953
+ * An `Error` object whose stack can be used to determine the callsite of the mocked function invocation.
1026
954
  */
1027
- coveredLineCount: number;
955
+ stack: Error;
1028
956
  /**
1029
- * The number of covered branches.
957
+ * If the mocked function is a constructor, this field contains the class being constructed.
958
+ * Otherwise this will be `undefined`.
1030
959
  */
1031
- coveredBranchCount: number;
960
+ target: F extends abstract new(...args: any) => any ? F : undefined;
1032
961
  /**
1033
- * The number of covered functions.
962
+ * The mocked function's `this` value.
1034
963
  */
1035
- coveredFunctionCount: number;
964
+ this: unknown;
965
+ }
966
+ interface MockFunctionContext<F extends Function> {
1036
967
  /**
1037
- * The percentage of lines covered.
968
+ * A getter that returns a copy of the internal array used to track calls to the mock.
1038
969
  */
1039
- coveredLinePercent: number;
970
+ readonly calls: MockFunctionCall<F>[];
1040
971
  /**
1041
- * The percentage of branches covered.
972
+ * This function returns the number of times that this mock has been invoked.
973
+ * This function is more efficient than checking `ctx.calls.length`
974
+ * because `ctx.calls` is a getter that creates a copy of the internal call tracking array.
1042
975
  */
1043
- coveredBranchPercent: number;
976
+ callCount(): number;
1044
977
  /**
1045
- * The percentage of functions covered.
978
+ * This function is used to change the behavior of an existing mock.
979
+ * @param implementation The function to be used as the mock's new implementation.
1046
980
  */
1047
- coveredFunctionPercent: number;
1048
- };
1049
- /**
1050
- * The working directory when code coverage began. This
1051
- * is useful for displaying relative path names in case
1052
- * the tests changed the working directory of the Node.js process.
1053
- */
1054
- workingDirectory: string;
1055
- };
1056
- /**
1057
- * The nesting level of the test.
1058
- */
1059
- nesting: number;
1060
- }
1061
- interface TestDequeue extends TestLocationInfo {
1062
- /**
1063
- * The test name
1064
- */
1065
- name: string;
1066
- /**
1067
- * The nesting level of the test.
1068
- */
1069
- nesting: number;
1070
- }
1071
- interface TestEnqueue extends TestLocationInfo {
1072
- /**
1073
- * The test name
1074
- */
1075
- name: string;
1076
- /**
1077
- * The nesting level of the test.
1078
- */
1079
- nesting: number;
1080
- }
1081
- interface TestFail extends TestLocationInfo {
1082
- /**
1083
- * Additional execution metadata.
1084
- */
1085
- details: {
1086
- /**
1087
- * The duration of the test in milliseconds.
1088
- */
1089
- duration_ms: number;
1090
- /**
1091
- * The error thrown by the test.
1092
- */
1093
- error: TestError;
1094
- /**
1095
- * The type of the test, used to denote whether this is a suite.
1096
- * @since 18.17.0
1097
- */
1098
- type?: "suite";
1099
- };
1100
- /**
1101
- * The test name.
1102
- */
1103
- name: string;
1104
- /**
1105
- * The nesting level of the test.
1106
- */
1107
- nesting: number;
1108
- /**
1109
- * The ordinal number of the test.
1110
- */
1111
- testNumber: number;
1112
- /**
1113
- * Present if `context.todo` is called.
1114
- */
1115
- todo?: string | boolean;
1116
- /**
1117
- * Present if `context.skip` is called.
1118
- */
1119
- skip?: string | boolean;
1120
- }
1121
- interface TestPass extends TestLocationInfo {
1122
- /**
1123
- * Additional execution metadata.
1124
- */
1125
- details: {
1126
- /**
1127
- * The duration of the test in milliseconds.
1128
- */
1129
- duration_ms: number;
981
+ mockImplementation(implementation: F): void;
982
+ /**
983
+ * This function is used to change the behavior of an existing mock for a single invocation.
984
+ * Once invocation `onCall` has occurred, the mock will revert to whatever behavior
985
+ * it would have used had `mockImplementationOnce()` not been called.
986
+ * @param implementation The function to be used as the mock's implementation for the invocation number specified by `onCall`.
987
+ * @param onCall The invocation number that will use `implementation`.
988
+ * If the specified invocation has already occurred then an exception is thrown.
989
+ */
990
+ mockImplementationOnce(implementation: F, onCall?: number): void;
991
+ /**
992
+ * Resets the call history of the mock function.
993
+ */
994
+ resetCalls(): void;
995
+ /**
996
+ * Resets the implementation of the mock function to its original behavior.
997
+ * The mock can still be used after calling this function.
998
+ */
999
+ restore(): void;
1000
+ }
1130
1001
  /**
1131
- * The type of the test, used to denote whether this is a suite.
1132
- * @since 18.17.0
1002
+ * Mocking timers is a technique commonly used in software testing to simulate and
1003
+ * control the behavior of timers, such as `setInterval` and `setTimeout`,
1004
+ * without actually waiting for the specified time intervals.
1005
+ *
1006
+ * The `MockTracker` provides a top-level `timers` export
1007
+ * which is a `MockTimers` instance.
1008
+ * @since v18.19.0
1009
+ * @experimental
1133
1010
  */
1134
- type?: "suite";
1135
- };
1136
- /**
1137
- * The test name.
1138
- */
1139
- name: string;
1140
- /**
1141
- * The nesting level of the test.
1142
- */
1143
- nesting: number;
1144
- /**
1145
- * The ordinal number of the test.
1146
- */
1147
- testNumber: number;
1148
- /**
1149
- * Present if `context.todo` is called.
1150
- */
1151
- todo?: string | boolean;
1152
- /**
1153
- * Present if `context.skip` is called.
1154
- */
1155
- skip?: string | boolean;
1156
- }
1157
- interface TestPlan extends TestLocationInfo {
1158
- /**
1159
- * The nesting level of the test.
1160
- */
1161
- nesting: number;
1162
- /**
1163
- * The number of subtests that have ran.
1164
- */
1165
- count: number;
1166
- }
1167
- interface TestStart extends TestLocationInfo {
1168
- /**
1169
- * The test name.
1170
- */
1171
- name: string;
1172
- /**
1173
- * The nesting level of the test.
1174
- */
1175
- nesting: number;
1176
- }
1177
- interface TestStderr extends TestLocationInfo {
1178
- /**
1179
- * The message written to `stderr`
1180
- */
1181
- message: string;
1182
- }
1183
- interface TestStdout extends TestLocationInfo {
1184
- /**
1185
- * The message written to `stdout`
1186
- */
1187
- message: string;
1011
+ interface MockTimers {
1012
+ /**
1013
+ * Enables timer mocking for the specified timers.
1014
+ *
1015
+ * **Note:** When you enable mocking for a specific timer, its associated
1016
+ * clear function will also be implicitly mocked.
1017
+ *
1018
+ * Example usage:
1019
+ *
1020
+ * ```js
1021
+ * import { mock } from 'node:test';
1022
+ * mock.timers.enable(['setInterval']);
1023
+ * ```
1024
+ *
1025
+ * The above example enables mocking for the `setInterval` timer and
1026
+ * implicitly mocks the `clearInterval` function. Only the `setInterval` and `clearInterval` functions from `node:timers`, `node:timers/promises`, and`globalThis` will be mocked.
1027
+ *
1028
+ * Alternatively, if you call `mock.timers.enable()` without any parameters:
1029
+ *
1030
+ * All timers (`'setInterval'`, `'clearInterval'`, `'setTimeout'`, and `'clearTimeout'`)
1031
+ * will be mocked. The `setInterval`, `clearInterval`, `setTimeout`, and `clearTimeout` functions from `node:timers`, `node:timers/promises`,
1032
+ * and `globalThis` will be mocked.
1033
+ * @since v18.19.0
1034
+ */
1035
+ enable(timers?: ReadonlyArray<"setInterval" | "clearInterval" | "setTimeout" | "clearTimeout">): void;
1036
+ /**
1037
+ * This function restores the default behavior of all mocks that were previously
1038
+ * created by this `MockTimers` instance and disassociates the mocks
1039
+ * from the `MockTracker` instance.
1040
+ *
1041
+ * **Note:** After each test completes, this function is called on
1042
+ * the test context's `MockTracker`.
1043
+ *
1044
+ * ```js
1045
+ * import { mock } from 'node:test';
1046
+ * mock.timers.reset();
1047
+ * ```
1048
+ * @since v18.19.0
1049
+ */
1050
+ reset(): void;
1051
+ /**
1052
+ * Advances time for all mocked timers.
1053
+ *
1054
+ * **Note:** This diverges from how `setTimeout` in Node.js behaves and accepts
1055
+ * only positive numbers. In Node.js, `setTimeout` with negative numbers is
1056
+ * only supported for web compatibility reasons.
1057
+ *
1058
+ * The following example mocks a `setTimeout` function and
1059
+ * by using `.tick` advances in
1060
+ * time triggering all pending timers.
1061
+ *
1062
+ * ```js
1063
+ * import assert from 'node:assert';
1064
+ * import { test } from 'node:test';
1065
+ *
1066
+ * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
1067
+ * const fn = context.mock.fn();
1068
+ *
1069
+ * context.mock.timers.enable(['setTimeout']);
1070
+ *
1071
+ * setTimeout(fn, 9999);
1072
+ *
1073
+ * assert.strictEqual(fn.mock.callCount(), 0);
1074
+ *
1075
+ * // Advance in time
1076
+ * context.mock.timers.tick(9999);
1077
+ *
1078
+ * assert.strictEqual(fn.mock.callCount(), 1);
1079
+ * });
1080
+ * ```
1081
+ *
1082
+ * Alternativelly, the `.tick` function can be called many times
1083
+ *
1084
+ * ```js
1085
+ * import assert from 'node:assert';
1086
+ * import { test } from 'node:test';
1087
+ *
1088
+ * test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
1089
+ * const fn = context.mock.fn();
1090
+ * context.mock.timers.enable(['setTimeout']);
1091
+ * const nineSecs = 9000;
1092
+ * setTimeout(fn, nineSecs);
1093
+ *
1094
+ * const twoSeconds = 3000;
1095
+ * context.mock.timers.tick(twoSeconds);
1096
+ * context.mock.timers.tick(twoSeconds);
1097
+ * context.mock.timers.tick(twoSeconds);
1098
+ *
1099
+ * assert.strictEqual(fn.mock.callCount(), 1);
1100
+ * });
1101
+ * ```
1102
+ * @since v18.19.0
1103
+ */
1104
+ tick(milliseconds: number): void;
1105
+ /**
1106
+ * Triggers all pending mocked timers immediately.
1107
+ *
1108
+ * The example below triggers all pending timers immediately,
1109
+ * causing them to execute without any delay.
1110
+ *
1111
+ * ```js
1112
+ * import assert from 'node:assert';
1113
+ * import { test } from 'node:test';
1114
+ *
1115
+ * test('runAll functions following the given order', (context) => {
1116
+ * context.mock.timers.enable(['setTimeout']);
1117
+ * const results = [];
1118
+ * setTimeout(() => results.push(1), 9999);
1119
+ *
1120
+ * // Notice that if both timers have the same timeout,
1121
+ * // the order of execution is guaranteed
1122
+ * setTimeout(() => results.push(3), 8888);
1123
+ * setTimeout(() => results.push(2), 8888);
1124
+ *
1125
+ * assert.deepStrictEqual(results, []);
1126
+ *
1127
+ * context.mock.timers.runAll();
1128
+ *
1129
+ * assert.deepStrictEqual(results, [3, 2, 1]);
1130
+ * });
1131
+ * ```
1132
+ *
1133
+ * **Note:** The `runAll()` function is specifically designed for
1134
+ * triggering timers in the context of timer mocking.
1135
+ * It does not have any effect on real-time system
1136
+ * clocks or actual timers outside of the mocking environment.
1137
+ * @since v18.19.0
1138
+ */
1139
+ runAll(): void;
1140
+ /**
1141
+ * Calls {@link MockTimers.reset()}.
1142
+ */
1143
+ [Symbol.dispose](): void;
1144
+ }
1145
+ }
1146
+ type FunctionPropertyNames<T> = {
1147
+ [K in keyof T]: T[K] extends Function ? K : never;
1148
+ }[keyof T];
1149
+ export = test;
1188
1150
  }
1189
1151
 
1190
1152
  /**
@@ -1206,18 +1168,19 @@ interface TestStdout extends TestLocationInfo {
1206
1168
  */
1207
1169
  declare module "node:test/reporters" {
1208
1170
  import { Transform } from "node:stream";
1171
+ import { EventData } from "node:test";
1209
1172
 
1210
1173
  type TestEvent =
1211
- | { type: "test:coverage"; data: TestCoverage }
1212
- | { type: "test:dequeue"; data: TestDequeue }
1213
- | { type: "test:diagnostic"; data: DiagnosticData }
1214
- | { type: "test:enqueue"; data: TestEnqueue }
1215
- | { type: "test:fail"; data: TestFail }
1216
- | { type: "test:pass"; data: TestPass }
1217
- | { type: "test:plan"; data: TestPlan }
1218
- | { type: "test:start"; data: TestStart }
1219
- | { type: "test:stderr"; data: TestStderr }
1220
- | { type: "test:stdout"; data: TestStdout }
1174
+ | { type: "test:coverage"; data: EventData.TestCoverage }
1175
+ | { type: "test:dequeue"; data: EventData.TestDequeue }
1176
+ | { type: "test:diagnostic"; data: EventData.TestDiagnostic }
1177
+ | { type: "test:enqueue"; data: EventData.TestEnqueue }
1178
+ | { type: "test:fail"; data: EventData.TestFail }
1179
+ | { type: "test:pass"; data: EventData.TestPass }
1180
+ | { type: "test:plan"; data: EventData.TestPlan }
1181
+ | { type: "test:start"; data: EventData.TestStart }
1182
+ | { type: "test:stderr"; data: EventData.TestStderr }
1183
+ | { type: "test:stdout"; data: EventData.TestStdout }
1221
1184
  | { type: "test:watch:drained"; data: undefined };
1222
1185
  type TestEventGenerator = AsyncGenerator<TestEvent, void>;
1223
1186