test.d.ts (8459B)
1 /** 2 * The `node:test` module provides a standalone testing module. 3 * @see [source](https://github.com/nodejs/node/blob/v16.17.0/lib/test.js) 4 */ 5 declare module "node:test" { 6 /** 7 * The `test()` function is the value imported from the test module. Each invocation of this 8 * function results in the creation of a test point in the TAP output. 9 * 10 * The {@link TestContext} object passed to the fn argument can be used to perform actions 11 * related to the current test. Examples include skipping the test, adding additional TAP 12 * diagnostic information, or creating subtests. 13 * 14 * `test()` returns a {@link Promise} that resolves once the test completes. The return value 15 * can usually be discarded for top level tests. However, the return value from subtests should 16 * be used to prevent the parent test from finishing first and cancelling the subtest as shown 17 * in the following example. 18 * 19 * ```js 20 * test('top level test', async (t) => { 21 * // The setTimeout() in the following subtest would cause it to outlive its 22 * // parent test if 'await' is removed on the next line. Once the parent test 23 * // completes, it will cancel any outstanding subtests. 24 * await t.test('longer running subtest', async (t) => { 25 * return new Promise((resolve, reject) => { 26 * setTimeout(resolve, 1000); 27 * }); 28 * }); 29 * }); 30 * ``` 31 * @since v16.17.0 32 * @param name The name of the test, which is displayed when reporting test results. 33 * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name. 34 * @param options Configuration options for the test 35 * @param fn The function under test. The first argument to this function is a 36 * {@link TestContext} object. If the test uses callbacks, the callback function is 37 * passed as the second argument. Default: A no-op function. 38 * @returns A {@link Promise} resolved with `undefined` once the test completes. 39 */ 40 function test(name?: string, fn?: TestFn): Promise<void>; 41 function test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>; 42 function test(options?: TestOptions, fn?: TestFn): Promise<void>; 43 function test(fn?: TestFn): Promise<void>; 44 45 /* 46 * @since v16.17.0 47 * @param name The name of the suite, which is displayed when reporting suite results. 48 * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name. 49 * @param options Configuration options for the suite 50 * @param fn The function under suite. Default: A no-op function. 51 */ 52 function describe(name?: string, options?: TestOptions, fn?: SuiteFn): void; 53 function describe(name?: string, fn?: SuiteFn): void; 54 function describe(options?: TestOptions, fn?: SuiteFn): void; 55 function describe(fn?: SuiteFn): void; 56 57 /* 58 * @since v16.17.0 59 * @param name The name of the test, which is displayed when reporting test results. 60 * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name. 61 * @param options Configuration options for the test 62 * @param fn The function under test. If the test uses callbacks, the callback function is 63 * passed as the second argument. Default: A no-op function. 64 */ 65 function it(name?: string, options?: TestOptions, fn?: ItFn): void; 66 function it(name?: string, fn?: ItFn): void; 67 function it(options?: TestOptions, fn?: ItFn): void; 68 function it(fn?: ItFn): void; 69 70 /** 71 * The type of a function under test. The first argument to this function is a 72 * {@link TestContext} object. If the test uses callbacks, the callback function is passed as 73 * the second argument. 74 */ 75 type TestFn = (t: TestContext, done: (result?: any) => void) => any; 76 77 /** 78 * The type of a function under Suite. 79 * If the test uses callbacks, the callback function is passed as an argument 80 */ 81 type SuiteFn = (done: (result?: any) => void) => void; 82 83 /** 84 * The type of a function under test. 85 * If the test uses callbacks, the callback function is passed as an argument 86 */ 87 type ItFn = (done: (result?: any) => void) => any; 88 89 /** 90 * An instance of `TestContext` is passed to each test function in order to interact with the 91 * test runner. However, the `TestContext` constructor is not exposed as part of the API. 92 * @since v16.17.0 93 */ 94 interface TestContext { 95 /** 96 * This function is used to write TAP diagnostics to the output. Any diagnostic information is 97 * included at the end of the test's results. This function does not return a value. 98 * @param message Message to be displayed as a TAP diagnostic. 99 * @since v16.17.0 100 */ 101 diagnostic(message: string): void; 102 103 /** 104 * If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only` 105 * option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only` 106 * command-line option, this function is a no-op. 107 * @param shouldRunOnlyTests Whether or not to run `only` tests. 108 * @since v16.17.0 109 */ 110 runOnly(shouldRunOnlyTests: boolean): void; 111 112 /** 113 * This function causes the test's output to indicate the test as skipped. If `message` is 114 * provided, it is included in the TAP output. Calling `skip()` does not terminate execution of 115 * the test function. This function does not return a value. 116 * @param message Optional skip message to be displayed in TAP output. 117 * @since v16.17.0 118 */ 119 skip(message?: string): void; 120 121 /** 122 * This function adds a `TODO` directive to the test's output. If `message` is provided, it is 123 * included in the TAP output. Calling `todo()` does not terminate execution of the test 124 * function. This function does not return a value. 125 * @param message Optional `TODO` message to be displayed in TAP output. 126 * @since v16.17.0 127 */ 128 todo(message?: string): void; 129 130 /** 131 * This function is used to create subtests under the current test. This function behaves in 132 * the same fashion as the top level {@link test} function. 133 * @since v16.17.0 134 * @param name The name of the test, which is displayed when reporting test results. 135 * Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name. 136 * @param options Configuration options for the test 137 * @param fn The function under test. This first argument to this function is a 138 * {@link TestContext} object. If the test uses callbacks, the callback function is 139 * passed as the second argument. Default: A no-op function. 140 * @returns A {@link Promise} resolved with `undefined` once the test completes. 141 */ 142 test: typeof test; 143 } 144 145 interface TestOptions { 146 /** 147 * The number of tests that can be run at the same time. If unspecified, subtests inherit this 148 * value from their parent. 149 * @default 1 150 */ 151 concurrency?: number; 152 153 /** 154 * If truthy, and the test context is configured to run `only` tests, then this test will be 155 * run. Otherwise, the test is skipped. 156 * @default false 157 */ 158 only?: boolean; 159 160 /** 161 * Allows aborting an in-progress test. 162 * @since v16.17.0 163 */ 164 signal?: AbortSignal; 165 166 /** 167 * If truthy, the test is skipped. If a string is provided, that string is displayed in the 168 * test results as the reason for skipping the test. 169 * @default false 170 */ 171 skip?: boolean | string; 172 173 /** 174 * A number of milliseconds the test will fail after. If unspecified, subtests inherit this 175 * value from their parent. 176 * @default Infinity 177 * @since v16.17.0 178 */ 179 timeout?: number; 180 181 /** 182 * If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in 183 * the test results as the reason why the test is `TODO`. 184 * @default false 185 */ 186 todo?: boolean | string; 187 } 188 189 export { describe, it, test, test as default, TestContext }; 190 }