Skip to content

update types for node node:test 18.6.0 #61353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
typescript-bot merged 6 commits into from
Jul 24, 2022
Merged

update types for node node:test 18.6.0 #61353

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
b7ecad0
node: update `node:test` types for node 18.6.0
MoLow Jul 20, 2022
2a161ba
fix: tests and lint
MoLow Jul 20, 2022
45a3293
fix
MoLow Jul 20, 2022
ffe69f2
Merge branch 'DefinitelyTyped:master' into update-node-test-types
MoLow Jul 20, 2022
63a8663
Fix broken tests
MoLow Jul 20, 2022
deb374c
Merge remote-tracking branch 'origin/master' into update-node-test-types
MoLow Jul 23, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion types/node/index.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Type definitions for non-npm package Node.js 18.0
// Type definitions for non-npm package Node.js 18.6
// Project: https://nodejs.org/
// Definitions by: Microsoft TypeScript <https://github.com/Microsoft>
// DefinitelyTyped <https://github.com/DefinitelyTyped>
Expand Down
258 changes: 146 additions & 112 deletions types/node/test.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,140 +3,174 @@
* @see [source](https://github.com/nodejs/node/blob/v18.0.0/lib/test.js)
*/
declare module 'node:test' {
/**
* The `test()` function is the value imported from the test module. Each invocation of this
* function results in the creation of a test point in the TAP output.
*
* The {@link TestContext} object passed to the fn argument can be used to perform actions
* related to the current test. Examples include skipping the test, adding additional TAP
* diagnostic information, or creating subtests.
*
* `test()` returns a {@link Promise} that resolves once the test completes. The return value
* can usually be discarded for top level tests. However, the return value from subtests should
* be used to prevent the parent test from finishing first and cancelling the subtest as shown
* in the following example.
*
* ```js
* test('top level test', async (t) => {
* // The setTimeout() in the following subtest would cause it to outlive its
* // parent test if 'await' is removed on the next line. Once the parent test
* // completes, it will cancel any outstanding subtests.
* await t.test('longer running subtest', async (t) => {
* return new Promise((resolve, reject) => {
* setTimeout(resolve, 1000);
* });
* });
* });
* ```
* @since v18.0.0
* @param name The name of the test, which is displayed when reporting test results.
* Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
* @param options Configuration options for the test
* @param fn The function under test. This first argument to this function is a
* {@link TestContext} object. If the test uses callbacks, the callback function is
* passed as the second argument. Default: A no-op function.
* @returns A {@link Promise} resolved with `undefined` once the test completes.
*/
function test(name?: string, fn?: TestFn): Promise<void>;
function test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
function test(options?: TestOptions, fn?: TestFn): Promise<void>;
function test(fn?: TestFn): Promise<void>;

/**
* The type of a function under test. This first argument to this function is a
* {@link TestContext} object. If the test uses callbacks, the callback function is passed as
* the second argument.
*/
type TestFn = ((t: TestContext, done: (result?: any) => void) => any);

/**
* An instance of `TestContext` is passed to each test function in order to interact with the
* test runner. However, the `TestContext` constructor is not exposed as part of the API.
* @since v18.0.0
*/
interface TestContext {
/**
* This function is used to write TAP diagnostics to the output. Any diagnostic information is
* included at the end of the test's results. This function does not return a value.
* @param message Message to be displayed as a TAP diagnostic.
* @since v18.0.0
*/
diagnostic(message: string): void;

/**
* If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only`
* option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only`
* command-line option, this function is a no-op.
* @param shouldRunOnlyTests Whether or not to run `only` tests.
* @since v18.0.0
*/
runOnly(shouldRunOnlyTests: boolean): void;

/**
* This function causes the test's output to indicate the test as skipped. If `message` is
* provided, it is included in the TAP output. Calling `skip()` does not terminate execution of
* the test function. This function does not return a value.
* @param message Optional skip message to be displayed in TAP output.
* The `test()` function is the value imported from the test module. Each invocation of this
* function results in the creation of a test point in the TAP output.
*
* The {@link TestContext} object passed to the fn argument can be used to perform actions
* related to the current test. Examples include skipping the test, adding additional TAP
* diagnostic information, or creating subtests.
*
* `test()` returns a {@link Promise} that resolves once the test completes. The return value
* can usually be discarded for top level tests. However, the return value from subtests should
* be used to prevent the parent test from finishing first and cancelling the subtest as shown
* in the following example.
*
* ```js
* test('top level test', async (t) => {
* // The setTimeout() in the following subtest would cause it to outlive its
* // parent test if 'await' is removed on the next line. Once the parent test
* // completes, it will cancel any outstanding subtests.
* await t.test('longer running subtest', async (t) => {
* return new Promise((resolve, reject) => {
* setTimeout(resolve, 1000);
* });
* });
* });
* ```
* @since v18.0.0
* @param name The name of the test, which is displayed when reporting test results.
* Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
* @param options Configuration options for the test
* @param fn The function under test. The first argument to this function is a
* {@link TestContext} object. If the test uses callbacks, the callback function is
* passed as the second argument. Default: A no-op function.
* @returns A {@link Promise} resolved with `undefined` once the test completes.
*/
skip(message?: string): void;
function test(name?: string, fn?: TestFn): Promise<void>;
function test(name?: string, options?: TestOptions, fn?: TestFn): Promise<void>;
function test(options?: TestOptions, fn?: TestFn): Promise<void>;
function test(fn?: TestFn): Promise<void>;

/**
* This function adds a `TODO` directive to the test's output. If `message` is provided, it is
* included in the TAP output. Calling `todo()` does not terminate execution of the test
* function. This function does not return a value.
* @param message Optional `TODO` message to be displayed in TAP output.
* @since v18.0.0
/*
* @since v18.6.0
* @param name The name of the suite, which is displayed when reporting suite results.
* Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
* @param options Configuration options for the suite
* @param fn The function under suite. Default: A no-op function.
*/
todo(message?: string): void;
function describe(name?: string, options?: TestOptions, fn?: SuiteFn): void;
function describe(name?: string, fn?: SuiteFn): void;
function describe(options?: TestOptions, fn?: SuiteFn): void;
function describe(fn?: SuiteFn): void;

/**
* This function is used to create subtests under the current test. This function behaves in
* the same fashion as the top level {@link test} function.
* @since v18.0.0
/*
* @since v18.6.0
* @param name The name of the test, which is displayed when reporting test results.
* Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
* @param options Configuration options for the test
* @param fn The function under test. This first argument to this function is a
* {@link TestContext} object. If the test uses callbacks, the callback function is
* @param fn The function under test. If the test uses callbacks, the callback function is
* passed as the second argument. Default: A no-op function.
* @returns A {@link Promise} resolved with `undefined` once the test completes.
*/
test: typeof test;
}
function it(name?: string, options?: TestOptions, fn?: ItFn): void;
function it(name?: string, fn?: ItFn): void;
function it(options?: TestOptions, fn?: ItFn): void;
function it(fn?: ItFn): void;

interface TestOptions {
/**
* The number of tests that can be run at the same time. If unspecified, subtests inherit this
* value from their parent.
* @default 1
* The type of a function under test. The first argument to this function is a
* {@link TestContext} object. If the test uses callbacks, the callback function is passed as
* the second argument.
*/
concurrency?: number;
type TestFn = (t: TestContext, done: (result?: any) => void) => any;

/**
* If truthy, and the test context is configured to run `only` tests, then this test will be
* run. Otherwise, the test is skipped.
* @default false
* The type of a function under Suite.
* If the test uses callbacks, the callback function is passed as an argument
*/
only?: boolean;
type SuiteFn = (done: (result?: any) => void) => void;

/**
* If truthy, the test is skipped. If a string is provided, that string is displayed in the
* test results as the reason for skipping the test.
* @default false
* The type of a function under test.
* If the test uses callbacks, the callback function is passed as an argument
*/
skip?: boolean | string;
type ItFn = (done: (result?: any) => void) => any;

/**
* If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in
* the test results as the reason why the test is `TODO`.
* @default false
* An instance of `TestContext` is passed to each test function in order to interact with the
* test runner. However, the `TestContext` constructor is not exposed as part of the API.
* @since v18.0.0
*/
todo?: boolean | string;
}
interface TestContext {
/**
* This function is used to write TAP diagnostics to the output. Any diagnostic information is
* included at the end of the test's results. This function does not return a value.
* @param message Message to be displayed as a TAP diagnostic.
* @since v18.0.0
*/
diagnostic(message: string): void;

/**
* If `shouldRunOnlyTests` is truthy, the test context will only run tests that have the `only`
* option set. Otherwise, all tests are run. If Node.js was not started with the `--test-only`
* command-line option, this function is a no-op.
* @param shouldRunOnlyTests Whether or not to run `only` tests.
* @since v18.0.0
*/
runOnly(shouldRunOnlyTests: boolean): void;

/**
* This function causes the test's output to indicate the test as skipped. If `message` is
* provided, it is included in the TAP output. Calling `skip()` does not terminate execution of
* the test function. This function does not return a value.
* @param message Optional skip message to be displayed in TAP output.
* @since v18.0.0
*/
skip(message?: string): void;

/**
* This function adds a `TODO` directive to the test's output. If `message` is provided, it is
* included in the TAP output. Calling `todo()` does not terminate execution of the test
* function. This function does not return a value.
* @param message Optional `TODO` message to be displayed in TAP output.
* @since v18.0.0
*/
todo(message?: string): void;

/**
* This function is used to create subtests under the current test. This function behaves in
* the same fashion as the top level {@link test} function.
* @since v18.0.0
* @param name The name of the test, which is displayed when reporting test results.
* Default: The `name` property of fn, or `'<anonymous>'` if `fn` does not have a name.
* @param options Configuration options for the test
* @param fn The function under test. This first argument to this function is a
* {@link TestContext} object. If the test uses callbacks, the callback function is
* passed as the second argument. Default: A no-op function.
* @returns A {@link Promise} resolved with `undefined` once the test completes.
*/
test: typeof test;
}

interface TestOptions {
/**
* The number of tests that can be run at the same time. If unspecified, subtests inherit this
* value from their parent.
* @default 1
*/
concurrency?: number;

/**
* If truthy, and the test context is configured to run `only` tests, then this test will be
* run. Otherwise, the test is skipped.
* @default false
*/
only?: boolean;

/**
* If truthy, the test is skipped. If a string is provided, that string is displayed in the
* test results as the reason for skipping the test.
* @default false
*/
skip?: boolean | string;

/**
* If truthy, the test marked as `TODO`. If a string is provided, that string is displayed in
* the test results as the reason why the test is `TODO`.
* @default false
*/
todo?: boolean | string;
}

export {
test as default,
test,
};
export { test as default, test, describe, it };
}
Loading