Pinsave/counterstrike
1
1/**2 * The `node:test` module facilitates the creation of JavaScript tests.3 * To access it:4 *5 * ```js6 * import test from 'node:test';7 * ```8 *9 * This module is only available under the `node:` scheme. The following will not10 * work:11 *12 * ```js13 * import test from 'node:test';14 * ```15 *16 * Tests created via the `test` module consist of a single function that is17 * processed in one of three ways:18 *19 * 1. A synchronous function that is considered failing if it throws an exception,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` fulfills.22 * 3. A function that receives a callback function. If the callback receives any23 * truthy value as its first argument, the test is considered failing. If a24 * falsy value is passed as the first argument to the callback, the test is25 * considered passing. If the test function receives a callback function and26 * also returns a `Promise`, the test will fail.27 *28 * The following example illustrates how tests are written using the `test` module.29 *30 * ```js31 * test('synchronous passing test', (t) => {32 * // This test passes because it does not throw an exception.33 * assert.strictEqual(1, 1);34 * });35 *36 * test('synchronous failing test', (t) => {37 * // This test fails because it throws an exception.38 * assert.strictEqual(1, 2);39 * });40 *41 * test('asynchronous passing test', async (t) => {42 * // This test passes because the Promise returned by the async43 * // function is settled and not rejected.44 * assert.strictEqual(1, 1);45 * });46 *47 * test('asynchronous failing test', async (t) => {48 * // This test fails because the Promise returned by the async49 * // function is rejected.50 * assert.strictEqual(1, 2);51 * });52 *53 * test('failing test using Promises', (t) => {54 * // Promises can be used directly as well.55 * return new Promise((resolve, reject) => {56 * setImmediate(() => {57 * reject(new Error('this will cause the test to fail'));58 * });59 * });60 * });61 *62 * test('callback passing test', (t, done) => {63 * // done() is the callback function. When the setImmediate() runs, it invokes64 * // done() with no arguments.65 * setImmediate(done);66 * });67 *68 * test('callback failing test', (t, done) => {69 * // When the setImmediate() runs, done() is invoked with an Error object and70 * // the test fails.71 * setImmediate(() => {72 * done(new Error('callback failure'));73 * });74 * });75 * ```76 *77 * If any tests fail, the process exit code is set to `1`.78 * @since v18.0.0, v16.17.079 * @see [source](https://github.com/nodejs/node/blob/v24.x/lib/test.js)80 */81declare module "node:test" {82 import { Readable } from "node:stream";83 import TestFn = test.TestFn;84 import TestOptions = test.TestOptions;85 /**86 * The `test()` function is the value imported from the `test` module. Each87 * invocation of this function results in reporting the test to the `TestsStream`.88 *89 * The `TestContext` object passed to the `fn` argument can be used to perform90 * actions related to the current test. Examples include skipping the test, adding91 * additional diagnostic information, or creating subtests.92 *93 * `test()` returns a `Promise` that fulfills once the test completes.94 * if `test()` is called within a suite, it fulfills immediately.95 * The return value can usually be discarded for top level tests.96 * However, the return value from subtests should be used to prevent the parent97 * test from finishing first and cancelling the subtest98 * as shown in the following example.99 *100 * ```js101 * test('top level test', async (t) => {102 * // The setTimeout() in the following subtest would cause it to outlive its103 * // parent test if 'await' is removed on the next line. Once the parent test104 * // completes, it will cancel any outstanding subtests.105 * await t.test('longer running subtest', async (t) => {106 * return new Promise((resolve, reject) => {107 * setTimeout(resolve, 1000);108 * });109 * });110 * });111 * ```112 *113 * 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 for114 * canceling tests because a running test might block the application thread and115 * thus prevent the scheduled cancellation.116 * @since v18.0.0, v16.17.0117 * @param name The name of the test, which is displayed when reporting test results.118 * Defaults to the `name` property of `fn`, or `'<anonymous>'` if `fn` does not have a name.119 * @param options Configuration options for the test.120 * @param fn The function under test. The first argument to this function is a {@link TestContext} object.121 * If the test uses callbacks, the callback function is passed as the second argument.122 * @return Fulfilled with `undefined` once the test completes, or immediately if the test runs within a suite.123 */124 function test(name?: string, fn?: TestFn): Promise<void>;125 function test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;126 function test(options?: TestOptions, fn?: TestFn): Promise<void>;127 function test(fn?: TestFn): Promise<void>;128 namespace test {129 export { test };130 export { suite as describe, test as it };131 }132 namespace test {133 /**134 * **Note:** `shard` is used to horizontally parallelize test running across135 * machines or processes, ideal for large-scale executions across varied136 * environments. It's incompatible with `watch` mode, tailored for rapid137 * code iteration by automatically rerunning tests on file changes.138 *139 * ```js140 * import { tap } from 'node:test/reporters';141 * import { run } from 'node:test';142 * import process from 'node:process';143 * import path from 'node:path';144 *145 * run({ files: [path.resolve('./tests/test.js')] })146 * .compose(tap)147 * .pipe(process.stdout);148 * ```149 * @since v18.9.0, v16.19.0150 * @param options Configuration options for running tests.151 */152 function run(options?: RunOptions): TestsStream;153 /**154 * The `suite()` function is imported from the `node:test` module.155 * @param name The name of the suite, which is displayed when reporting test results.156 * Defaults to the `name` property of `fn`, or `'<anonymous>'` if `fn` does not have a name.157 * @param options Configuration options for the suite. This supports the same options as {@link test}.158 * @param fn The suite function declaring nested tests and suites. The first argument to this function is a {@link SuiteContext} object.159 * @return Immediately fulfilled with `undefined`.160 * @since v20.13.0161 */162 function suite(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;163 function suite(name?: string, fn?: SuiteFn): Promise<void>;164 function suite(options?: TestOptions, fn?: SuiteFn): Promise<void>;165 function suite(fn?: SuiteFn): Promise<void>;166 namespace suite {167 /**168 * Shorthand for skipping a suite. This is the same as calling {@link suite} with `options.skip` set to `true`.169 * @since v20.13.0170 */171 function skip(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;172 function skip(name?: string, fn?: SuiteFn): Promise<void>;173 function skip(options?: TestOptions, fn?: SuiteFn): Promise<void>;174 function skip(fn?: SuiteFn): Promise<void>;175 /**176 * Shorthand for marking a suite as `TODO`. This is the same as calling {@link suite} with `options.todo` set to `true`.177 * @since v20.13.0178 */179 function todo(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;180 function todo(name?: string, fn?: SuiteFn): Promise<void>;181 function todo(options?: TestOptions, fn?: SuiteFn): Promise<void>;182 function todo(fn?: SuiteFn): Promise<void>;183 /**184 * Shorthand for marking a suite as `only`. This is the same as calling {@link suite} with `options.only` set to `true`.185 * @since v20.13.0186 */187 function only(name?: string, options?: TestOptions, fn?: SuiteFn): Promise<void>;188 function only(name?: string, fn?: SuiteFn): Promise<void>;189 function only(options?: TestOptions, fn?: SuiteFn): Promise<void>;190 function only(fn?: SuiteFn): Promise<void>;191 }192 /**193 * Shorthand for skipping a test. This is the same as calling {@link test} with `options.skip` set to `true`.194 * @since v20.2.0195 */196 function skip(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;197 function skip(name?: string, fn?: TestFn): Promise<void>;198 function skip(options?: TestOptions, fn?: TestFn): Promise<void>;199 function skip(fn?: TestFn): Promise<void>;200 /**201 * Shorthand for marking a test as `TODO`. This is the same as calling {@link test} with `options.todo` set to `true`.202 * @since v20.2.0203 */204 function todo(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;205 function todo(name?: string, fn?: TestFn): Promise<void>;206 function todo(options?: TestOptions, fn?: TestFn): Promise<void>;207 function todo(fn?: TestFn): Promise<void>;208 /**209 * Shorthand for marking a test as `only`. This is the same as calling {@link test} with `options.only` set to `true`.210 * @since v20.2.0211 */212 function only(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;213 function only(name?: string, fn?: TestFn): Promise<void>;214 function only(options?: TestOptions, fn?: TestFn): Promise<void>;215 function only(fn?: TestFn): Promise<void>;216 /**217 * The type of a function passed to {@link test}. The first argument to this function is a {@link TestContext} object.218 * If the test uses callbacks, the callback function is passed as the second argument.219 */220 type TestFn = (t: TestContext, done: (result?: any) => void) => void | Promise<void>;221 /**222 * The type of a suite test function. The argument to this function is a {@link SuiteContext} object.223 */224 type SuiteFn = (s: SuiteContext) => void | Promise<void>;225 interface TestShard {226 /**227 * A positive integer between 1 and `total` that specifies the index of the shard to run.228 */229 index: number;230 /**231 * A positive integer that specifies the total number of shards to split the test files to.232 */233 total: number;234 }235 interface RunOptions {236 /**237 * If a number is provided, then that many test processes would run in parallel, where each process corresponds to one test file.238 * If `true`, it would run `os.availableParallelism() - 1` test files in parallel. If `false`, it would only run one test file at a time.239 * @default false240 */241 concurrency?: number | boolean | undefined;242 /**243 * Specifies the current working directory to be used by the test runner.244 * Serves as the base path for resolving files according to the245 * [test runner execution model](https://nodejs.org/docs/latest-v24.x/api/test.html#test-runner-execution-model).246 * @since v23.0.0247 * @default process.cwd()248 */249 cwd?: string | undefined;250 /**251 * An array containing the list of files to run. If omitted, files are run according to the252 * [test runner execution model](https://nodejs.org/docs/latest-v24.x/api/test.html#test-runner-execution-model).253 */254 files?: readonly string[] | undefined;255 /**256 * Configures the test runner to exit the process once all known257 * tests have finished executing even if the event loop would258 * otherwise remain active.259 * @default false260 */261 forceExit?: boolean | undefined;262 /**263 * An array containing the list of glob patterns to match test files.264 * This option cannot be used together with `files`. If omitted, files are run according to the265 * [test runner execution model](https://nodejs.org/docs/latest-v24.x/api/test.html#test-runner-execution-model).266 * @since v22.6.0267 */268 globPatterns?: readonly string[] | undefined;269 /**270 * Sets inspector port of test child process.271 * This can be a number, or a function that takes no arguments and returns a272 * number. If a nullish value is provided, each process gets its own port,273 * incremented from the primary's `process.debugPort`. This option is ignored274 * if the `isolation` option is set to `'none'` as no child processes are275 * spawned.276 * @default undefined277 */278 inspectPort?: number | (() => number) | undefined;279 /**280 * Configures the type of test isolation. If set to281 * `'process'`, each test file is run in a separate child process. If set to282 * `'none'`, all test files run in the current process.283 * @default 'process'284 * @since v22.8.0285 */286 isolation?: "process" | "none" | undefined;287 /**288 * If truthy, the test context will only run tests that have the `only` option set289 */290 only?: boolean | undefined;291 /**292 * A function that accepts the `TestsStream` instance and can be used to setup listeners before any tests are run.293 * @default undefined294 */295 setup?: ((reporter: TestsStream) => void | Promise<void>) | undefined;296 /**297 * An array of CLI flags to pass to the `node` executable when298 * spawning the subprocesses. This option has no effect when `isolation` is `'none`'.299 * @since v22.10.0300 * @default []301 */302 execArgv?: readonly string[] | undefined;303 /**304 * An array of CLI flags to pass to each test file when spawning the305 * subprocesses. This option has no effect when `isolation` is `'none'`.306 * @since v22.10.0307 * @default []308 */309 argv?: readonly string[] | undefined;310 /**311 * Allows aborting an in-progress test execution.312 */313 signal?: AbortSignal | undefined;314 /**315 * If provided, only run tests whose name matches the provided pattern.316 * Strings are interpreted as JavaScript regular expressions.317 * @default undefined318 */319 testNamePatterns?: string | RegExp | ReadonlyArray<string | RegExp> | undefined;320 /**321 * A String, RegExp or a RegExp Array, that can be used to exclude running tests whose322 * name matches the provided pattern. Test name patterns are interpreted as JavaScript323 * regular expressions. For each test that is executed, any corresponding test hooks,324 * such as `beforeEach()`, are also run.325 * @default undefined326 * @since v22.1.0327 */328 testSkipPatterns?: string | RegExp | ReadonlyArray<string | RegExp> | undefined;329 /**330 * The number of milliseconds after which the test execution will fail.331 * If unspecified, subtests inherit this value from their parent.332 * @default Infinity333 */334 timeout?: number | undefined;335 /**336 * Whether to run in watch mode or not.337 * @default false338 */339 watch?: boolean | undefined;340 /**341 * Running tests in a specific shard.342 * @default undefined343 */344 shard?: TestShard | undefined;345 /**346 * enable [code coverage](https://nodejs.org/docs/latest-v24.x/api/test.html#collecting-code-coverage) collection.347 * @since v22.10.0348 * @default false349 */350 coverage?: boolean | undefined;351 /**352 * Excludes specific files from code coverage353 * using a glob pattern, which can match both absolute and relative file paths.354 * This property is only applicable when `coverage` was set to `true`.355 * If both `coverageExcludeGlobs` and `coverageIncludeGlobs` are provided,356 * files must meet **both** criteria to be included in the coverage report.357 * @since v22.10.0358 * @default undefined359 */360 coverageExcludeGlobs?: string | readonly string[] | undefined;361 /**362 * Includes specific files in code coverage363 * using a glob pattern, which can match both absolute and relative file paths.364 * This property is only applicable when `coverage` was set to `true`.365 * If both `coverageExcludeGlobs` and `coverageIncludeGlobs` are provided,366 * files must meet **both** criteria to be included in the coverage report.367 * @since v22.10.0368 * @default undefined369 */370 coverageIncludeGlobs?: string | readonly string[] | undefined;371 /**372 * Require a minimum percent of covered lines. If code373 * coverage does not reach the threshold specified, the process will exit with code `1`.374 * @since v22.10.0375 * @default 0376 */377 lineCoverage?: number | undefined;378 /**379 * Require a minimum percent of covered branches. If code380 * coverage does not reach the threshold specified, the process will exit with code `1`.381 * @since v22.10.0382 * @default 0383 */384 branchCoverage?: number | undefined;385 /**386 * Require a minimum percent of covered functions. If code387 * coverage does not reach the threshold specified, the process will exit with code `1`.388 * @since v22.10.0389 * @default 0390 */391 functionCoverage?: number | undefined;392 }393 /**394 * A successful call to `run()` will return a new `TestsStream` object, streaming a series of events representing the execution of the tests.395 *396 * 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.397 * @since v18.9.0, v16.19.0398 */399 interface TestsStream extends Readable {400 addListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;401 addListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;402 addListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;403 addListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;404 addListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;405 addListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;406 addListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;407 addListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;408 addListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;409 addListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;410 addListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;411 addListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;412 addListener(event: "test:watch:drained", listener: () => void): this;413 addListener(event: string, listener: (...args: any[]) => void): this;414 emit(event: "test:coverage", data: EventData.TestCoverage): boolean;415 emit(event: "test:complete", data: EventData.TestComplete): boolean;416 emit(event: "test:dequeue", data: EventData.TestDequeue): boolean;417 emit(event: "test:diagnostic", data: EventData.TestDiagnostic): boolean;418 emit(event: "test:enqueue", data: EventData.TestEnqueue): boolean;419 emit(event: "test:fail", data: EventData.TestFail): boolean;420 emit(event: "test:pass", data: EventData.TestPass): boolean;421 emit(event: "test:plan", data: EventData.TestPlan): boolean;422 emit(event: "test:start", data: EventData.TestStart): boolean;423 emit(event: "test:stderr", data: EventData.TestStderr): boolean;424 emit(event: "test:stdout", data: EventData.TestStdout): boolean;425 emit(event: "test:summary", data: EventData.TestSummary): boolean;426 emit(event: "test:watch:drained"): boolean;427 emit(event: string | symbol, ...args: any[]): boolean;428 on(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;429 on(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;430 on(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;431 on(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;432 on(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;433 on(event: "test:fail", listener: (data: EventData.TestFail) => void): this;434 on(event: "test:pass", listener: (data: EventData.TestPass) => void): this;435 on(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;436 on(event: "test:start", listener: (data: EventData.TestStart) => void): this;437 on(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;438 on(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;439 on(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;440 on(event: "test:watch:drained", listener: () => void): this;441 on(event: string, listener: (...args: any[]) => void): this;442 once(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;443 once(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;444 once(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;445 once(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;446 once(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;447 once(event: "test:fail", listener: (data: EventData.TestFail) => void): this;448 once(event: "test:pass", listener: (data: EventData.TestPass) => void): this;449 once(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;450 once(event: "test:start", listener: (data: EventData.TestStart) => void): this;451 once(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;452 once(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;453 once(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;454 once(event: "test:watch:drained", listener: () => void): this;455 once(event: string, listener: (...args: any[]) => void): this;456 prependListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;457 prependListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;458 prependListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;459 prependListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;460 prependListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;461 prependListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;462 prependListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;463 prependListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;464 prependListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;465 prependListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;466 prependListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;467 prependListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;468 prependListener(event: "test:watch:drained", listener: () => void): this;469 prependListener(event: string, listener: (...args: any[]) => void): this;470 prependOnceListener(event: "test:coverage", listener: (data: EventData.TestCoverage) => void): this;471 prependOnceListener(event: "test:complete", listener: (data: EventData.TestComplete) => void): this;472 prependOnceListener(event: "test:dequeue", listener: (data: EventData.TestDequeue) => void): this;473 prependOnceListener(event: "test:diagnostic", listener: (data: EventData.TestDiagnostic) => void): this;474 prependOnceListener(event: "test:enqueue", listener: (data: EventData.TestEnqueue) => void): this;475 prependOnceListener(event: "test:fail", listener: (data: EventData.TestFail) => void): this;476 prependOnceListener(event: "test:pass", listener: (data: EventData.TestPass) => void): this;477 prependOnceListener(event: "test:plan", listener: (data: EventData.TestPlan) => void): this;478 prependOnceListener(event: "test:start", listener: (data: EventData.TestStart) => void): this;479 prependOnceListener(event: "test:stderr", listener: (data: EventData.TestStderr) => void): this;480 prependOnceListener(event: "test:stdout", listener: (data: EventData.TestStdout) => void): this;481 prependOnceListener(event: "test:summary", listener: (data: EventData.TestSummary) => void): this;482 prependOnceListener(event: "test:watch:drained", listener: () => void): this;483 prependOnceListener(event: string, listener: (...args: any[]) => void): this;484 }485 namespace EventData {486 interface Error extends globalThis.Error {487 cause: globalThis.Error;488 }489 interface LocationInfo {490 /**491 * The column number where the test is defined, or492 * `undefined` if the test was run through the REPL.493 */494 column?: number;495 /**496 * The path of the test file, `undefined` if test was run through the REPL.497 */498 file?: string;499 /**500 * The line number where the test is defined, or `undefined` if the test was run through the REPL.501 */502 line?: number;503 }504 interface TestDiagnostic extends LocationInfo {505 /**506 * The diagnostic message.507 */508 message: string;509 /**510 * The nesting level of the test.511 */512 nesting: number;513 }514 interface TestCoverage {515 /**516 * An object containing the coverage report.517 */518 summary: {519 /**520 * An array of coverage reports for individual files.521 */522 files: Array<{523 /**524 * The absolute path of the file.525 */526 path: string;527 /**528 * The total number of lines.529 */530 totalLineCount: number;531 /**532 * The total number of branches.533 */534 totalBranchCount: number;535 /**536 * The total number of functions.537 */538 totalFunctionCount: number;539 /**540 * The number of covered lines.541 */542 coveredLineCount: number;543 /**544 * The number of covered branches.545 */546 coveredBranchCount: number;547 /**548 * The number of covered functions.549 */550 coveredFunctionCount: number;551 /**552 * The percentage of lines covered.553 */554 coveredLinePercent: number;555 /**556 * The percentage of branches covered.557 */558 coveredBranchPercent: number;559 /**560 * The percentage of functions covered.561 */562 coveredFunctionPercent: number;563 /**564 * An array of functions representing function coverage.565 */566 functions: Array<{567 /**568 * The name of the function.569 */570 name: string;571 /**572 * The line number where the function is defined.573 */574 line: number;575 /**576 * The number of times the function was called.577 */578 count: number;579 }>;580 /**581 * An array of branches representing branch coverage.582 */583 branches: Array<{584 /**585 * The line number where the branch is defined.586 */587 line: number;588 /**589 * The number of times the branch was taken.590 */591 count: number;592 }>;593 /**594 * An array of lines representing line numbers and the number of times they were covered.595 */596 lines: Array<{597 /**598 * The line number.599 */600 line: number;601 /**602 * The number of times the line was covered.603 */604 count: number;605 }>;606 }>;607 /**608 * An object containing whether or not the coverage for609 * each coverage type.610 * @since v22.9.0611 */612 thresholds: {613 /**614 * The function coverage threshold.615 */616 function: number;617 /**618 * The branch coverage threshold.619 */620 branch: number;621 /**622 * The line coverage threshold.623 */624 line: number;625 };626 /**627 * An object containing a summary of coverage for all files.628 */629 totals: {630 /**631 * The total number of lines.632 */633 totalLineCount: number;634 /**635 * The total number of branches.636 */637 totalBranchCount: number;638 /**639 * The total number of functions.640 */641 totalFunctionCount: number;642 /**643 * The number of covered lines.644 */645 coveredLineCount: number;646 /**647 * The number of covered branches.648 */649 coveredBranchCount: number;650 /**651 * The number of covered functions.652 */653 coveredFunctionCount: number;654 /**655 * The percentage of lines covered.656 */657 coveredLinePercent: number;658 /**659 * The percentage of branches covered.660 */661 coveredBranchPercent: number;662 /**663 * The percentage of functions covered.664 */665 coveredFunctionPercent: number;666 };667 /**668 * The working directory when code coverage began. This669 * is useful for displaying relative path names in case670 * the tests changed the working directory of the Node.js process.671 */672 workingDirectory: string;673 };674 /**675 * The nesting level of the test.676 */677 nesting: number;678 }679 interface TestComplete extends LocationInfo {680 /**681 * Additional execution metadata.682 */683 details: {684 /**685 * Whether the test passed or not.686 */687 passed: boolean;688 /**689 * The duration of the test in milliseconds.690 */691 duration_ms: number;692 /**693 * An error wrapping the error thrown by the test if it did not pass.694 */695 error?: Error;696 /**697 * The type of the test, used to denote whether this is a suite.698 */699 type?: "suite";700 };701 /**702 * The test name.703 */704 name: string;705 /**706 * The nesting level of the test.707 */708 nesting: number;709 /**710 * The ordinal number of the test.711 */712 testNumber: number;713 /**714 * Present if `context.todo` is called.715 */716 todo?: string | boolean;717 /**718 * Present if `context.skip` is called.719 */720 skip?: string | boolean;721 }722 interface TestDequeue extends LocationInfo {723 /**724 * The test name.725 */726 name: string;727 /**728 * The nesting level of the test.729 */730 nesting: number;731 /**732 * The test type. Either `'suite'` or `'test'`.733 * @since v22.15.0734 */735 type: "suite" | "test";736 }737 interface TestEnqueue extends LocationInfo {738 /**739 * The test name.740 */741 name: string;742 /**743 * The nesting level of the test.744 */745 nesting: number;746 /**747 * The test type. Either `'suite'` or `'test'`.748 * @since v22.15.0749 */750 type: "suite" | "test";751 }752 interface TestFail extends LocationInfo {753 /**754 * Additional execution metadata.755 */756 details: {757 /**758 * The duration of the test in milliseconds.759 */760 duration_ms: number;761 /**762 * An error wrapping the error thrown by the test.763 */764 error: Error;765 /**766 * The type of the test, used to denote whether this is a suite.767 * @since v20.0.0, v19.9.0, v18.17.0768 */769 type?: "suite";770 };771 /**772 * The test name.773 */774 name: string;775 /**776 * The nesting level of the test.777 */778 nesting: number;779 /**780 * The ordinal number of the test.781 */782 testNumber: number;783 /**784 * Present if `context.todo` is called.785 */786 todo?: string | boolean;787 /**788 * Present if `context.skip` is called.789 */790 skip?: string | boolean;791 }792 interface TestPass extends LocationInfo {793 /**794 * Additional execution metadata.795 */796 details: {797 /**798 * The duration of the test in milliseconds.799 */800 duration_ms: number;801 /**802 * The type of the test, used to denote whether this is a suite.803 * @since 20.0.0, 19.9.0, 18.17.0804 */805 type?: "suite";806 };807 /**808 * The test name.809 */810 name: string;811 /**812 * The nesting level of the test.813 */814 nesting: number;815 /**816 * The ordinal number of the test.817 */818 testNumber: number;819 /**820 * Present if `context.todo` is called.821 */822 todo?: string | boolean;823 /**824 * Present if `context.skip` is called.825 */826 skip?: string | boolean;827 }828 interface TestPlan extends LocationInfo {829 /**830 * The nesting level of the test.831 */832 nesting: number;833 /**834 * The number of subtests that have ran.835 */836 count: number;837 }838 interface TestStart extends LocationInfo {839 /**840 * The test name.841 */842 name: string;843 /**844 * The nesting level of the test.845 */846 nesting: number;847 }848 interface TestStderr {849 /**850 * The path of the test file.851 */852 file: string;853 /**854 * The message written to `stderr`.855 */856 message: string;857 }858 interface TestStdout {859 /**860 * The path of the test file.861 */862 file: string;863 /**864 * The message written to `stdout`.865 */866 message: string;867 }868 interface TestSummary {869 /**870 * An object containing the counts of various test results.871 */872 counts: {873 /**874 * The total number of cancelled tests.875 */876 cancelled: number;877 /**878 * The total number of passed tests.879 */880 passed: number;881 /**882 * The total number of skipped tests.883 */884 skipped: number;885 /**886 * The total number of suites run.887 */888 suites: number;889 /**890 * The total number of tests run, excluding suites.891 */892 tests: number;893 /**894 * The total number of TODO tests.895 */896 todo: number;897 /**898 * The total number of top level tests and suites.899 */900 topLevel: number;901 };902 /**903 * The duration of the test run in milliseconds.904 */905 duration_ms: number;906 /**907 * The path of the test file that generated the908 * summary. If the summary corresponds to multiple files, this value is909 * `undefined`.910 */911 file: string | undefined;912 /**913 * Indicates whether or not the test run is considered914 * successful or not. If any error condition occurs, such as a failing test or915 * unmet coverage threshold, this value will be set to `false`.916 */917 success: boolean;918 }919 }920 /**921 * An instance of `TestContext` is passed to each test function in order to922 * interact with the test runner. However, the `TestContext` constructor is not923 * exposed as part of the API.924 * @since v18.0.0, v16.17.0925 */926 interface TestContext {927 /**928 * An object containing assertion methods bound to the test context.929 * The top-level functions from the `node:assert` module are exposed here for the purpose of creating test plans.930 *931 * **Note:** Some of the functions from `node:assert` contain type assertions. If these are called via the932 * TestContext `assert` object, then the context parameter in the test's function signature **must be explicitly typed**933 * (ie. the parameter must have a type annotation), otherwise an error will be raised by the TypeScript compiler:934 * ```ts935 * import { test, type TestContext } from 'node:test';936 *937 * // The test function's context parameter must have a type annotation.938 * test('example', (t: TestContext) => {939 * t.assert.deepStrictEqual(actual, expected);940 * });941 *942 * // Omitting the type annotation will result in a compilation error.943 * test('example', t => {944 * t.assert.deepStrictEqual(actual, expected); // Error: 't' needs an explicit type annotation.945 * });946 * ```947 * @since v22.2.0, v20.15.0948 */949 readonly assert: TestContextAssert;950 /**951 * This function is used to create a hook running before subtest of the current test.952 * @param fn The hook function. The first argument to this function is a `TestContext` object.953 * If the hook uses callbacks, the callback function is passed as the second argument.954 * @param options Configuration options for the hook.955 * @since v20.1.0, v18.17.0956 */957 before(fn?: TestContextHookFn, options?: HookOptions): void;958 /**959 * This function is used to create a hook running before each subtest of the current test.960 * @param fn The hook function. The first argument to this function is a `TestContext` object.961 * If the hook uses callbacks, the callback function is passed as the second argument.962 * @param options Configuration options for the hook.963 * @since v18.8.0964 */965 beforeEach(fn?: TestContextHookFn, options?: HookOptions): void;966 /**967 * This function is used to create a hook that runs after the current test finishes.968 * @param fn The hook function. The first argument to this function is a `TestContext` object.969 * If the hook uses callbacks, the callback function is passed as the second argument.970 * @param options Configuration options for the hook.971 * @since v18.13.0972 */973 after(fn?: TestContextHookFn, options?: HookOptions): void;974 /**975 * This function is used to create a hook running after each subtest of the current test.976 * @param fn The hook function. The first argument to this function is a `TestContext` object.977 * If the hook uses callbacks, the callback function is passed as the second argument.978 * @param options Configuration options for the hook.979 * @since v18.8.0980 */981 afterEach(fn?: TestContextHookFn, options?: HookOptions): void;982 /**983 * This function is used to write diagnostics to the output. Any diagnostic984 * information is included at the end of the test's results. This function does985 * not return a value.986 *987 * ```js988 * test('top level test', (t) => {989 * t.diagnostic('A diagnostic message');990 * });991 * ```992 * @since v18.0.0, v16.17.0993 * @param message Message to be reported.994 */995 diagnostic(message: string): void;996 /**997 * The absolute path of the test file that created the current test. If a test file imports998 * additional modules that generate tests, the imported tests will return the path of the root test file.999 * @since v22.6.01000 */1001 readonly filePath: string | undefined;1002 /**1003 * The name of the test and each of its ancestors, separated by `>`.1004 * @since v22.3.01005 */1006 readonly fullName: string;1007 /**1008 * The name of the test.1009 * @since v18.8.0, v16.18.01010 */1011 readonly name: string;1012 /**1013 * This function is used to set the number of assertions and subtests that are expected to run1014 * within the test. If the number of assertions and subtests that run does not match the1015 * expected count, the test will fail.1016 *1017 * > Note: To make sure assertions are tracked, `t.assert` must be used instead of `assert` directly.1018 *1019 * ```js1020 * test('top level test', (t) => {1021 * t.plan(2);1022 * t.assert.ok('some relevant assertion here');1023 * t.test('subtest', () => {});1024 * });1025 * ```1026 *1027 * When working with asynchronous code, the `plan` function can be used to ensure that the1028 * correct number of assertions are run:1029 *1030 * ```js1031 * test('planning with streams', (t, done) => {1032 * function* generate() {1033 * yield 'a';1034 * yield 'b';1035 * yield 'c';1036 * }1037 * const expected = ['a', 'b', 'c'];1038 * t.plan(expected.length);1039 * const stream = Readable.from(generate());1040 * stream.on('data', (chunk) => {1041 * t.assert.strictEqual(chunk, expected.shift());1042 * });1043 *1044 * stream.on('end', () => {1045 * done();1046 * });1047 * });1048 * ```1049 *1050 * When using the `wait` option, you can control how long the test will wait for the expected assertions.1051 * For example, setting a maximum wait time ensures that the test will wait for asynchronous assertions1052 * to complete within the specified timeframe:1053 *1054 * ```js1055 * test('plan with wait: 2000 waits for async assertions', (t) => {1056 * t.plan(1, { wait: 2000 }); // Waits for up to 2 seconds for the assertion to complete.1057 *1058 * const asyncActivity = () => {1059 * setTimeout(() => {1060 * * t.assert.ok(true, 'Async assertion completed within the wait time');1061 * }, 1000); // Completes after 1 second, within the 2-second wait time.1062 * };1063 *1064 * asyncActivity(); // The test will pass because the assertion is completed in time.1065 * });1066 * ```1067 *1068 * Note: If a `wait` timeout is specified, it begins counting down only after the test function finishes executing.1069 * @since v22.2.01070 */1071 plan(count: number, options?: TestContextPlanOptions): void;1072 /**1073 * If `shouldRunOnlyTests` is truthy, the test context will only run tests that1074 * have the `only` option set. Otherwise, all tests are run. If Node.js was not1075 * started with the `--test-only` command-line option, this function is a1076 * no-op.1077 *1078 * ```js1079 * test('top level test', (t) => {1080 * // The test context can be set to run subtests with the 'only' option.1081 * t.runOnly(true);1082 * return Promise.all([1083 * t.test('this subtest is now skipped'),1084 * t.test('this subtest is run', { only: true }),1085 * ]);1086 * });1087 * ```1088 * @since v18.0.0, v16.17.01089 * @param shouldRunOnlyTests Whether or not to run `only` tests.1090 */1091 runOnly(shouldRunOnlyTests: boolean): void;1092 /**1093 * ```js1094 * test('top level test', async (t) => {1095 * await fetch('some/uri', { signal: t.signal });1096 * });1097 * ```1098 * @since v18.7.0, v16.17.01099 */1100 readonly signal: AbortSignal;1101 /**1102 * 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()` does1103 * not terminate execution of the test function. This function does not return a1104 * value.1105 *1106 * ```js1107 * test('top level test', (t) => {1108 * // Make sure to return here as well if the test contains additional logic.1109 * t.skip('this is skipped');1110 * });1111 * ```1112 * @since v18.0.0, v16.17.01113 * @param message Optional skip message.1114 */1115 skip(message?: string): void;1116 /**1117 * This function adds a `TODO` directive to the test's output. If `message` is1118 * provided, it is included in the output. Calling `todo()` does not terminate1119 * execution of the test function. This function does not return a value.1120 *1121 * ```js1122 * test('top level test', (t) => {1123 * // This test is marked as `TODO`1124 * t.todo('this is a todo');1125 * });1126 * ```1127 * @since v18.0.0, v16.17.01128 * @param message Optional `TODO` message.1129 */1130 todo(message?: string): void;1131 /**1132 * This function is used to create subtests under the current test. This function behaves in1133 * the same fashion as the top level {@link test} function.1134 * @since v18.0.01135 * @param name The name of the test, which is displayed when reporting test results.1136 * Defaults to the `name` property of `fn`, or `'<anonymous>'` if `fn` does not have a name.1137 * @param options Configuration options for the test.1138 * @param fn The function under test. This first argument to this function is a {@link TestContext} object.1139 * If the test uses callbacks, the callback function is passed as the second argument.1140 * @returns A {@link Promise} resolved with `undefined` once the test completes.1141 */1142 test: typeof test;1143 /**1144 * This method polls a `condition` function until that function either returns1145 * successfully or the operation times out.1146 * @since v22.14.01147 * @param condition An assertion function that is invoked1148 * periodically until it completes successfully or the defined polling timeout1149 * elapses. Successful completion is defined as not throwing or rejecting. This1150 * function does not accept any arguments, and is allowed to return any value.1151 * @param options An optional configuration object for the polling operation.1152 * @returns Fulfilled with the value returned by `condition`.1153 */1154 waitFor<T>(condition: () => T, options?: TestContextWaitForOptions): Promise<Awaited<T>>;1155 /**1156 * Each test provides its own MockTracker instance.1157 */1158 readonly mock: MockTracker;1159 }1160 interface TestContextAssert extends1161 Pick<1162 typeof import("assert"),1163 | "deepEqual"1164 | "deepStrictEqual"1165 | "doesNotMatch"1166 | "doesNotReject"1167 | "doesNotThrow"1168 | "equal"1169 | "fail"1170 | "ifError"1171 | "match"1172 | "notDeepEqual"1173 | "notDeepStrictEqual"1174 | "notEqual"1175 | "notStrictEqual"1176 | "ok"1177 | "partialDeepStrictEqual"1178 | "rejects"1179 | "strictEqual"1180 | "throws"1181 >1182 {1183 /**1184 * This function serializes `value` and writes it to the file specified by `path`.1185 *1186 * ```js1187 * test('snapshot test with default serialization', (t) => {1188 * t.assert.fileSnapshot({ value1: 1, value2: 2 }, './snapshots/snapshot.json');1189 * });1190 * ```1191 *1192 * This function differs from `context.assert.snapshot()` in the following ways:1193 *1194 * * The snapshot file path is explicitly provided by the user.1195 * * Each snapshot file is limited to a single snapshot value.1196 * * No additional escaping is performed by the test runner.1197 *1198 * These differences allow snapshot files to better support features such as syntax1199 * highlighting.1200 * @since v22.14.0