- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
Node.js v18.20.0 文档
- Node.js v18.20.0
-
目录
- 测试运行器
- 子测试
- 跳过测试
describe
/it
语法only
测试- 按名称过滤测试
- 无关的异步活动
- 监视模式
- 从命令行运行测试
- 收集代码覆盖率
- 模拟
- 测试报告器
run([options])
test([name][, options][, fn])
test.skip([name][, options][, fn])
test.todo([name][, options][, fn])
test.only([name][, options][, fn])
describe([name][, options][, fn])
describe.skip([name][, options][, fn])
describe.todo([name][, options][, fn])
describe.only([name][, options][, fn])
it([name][, options][, fn])
it.skip([name][, options][, fn])
it.todo([name][, options][, fn])
it.only([name][, options][, fn])
before([fn][, options])
after([fn][, options])
beforeEach([fn][, options])
afterEach([fn][, options])
- 类:
MockFunctionContext
- 类:
MockTracker
- 类:
MockTimers
- 类:
TestsStream
- 类:
TestContext
context.before([fn][, options])
context.beforeEach([fn][, options])
context.after([fn][, options])
context.afterEach([fn][, options])
context.diagnostic(message)
context.name
context.runOnly(shouldRunOnlyTests)
context.signal
context.skip([message])
context.todo([message])
context.test([name][, options][, fn])
- 类:
SuiteContext
- 测试运行器
-
导航
- assert 断言
- async_hooks 异步钩子
- async_hooks/context 异步上下文
- buffer 缓冲区
- C++插件
- C/C++插件(使用 Node-API)
- C++嵌入器
- child_process 子进程
- cluster 集群
- CLI 命令行
- console 控制台
- Corepack 核心包
- crypto 加密
- crypto/webcrypto 网络加密
- debugger 调试器
- deprecation 弃用
- dgram 数据报
- diagnostics_channel 诊断通道
- dns 域名服务器
- domain 域
- Error 错误
- events 事件触发器
- fs 文件系统
- global 全局变量
- http 超文本传输协议
- http2 超文本传输协议 2.0
- https 安全超文本传输协议
- inspector 检查器
- Intl 国际化
- module 模块
- module/cjs CommonJS 模块
- module/esm ECMAScript 模块
- module/package 包模块
- net 网络
- os 操作系统
- path 路径
- perf_hooks 性能钩子
- permission 权限
- process 进程
- punycode 域名代码
- querystring 查询字符串
- readline 逐行读取
- repl 交互式解释器
- report 诊断报告
- sea 单个可执行应用程序
- stream 流
- stream/web 网络流
- string_decoder 字符串解码器
- test 测试
- timers 定时器
- tls 安全传输层
- trace_events 跟踪事件
- tty 终端
- url 网址
- util 实用工具
- v8 引擎
- vm 虚拟机
- wasi 网络汇编系统接口
- worker_threads 工作线程
- zlib 压缩
- 其他版本
测试运行器#
¥Test runner
¥Stability: 1 - Experimental
源代码: lib/test.js
node:test
模块有助于创建 JavaScript 测试。要访问它:
¥The node:test
module facilitates the creation of JavaScript tests.
To access it:
import test from 'node:test';
const test = require('node:test');
此模块仅在 node:
协议下可用。以下将不起作用:
¥This module is only available under the node:
scheme. The following will not
work:
import test from 'test';
const test = require('test');
通过 test
模块创建的测试由单个函数组成,该函数以三种方式之一进行处理:
¥Tests created via the test
module consist of a single function that is
processed in one of three ways:
-
同步的函数,如果抛出异常则认为失败,否则认为通过。
¥A synchronous function that is considered failing if it throws an exception, and is considered passing otherwise.
-
返回
Promise
的函数,如果Promise
拒绝,则认为该函数失败,如果Promise
解决,则认为该函数通过。¥A function that returns a
Promise
that is considered failing if thePromise
rejects, and is considered passing if thePromise
resolves. -
接收回调函数的函数。如果回调接收到任何真值作为其第一个参数,则认为测试失败。如果非真值作为第一个参数传给回调,则认为测试通过。如果测试函数接收到回调函数并且还返回
Promise
,则测试将失败。¥A function that receives a callback function. If the callback receives any truthy value as its first argument, the test is considered failing. If a falsy value is passed as the first argument to the callback, the test is considered passing. If the test function receives a callback function and also returns a
Promise
, the test will fail.
以下示例说明了如何使用 test
模块编写测试。
¥The following example illustrates how tests are written using the
test
module.
test('synchronous passing test', (t) => {
// This test passes because it does not throw an exception.
assert.strictEqual(1, 1);
});
test('synchronous failing test', (t) => {
// This test fails because it throws an exception.
assert.strictEqual(1, 2);
});
test('asynchronous passing test', async (t) => {
// This test passes because the Promise returned by the async
// function is not rejected.
assert.strictEqual(1, 1);
});
test('asynchronous failing test', async (t) => {
// This test fails because the Promise returned by the async
// function is rejected.
assert.strictEqual(1, 2);
});
test('failing test using Promises', (t) => {
// Promises can be used directly as well.
return new Promise((resolve, reject) => {
setImmediate(() => {
reject(new Error('this will cause the test to fail'));
});
});
});
test('callback passing test', (t, done) => {
// done() is the callback function. When the setImmediate() runs, it invokes
// done() with no arguments.
setImmediate(done);
});
test('callback failing test', (t, done) => {
// When the setImmediate() runs, done() is invoked with an Error object and
// the test fails.
setImmediate(() => {
done(new Error('callback failure'));
});
});
如果任何测试失败,则进程退出代码设置为 1
。
¥If any tests fail, the process exit code is set to 1
.
子测试#
¥Subtests
测试上下文的 test()
方法允许创建子测试。此方法的行为与顶层 test()
函数相同。以下示例演示了如何创建具有两个子测试的顶层测试。
¥The test context's test()
method allows subtests to be created. This method
behaves identically to the top level test()
function. The following example
demonstrates the creation of a top level test with two subtests.
test('top level test', async (t) => {
await t.test('subtest 1', (t) => {
assert.strictEqual(1, 1);
});
await t.test('subtest 2', (t) => {
assert.strictEqual(2, 2);
});
});
在本示例中,await
用于确保两个子测试均已完成。这是必要的,因为父测试不会等待子测试完成。当父测试完成时仍然未完成的任何子测试将被取消并视为失败。任何子测试失败都会导致父测试失败。
¥In this example, await
is used to ensure that both subtests have completed.
This is necessary because parent tests do not wait for their subtests to
complete. Any subtests that are still outstanding when their parent finishes
are cancelled and treated as failures. Any subtest failures cause the parent
test to fail.
跳过测试#
¥Skipping tests
通过将 skip
选项传递给测试,或通过调用测试上下文的 skip()
方法,可以跳过单个测试,如下例所示。
¥Individual tests can be skipped by passing the skip
option to the test, or by
calling the test context's skip()
method as shown in the
following example.
// The skip option is used, but no message is provided.
test('skip option', { skip: true }, (t) => {
// This code is never executed.
});
// The skip option is used, and a message is provided.
test('skip option with message', { skip: 'this is skipped' }, (t) => {
// This code is never executed.
});
test('skip() method', (t) => {
// Make sure to return here as well if the test contains additional logic.
t.skip();
});
test('skip() method with message', (t) => {
// Make sure to return here as well if the test contains additional logic.
t.skip('this is skipped');
});
describe
/it
语法#
¥describe
/it
syntax
运行测试也可以使用 describe
来声明套件和 it
来声明测试。套件用于将相关测试组织和分组在一起。it
是 test()
的简写。
¥Running tests can also be done using describe
to declare a suite
and it
to declare a test.
A suite is used to organize and group related tests together.
it
is a shorthand for test()
.
describe('A thing', () => {
it('should work', () => {
assert.strictEqual(1, 1);
});
it('should be ok', () => {
assert.strictEqual(2, 2);
});
describe('a nested thing', () => {
it('should work', () => {
assert.strictEqual(3, 3);
});
});
});
describe
和 it
是从 node:test
模块导入的。
¥describe
and it
are imported from the node:test
module.
import { describe, it } from 'node:test';
const { describe, it } = require('node:test');
only
测试#
¥only
tests
如果 Node.js 使用 --test-only
命令行选项启动,则可以通过将 only
选项传给应该运行的测试来跳过除选定子集之外的所有顶层测试。当运行带有 only
选项集的测试时,所有子测试也会运行。测试上下文的 runOnly()
方法可用于在子测试级别实现相同的行为。
¥If Node.js is started with the --test-only
command-line option, it is
possible to skip all top level tests except for a selected subset by passing
the only
option to the tests that should be run. When a test with the only
option set is run, all subtests are also run. The test context's runOnly()
method can be used to implement the same behavior at the subtest level.
// Assume Node.js is run with the --test-only command-line option.
// The 'only' option is set, so this test is run.
test('this test is run', { only: true }, async (t) => {
// Within this test, all subtests are run by default.
await t.test('running subtest');
// The test context can be updated to run subtests with the 'only' option.
t.runOnly(true);
await t.test('this subtest is now skipped');
await t.test('this subtest is run', { only: true });
// Switch the context back to execute all tests.
t.runOnly(false);
await t.test('this subtest is now run');
// Explicitly do not run these tests.
await t.test('skipped subtest 3', { only: false });
await t.test('skipped subtest 4', { skip: true });
});
// The 'only' option is not set, so this test is skipped.
test('this test is not run', () => {
// This code is not run.
throw new Error('fail');
});
按名称过滤测试#
¥Filtering tests by name
--test-name-pattern
命令行选项可用于仅运行名称与提供的模式匹配的测试。测试名称模式被解释为 JavaScript 正则表达式。可以多次指定 --test-name-pattern
选项以运行嵌套测试。对于执行的每个测试,也会运行任何相应的测试钩子,例如 beforeEach()
。
¥The --test-name-pattern
command-line option can be used to only run tests
whose name matches the provided pattern. Test name patterns are interpreted as
JavaScript regular expressions. The --test-name-pattern
option can be
specified multiple times in order to run nested tests. For each test that is
executed, any corresponding test hooks, such as beforeEach()
, are also
run.
给定以下测试文件,使用 --test-name-pattern="test [1-3]"
选项启动 Node.js 将导致测试运行程序执行 test 1
、test 2
和 test 3
。如果 test 1
不匹配测试名称模式,那么它的子测试将不会执行,尽管匹配模式。同一组测试也可以通过多次传递 --test-name-pattern
来执行(例如 --test-name-pattern="test 1"
、--test-name-pattern="test 2"
等)。
¥Given the following test file, starting Node.js with the
--test-name-pattern="test [1-3]"
option would cause the test runner to execute
test 1
, test 2
, and test 3
. If test 1
did not match the test name
pattern, then its subtests would not execute, despite matching the pattern. The
same set of tests could also be executed by passing --test-name-pattern
multiple times (e.g. --test-name-pattern="test 1"
,
--test-name-pattern="test 2"
, etc.).
test('test 1', async (t) => {
await t.test('test 2');
await t.test('test 3');
});
test('Test 4', async (t) => {
await t.test('Test 5');
await t.test('test 6');
});
也可以使用正则表达式字面指定测试名称模式。这允许使用正则表达式标志。在前面的示例中,以 --test-name-pattern="/test [4-5]/i"
开头的 Node.js 将匹配 Test 4
和 Test 5
,因为该模式不区分大小写。
¥Test name patterns can also be specified using regular expression literals. This
allows regular expression flags to be used. In the previous example, starting
Node.js with --test-name-pattern="/test [4-5]/i"
would match Test 4
and
Test 5
because the pattern is case-insensitive.
测试名称模式不会更改测试运行程序执行的文件集。
¥Test name patterns do not change the set of files that the test runner executes.
无关的异步活动#
¥Extraneous asynchronous activity
一旦测试函数完成执行,将在保持测试顺序的同时尽快报告结果。但是,测试函数可能会生成比测试本身寿命更长的异步活动。测试运行器处理此类活动,但不会延迟报告测试结果以适应它。
¥Once a test function finishes executing, the results are reported as quickly as possible while maintaining the order of the tests. However, it is possible for the test function to generate asynchronous activity that outlives the test itself. The test runner handles this type of activity, but does not delay the reporting of test results in order to accommodate it.
在下面的示例中,测试完成时仍然有两个 setImmediate()
操作未完成。第一个 setImmediate()
尝试创建新的子测试。因为父测试已经完成并输出结果,所以新的子测试立即标记为失败,稍后报告给 <TestsStream>。
¥In the following example, a test completes with two setImmediate()
operations still outstanding. The first setImmediate()
attempts to create a
new subtest. Because the parent test has already finished and output its
results, the new subtest is immediately marked as failed, and reported later
to the <TestsStream>.
第二个 setImmediate()
创建了 uncaughtException
事件。源自已完成测试的 uncaughtException
和 unhandledRejection
事件被 test
模块标记为失败,并由 <TestsStream> 在顶层报告为诊断警告。
¥The second setImmediate()
creates an uncaughtException
event.
uncaughtException
and unhandledRejection
events originating from a completed
test are marked as failed by the test
module and reported as diagnostic
warnings at the top level by the <TestsStream>.
test('a test that creates asynchronous activity', (t) => {
setImmediate(() => {
t.test('subtest that is created too late', (t) => {
throw new Error('error1');
});
});
setImmediate(() => {
throw new Error('error2');
});
// The test finishes after this line.
});
监视模式#
¥Watch mode
¥Stability: 1 - Experimental
Node.js 测试运行器支持通过传递 --watch
标志以监视模式运行:
¥The Node.js test runner supports running in watch mode by passing the --watch
flag:
node --test --watch
在监视模式下,测试运行器将监视测试文件及其依赖的更改。当检测到变化时,测试运行器将重新运行受变化影响的测试。测试运行器将继续运行直到进程终止。
¥In watch mode, the test runner will watch for changes to test files and their dependencies. When a change is detected, the test runner will rerun the tests affected by the change. The test runner will continue to run until the process is terminated.
从命令行运行测试#
¥Running tests from the command line
可以通过传入 --test
标志从命令行调用 Node.js 测试运行程序:
¥The Node.js test runner can be invoked from the command line by passing the
--test
flag:
node --test
默认情况下,Node.js 将递归搜索当前目录以查找匹配特定命名约定的 JavaScript 源文件。匹配文件作为测试文件执行。有关预期测试文件命名约定和行为的更多信息,请参见 测试运行器执行模型 部分。
¥By default, Node.js will recursively search the current directory for JavaScript source files matching a specific naming convention. Matching files are executed as test files. More information on the expected test file naming convention and behavior can be found in the test runner execution model section.
或者,可以提供一个或多个路径作为 Node.js 命令的最终参数,如下所示。
¥Alternatively, one or more paths can be provided as the final argument(s) to the Node.js command, as shown below.
node --test test1.js test2.mjs custom_test_dir/
在本例中,测试运行程序将执行文件 test1.js
和 test2.mjs
。测试运行器还将递归搜索 custom_test_dir/
目录以查找要执行的测试文件。
¥In this example, the test runner will execute the files test1.js
and
test2.mjs
. The test runner will also recursively search the
custom_test_dir/
directory for test files to execute.
测试运行器执行模型#
¥Test runner execution model
当搜索要执行的测试文件时,测试运行器的行为如下:
¥When searching for test files to execute, the test runner behaves as follows:
-
执行用户显式提供的任何文件。
¥Any files explicitly provided by the user are executed.
-
如果用户没有显式地指定任何路径,则递归搜索当前工作目录中指定的文件,如以下步骤所示。
¥If the user did not explicitly specify any paths, the current working directory is recursively searched for files as specified in the following steps.
-
除非用户显式地提供,否则跳过
node_modules
目录。¥
node_modules
directories are skipped unless explicitly provided by the user. -
如果遇到名为
test
的目录,则测试运行程序将递归搜索所有.js
、.cjs
和.mjs
文件。所有这些文件都被视为测试文件,不需要匹配下面详述的特定命名约定。这是为了适应将所有测试放在单个test
目录中的项目。¥If a directory named
test
is encountered, the test runner will search it recursively for all all.js
,.cjs
, and.mjs
files. All of these files are treated as test files, and do not need to match the specific naming convention detailed below. This is to accommodate projects that place all of their tests in a singletest
directory. -
在所有其他目录中,匹配以下模式的
.js
、.cjs
和.mjs
文件被视为测试文件:¥In all other directories,
.js
,.cjs
, and.mjs
files matching the following patterns are treated as test files:-
^test$
- 基本名称为字符串'test'
的文件。示例:test.js
,test.cjs
,test.mjs
.¥
^test$
- Files whose basename is the string'test'
. Examples:test.js
,test.cjs
,test.mjs
. -
^test-.+
- 基本名称以字符串'test-'
后跟一个或多个字符开头的文件。示例:test-example.js
,test-another-example.mjs
.¥
^test-.+
- Files whose basename starts with the string'test-'
followed by one or more characters. Examples:test-example.js
,test-another-example.mjs
. -
.+[\.\-\_]test$
- 基本名称以.test
、-test
或_test
结尾且前面有一个或多个字符的文件。示例:example.test.js
,example-test.cjs
,example_test.mjs
.¥
.+[\.\-\_]test$
- Files whose basename ends with.test
,-test
, or_test
, preceded by one or more characters. Examples:example.test.js
,example-test.cjs
,example_test.mjs
. -
Node.js 理解的其他文件类型,例如
.node
和.json
,不会由测试运行程序自动执行,但如果在命令行上显式地提供,则支持。¥Other file types understood by Node.js such as
.node
and.json
are not automatically executed by the test runner, but are supported if explicitly provided on the command line.
-
每个匹配的测试文件都在单独的子进程中执行。任何时候运行的子进程的最大数量由 --test-concurrency
标志控制。如果子进程以退出代码 0 结束,则认为测试通过。否则,认为测试失败。测试文件必须是 Node.js 可执行文件,但不需要在内部使用 node:test
模块。
¥Each matching test file is executed in a separate child process. The maximum
number of child processes running at any time is controlled by the
--test-concurrency
flag. If the child process finishes with an exit code
of 0, the test is considered passing. Otherwise, the test is considered to be a
failure. Test files must be executable by Node.js, but are not required to use
the node:test
module internally.
每个测试文件都像常规脚本一样执行。也就是说,如果测试文件本身使用 node:test
来定义测试,则所有这些测试都将在单个应用线程中执行,而不管 test()
的 concurrency
选项的值如何。
¥Each test file is executed as if it was a regular script. That is, if the test
file itself uses node:test
to define tests, all of those tests will be
executed within a single application thread, regardless of the value of the
concurrency
option of test()
.
收集代码覆盖率#
¥Collecting code coverage
当 Node.js 以 --experimental-test-coverage
命令行标志启动时,代码覆盖率将被收集并在所有测试完成后报告统计信息。如果使用 NODE_V8_COVERAGE
环境变量指定代码覆盖目录,则生成的 V8 覆盖文件写入该目录。node_modules/
目录中的 Node.js 核心模块和文件未包含在覆盖率报告中。如果启用覆盖,覆盖报告将通过 'test:coverage'
事件发送到任何 测试报告器。
¥When Node.js is started with the --experimental-test-coverage
command-line flag, code coverage is collected and statistics are reported once
all tests have completed. If the NODE_V8_COVERAGE
environment variable is
used to specify a code coverage directory, the generated V8 coverage files are
written to that directory. Node.js core modules and files within
node_modules/
directories are not included in the coverage report. If
coverage is enabled, the coverage report is sent to any test reporters via
the 'test:coverage'
event.
可以使用以下注释语法在一系列行上禁用覆盖:
¥Coverage can be disabled on a series of lines using the following comment syntax:
/* node:coverage disable */
if (anAlwaysFalseCondition) {
// Code in this branch will never be executed, but the lines are ignored for
// coverage purposes. All lines following the 'disable' comment are ignored
// until a corresponding 'enable' comment is encountered.
console.log('this is never executed');
}
/* node:coverage enable */
也可以针对指定行数禁用覆盖。在指定的行数之后,将自动重新启用覆盖。如果未明确提供行数,则忽略单行。
¥Coverage can also be disabled for a specified number of lines. After the specified number of lines, coverage will be automatically reenabled. If the number of lines is not explicitly provided, a single line is ignored.
/* node:coverage ignore next */
if (anAlwaysFalseCondition) { console.log('this is never executed'); }
/* node:coverage ignore next 3 */
if (anAlwaysFalseCondition) {
console.log('this is never executed');
}
测试运行器的代码覆盖功能有以下限制,将在未来的 Node.js 版本中解决:
¥The test runner's code coverage functionality has the following limitations, which will be addressed in a future Node.js release:
-
不支持源映射。
¥Source maps are not supported.
-
不支持从覆盖率报告中排除特定文件或目录。
¥Excluding specific files or directories from the coverage report is not supported.
模拟#
¥Mocking
node:test
模块支持通过顶层 mock
对象在测试期间进行模拟。以下示例创建了一个对将两个数字相加的函数的监视。间谍随后被用来断言该函数已按预期调用。
¥The node:test
module supports mocking during testing via a top-level mock
object. The following example creates a spy on a function that adds two numbers
together. The spy is then used to assert that the function was called as
expected.
import assert from 'node:assert';
import { mock, test } from 'node:test';
test('spies on a function', () => {
const sum = mock.fn((a, b) => {
return a + b;
});
assert.strictEqual(sum.mock.calls.length, 0);
assert.strictEqual(sum(3, 4), 7);
assert.strictEqual(sum.mock.calls.length, 1);
const call = sum.mock.calls[0];
assert.deepStrictEqual(call.arguments, [3, 4]);
assert.strictEqual(call.result, 7);
assert.strictEqual(call.error, undefined);
// Reset the globally tracked mocks.
mock.reset();
});
'use strict';
const assert = require('node:assert');
const { mock, test } = require('node:test');
test('spies on a function', () => {
const sum = mock.fn((a, b) => {
return a + b;
});
assert.strictEqual(sum.mock.calls.length, 0);
assert.strictEqual(sum(3, 4), 7);
assert.strictEqual(sum.mock.calls.length, 1);
const call = sum.mock.calls[0];
assert.deepStrictEqual(call.arguments, [3, 4]);
assert.strictEqual(call.result, 7);
assert.strictEqual(call.error, undefined);
// Reset the globally tracked mocks.
mock.reset();
});
相同的模拟功能也暴露在每个测试的 TestContext
对象上。以下示例使用 TestContext
上公开的 API 创建对象方法的监听器。通过测试上下文进行模拟的好处是,测试运行器将在测试完成后自动恢复所有模拟功能。
¥The same mocking functionality is also exposed on the TestContext
object
of each test. The following example creates a spy on an object method using the
API exposed on the TestContext
. The benefit of mocking via the test context is
that the test runner will automatically restore all mocked functionality once
the test finishes.
test('spies on an object method', (t) => {
const number = {
value: 5,
add(a) {
return this.value + a;
},
};
t.mock.method(number, 'add');
assert.strictEqual(number.add.mock.calls.length, 0);
assert.strictEqual(number.add(3), 8);
assert.strictEqual(number.add.mock.calls.length, 1);
const call = number.add.mock.calls[0];
assert.deepStrictEqual(call.arguments, [3]);
assert.strictEqual(call.result, 8);
assert.strictEqual(call.target, undefined);
assert.strictEqual(call.this, number);
});
定时器#
¥Timers
模拟定时器是软件测试中常用的一种技术,用于模拟和控制定时器(例如 setInterval
和 setTimeout
)的行为,而无需实际等待指定的时间间隔。
¥Mocking timers is a technique commonly used in software testing to simulate and
control the behavior of timers, such as setInterval
and setTimeout
,
without actually waiting for the specified time intervals.
有关方法和功能的完整列表,请参阅 MockTimers
类。
¥Refer to the MockTimers
class for a full list of methods and features.
这使得开发者能够为时间相关的功能编写更可靠和可预测的测试。
¥This allows developers to write more reliable and predictable tests for time-dependent functionality.
下面的示例展示了如何模拟 setTimeout
。使用 .enable(['setTimeout']);
它将模拟 node:timers 和 node:timers/promises 模块以及 Node.js 全局上下文中的 setTimeout
函数。
¥The example below shows how to mock setTimeout
.
Using .enable(['setTimeout']);
it will mock the setTimeout
functions in the node:timers and
node:timers/promises modules,
as well as from the Node.js global context.
注意:该 API 目前不支持 import { setTimeout } from 'node:timers'
等解构函数。
¥Note: Destructuring functions such as
import { setTimeout } from 'node:timers'
is currently not supported by this API.
import assert from 'node:assert';
import { mock, test } from 'node:test';
test('mocks setTimeout to be executed synchronously without having to actually wait for it', () => {
const fn = mock.fn();
// Optionally choose what to mock
mock.timers.enable(['setTimeout']);
setTimeout(fn, 9999);
assert.strictEqual(fn.mock.callCount(), 0);
// Advance in time
mock.timers.tick(9999);
assert.strictEqual(fn.mock.callCount(), 1);
// Reset the globally tracked mocks.
mock.timers.reset();
// If you call reset mock instance, it will also reset timers instance
mock.reset();
});
const assert = require('node:assert');
const { mock, test } = require('node:test');
test('mocks setTimeout to be executed synchronously without having to actually wait for it', () => {
const fn = mock.fn();
// Optionally choose what to mock
mock.timers.enable(['setTimeout']);
setTimeout(fn, 9999);
assert.strictEqual(fn.mock.callCount(), 0);
// Advance in time
mock.timers.tick(9999);
assert.strictEqual(fn.mock.callCount(), 1);
// Reset the globally tracked mocks.
mock.timers.reset();
// If you call reset mock instance, it'll also reset timers instance
mock.reset();
});
每个测试的 TestContext
对象的模拟属性中也公开了相同的模拟功能。通过测试上下文进行模拟的好处是,一旦测试完成,测试运行器将自动恢复所有模拟的定时器功能。
¥The same mocking functionality is also exposed in the mock property on the TestContext
object
of each test. The benefit of mocking via the test context is
that the test runner will automatically restore all mocked timers
functionality once the test finishes.
import assert from 'node:assert';
import { test } from 'node:test';
test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
const fn = context.mock.fn();
// Optionally choose what to mock
context.mock.timers.enable(['setTimeout']);
setTimeout(fn, 9999);
assert.strictEqual(fn.mock.callCount(), 0);
// Advance in time
context.mock.timers.tick(9999);
assert.strictEqual(fn.mock.callCount(), 1);
});
const assert = require('node:assert');
const { test } = require('node:test');
test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
const fn = context.mock.fn();
// Optionally choose what to mock
context.mock.timers.enable(['setTimeout']);
setTimeout(fn, 9999);
assert.strictEqual(fn.mock.callCount(), 0);
// Advance in time
context.mock.timers.tick(9999);
assert.strictEqual(fn.mock.callCount(), 1);
});
测试报告器#
¥Test reporters
node:test
模块支持传递 --test-reporter
标志,以便测试运行器使用特定的报告程序。
¥The node:test
module supports passing --test-reporter
flags for the test runner to use a specific reporter.
支持以下内置报告器:
¥The following built-reporters are supported:
-
tap
tap
报告器以 TAP 格式输出测试结果。¥
tap
Thetap
reporter outputs the test results in the TAP format. -
spec
spec
报告器以人类可读的格式输出测试结果。¥
spec
Thespec
reporter outputs the test results in a human-readable format. -
dot
dot
报告器以紧凑格式输出测试结果,其中每个通过的测试用.
表示,每个失败的测试用X
表示。¥
dot
Thedot
reporter outputs the test results in a compact format, where each passing test is represented by a.
, and each failing test is represented by aX
. -
junit
junit 报告器以 jUnit XML 格式输出测试结果¥
junit
The junit reporter outputs test results in a jUnit XML format
当 stdout
为 TTY 时,默认使用 spec
报告器。否则,默认使用 tap
报告器。
¥When stdout
is a TTY, the spec
reporter is used by default.
Otherwise, the tap
reporter is used by default.
报告器可通过 node:test/reporters
模块获得:
¥The reporters are available via the node:test/reporters
module:
import { tap, spec, dot, junit } from 'node:test/reporters';
const { tap, spec, dot, junit } = require('node:test/reporters');
自定义报告器#
¥Custom reporters
--test-reporter
可用于指定自定义报告程序的路径。自定义报告器是一个导出 stream.compose 接受的值的模块。报告者应该转换 <TestsStream> 触发的事件
¥--test-reporter
can be used to specify a path to custom reporter.
A custom reporter is a module that exports a value
accepted by stream.compose.
Reporters should transform events emitted by a <TestsStream>
使用 <stream.Transform> 的自定义报告器示例:
¥Example of a custom reporter using <stream.Transform>:
import { Transform } from 'node:stream';
const customReporter = new Transform({
writableObjectMode: true,
transform(event, encoding, callback) {
switch (event.type) {
case 'test:dequeue':
callback(null, `test ${event.data.name} dequeued`);
break;
case 'test:enqueue':
callback(null, `test ${event.data.name} enqueued`);
break;
case 'test:watch:drained':
callback(null, 'test watch queue drained');
break;
case 'test:start':
callback(null, `test ${event.data.name} started`);
break;
case 'test:pass':
callback(null, `test ${event.data.name} passed`);
break;
case 'test:fail':
callback(null, `test ${event.data.name} failed`);
break;
case 'test:plan':
callback(null, 'test plan');
break;
case 'test:diagnostic':
case 'test:stderr':
case 'test:stdout':
callback(null, event.data.message);
break;
case 'test:coverage': {
const { totalLineCount } = event.data.summary.totals;
callback(null, `total line count: ${totalLineCount}\n`);
break;
}
}
},
});
export default customReporter;
const { Transform } = require('node:stream');
const customReporter = new Transform({
writableObjectMode: true,
transform(event, encoding, callback) {
switch (event.type) {
case 'test:dequeue':
callback(null, `test ${event.data.name} dequeued`);
break;
case 'test:enqueue':
callback(null, `test ${event.data.name} enqueued`);
break;
case 'test:watch:drained':
callback(null, 'test watch queue drained');
break;
case 'test:start':
callback(null, `test ${event.data.name} started`);
break;
case 'test:pass':
callback(null, `test ${event.data.name} passed`);
break;
case 'test:fail':
callback(null, `test ${event.data.name} failed`);
break;
case 'test:plan':
callback(null, 'test plan');
break;
case 'test:diagnostic':
case 'test:stderr':
case 'test:stdout':
callback(null, event.data.message);
break;
case 'test:coverage': {
const { totalLineCount } = event.data.summary.totals;
callback(null, `total line count: ${totalLineCount}\n`);
break;
}
}
},
});
module.exports = customReporter;
使用生成器函数的自定义报告器示例:
¥Example of a custom reporter using a generator function:
export default async function * customReporter(source) {
for await (const event of source) {
switch (event.type) {
case 'test:dequeue':
yield `test ${event.data.name} dequeued`;
break;
case 'test:enqueue':
yield `test ${event.data.name} enqueued`;
break;
case 'test:watch:drained':
yield 'test watch queue drained';
break;
case 'test:start':
yield `test ${event.data.name} started\n`;
break;
case 'test:pass':
yield `test ${event.data.name} passed\n`;
break;
case 'test:fail':
yield `test ${event.data.name} failed\n`;
break;
case 'test:plan':
yield 'test plan';
break;
case 'test:diagnostic':
case 'test:stderr':
case 'test:stdout':
yield `${event.data.message}\n`;
break;
case 'test:coverage': {
const { totalLineCount } = event.data.summary.totals;
yield `total line count: ${totalLineCount}\n`;
break;
}
}
}
}
module.exports = async function * customReporter(source) {
for await (const event of source) {
switch (event.type) {
case 'test:dequeue':
yield `test ${event.data.name} dequeued`;
break;
case 'test:enqueue':
yield `test ${event.data.name} enqueued`;
break;
case 'test:watch:drained':
yield 'test watch queue drained';
break;
case 'test:start':
yield `test ${event.data.name} started\n`;
break;
case 'test:pass':
yield `test ${event.data.name} passed\n`;
break;
case 'test:fail':
yield `test ${event.data.name} failed\n`;
break;
case 'test:plan':
yield 'test plan\n';
break;
case 'test:diagnostic':
case 'test:stderr':
case 'test:stdout':
yield `${event.data.message}\n`;
break;
case 'test:coverage': {
const { totalLineCount } = event.data.summary.totals;
yield `total line count: ${totalLineCount}\n`;
break;
}
}
}
};
提供给 --test-reporter
的值应该是一个字符串,就像在 JavaScript 代码中的 import()
中使用的那样。
¥The value provided to --test-reporter
should be a string like one used in an
import()
in JavaScript code.
多报告器#
¥Multiple reporters
可以多次指定 --test-reporter
标志,以多种格式报告测试结果。在这种情况下,需要使用 --test-reporter-destination
为每个报告者指定目标。目标可以是 stdout
、stderr
或文件路径。报告器和目标根据指定的顺序配对。
¥The --test-reporter
flag can be specified multiple times to report test
results in several formats. In this situation
it is required to specify a destination for each reporter
using --test-reporter-destination
.
Destination can be stdout
, stderr
, or a file path.
Reporters and destinations are paired according
to the order they were specified.
在下面的例子中,spec
报告器将输出到 stdout
,dot
报告器将输出到 file.txt
:
¥In the following example, the spec
reporter will output to stdout
,
and the dot
reporter will output to file.txt
:
node --test-reporter=spec --test-reporter=dot --test-reporter-destination=stdout --test-reporter-destination=file.txt
当指定单个报告者时,目标将默认为 stdout
,除非明确提供目标。
¥When a single reporter is specified, the destination will default to stdout
,
unless a destination is explicitly provided.
run([options])
#
-
options
<Object> 运行测试的配置选项。支持以下属性:¥
options
<Object> Configuration options for running tests. The following properties are supported:-
concurrency
<number> | <boolean> 如果提供了一个数字,那么许多测试进程将并行运行,其中每个进程对应一个测试文件。如果是true
,它将并行运行os.availableParallelism() - 1
个测试文件。如果是false
,它一次只会运行一个测试文件。默认值:false
。¥
concurrency
<number> | <boolean> If a number is provided, then that many test processes would run in parallel, where each process corresponds to one test file. Iftrue
, it would runos.availableParallelism() - 1
test files in parallel. Iffalse
, it would only run one test file at a time. Default:false
. -
files
:<Array> 包含要运行的文件列表的数组。测试运行器执行模型 中的默认匹配文件。¥
files
: <Array> An array containing the list of files to run. Default matching files from test runner execution model. -
inspectPort
<number> | <Function> 设置测试子进程的检查器端口。这可以是数字,也可以是不带参数并返回数字的函数。如果提供了一个空值,每个进程都有自己的端口,从主进程的process.debugPort
递增。默认值:undefined
。¥
inspectPort
<number> | <Function> Sets inspector port of test child process. This can be a number, or a function that takes no arguments and returns a number. If a nullish value is provided, each process gets its own port, incremented from the primary'sprocess.debugPort
. Default:undefined
. -
only
:<boolean> 如果为真,测试上下文将仅运行设置了only
选项的测试¥
only
: <boolean> If truthy, the test context will only run tests that have theonly
option set -
setup
<Function> 接受TestsStream
实例并可用于在运行任何测试之前设置监听器的函数。默认值:undefined
。¥
setup
<Function> A function that accepts theTestsStream
instance and can be used to setup listeners before any tests are run. Default:undefined
. -
signal
<AbortSignal> 允许中止正在进行的测试执行。¥
signal
<AbortSignal> Allows aborting an in-progress test execution. -
testNamePatterns
<string> | <RegExp> | <Array> 一个字符串、正则表达式或正则表达式数组,可用于仅运行名称与提供的模式匹配的测试。测试名称模式被解释为 JavaScript 正则表达式。对于执行的每个测试,也会运行任何相应的测试钩子,例如beforeEach()
。默认值:undefined
。¥
testNamePatterns
<string> | <RegExp> | <Array> A String, RegExp or a RegExp Array, that can be used to only run tests whose name matches the provided pattern. Test name patterns are interpreted as JavaScript regular expressions. For each test that is executed, any corresponding test hooks, such asbeforeEach()
, are also run. Default:undefined
. -
timeout
<number> 测试执行将在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the test execution will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
. -
watch
<boolean> 是否以监视模式运行。默认值:false
。¥
watch
<boolean> Whether to run in watch mode or not. Default:false
. -
shard
<Object> 在特定分片中运行测试。默认值:undefined
。¥
shard
<Object> Running tests in a specific shard. Default:undefined
.-
index
<number> 是 1 到<total>
之间的正整数,指定要运行的分片的索引。此选项是必需的。¥
index
<number> is a positive integer between 1 and<total>
that specifies the index of the shard to run. This option is required. -
total
<number> 是一个正整数,指定将测试文件拆分为的分片总数。此选项是必需的。¥
total
<number> is a positive integer that specifies the total number of shards to split the test files to. This option is required.
-
-
-
¥Returns: <TestsStream>
import { tap } from 'node:test/reporters';
import process from 'node:process';
run({ files: [path.resolve('./tests/test.js')] })
.compose(tap)
.pipe(process.stdout);
const { tap } = require('node:test/reporters');
run({ files: [path.resolve('./tests/test.js')] })
.compose(tap)
.pipe(process.stdout);
test([name][, options][, fn])
#
-
name
<string> 测试的名称,报告测试结果时显示。默认值:fn
的name
属性,如果fn
没有名称,则为'<anonymous>'
。¥
name
<string> The name of the test, which is displayed when reporting test results. Default: Thename
property offn
, or'<anonymous>'
iffn
does not have a name. -
options
<Object> 测试的配置选项。支持以下属性:¥
options
<Object> Configuration options for the test. The following properties are supported:-
concurrency
<number> | <boolean> 如果提供了一个数字,那么许多测试将在应用线程中并行运行。如果为true
,则所有计划的异步测试在线程内同时运行。如果是false
,一次只运行一个测试。如果未指定,则子测试从其父测试继承此值。默认值:false
。¥
concurrency
<number> | <boolean> If a number is provided, then that many tests would run in parallel within the application thread. Iftrue
, all scheduled asynchronous tests run concurrently within the thread. Iffalse
, only one test runs at a time. If unspecified, subtests inherit this value from their parent. Default:false
. -
only
<boolean> 如果为真,并且测试上下文配置为运行only
测试,则将运行此测试。否则跳过测试。默认值:false
。¥
only
<boolean> If truthy, and the test context is configured to runonly
tests, then this test will be run. Otherwise, the test is skipped. Default:false
. -
signal
<AbortSignal> 允许中止正在进行的测试。¥
signal
<AbortSignal> Allows aborting an in-progress test. -
skip
<boolean> | <string> 如果为真,则跳过测试。如果提供了字符串,则该字符串将作为跳过测试的原因显示在测试结果中。默认值:false
。¥
skip
<boolean> | <string> 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
. -
todo
<boolean> | <string> 如果为真,则测试标记为TODO
。如果提供了字符串,则该字符串会显示在测试结果中作为测试为TODO
的原因。默认值:false
。¥
todo
<boolean> | <string> If truthy, the test marked asTODO
. If a string is provided, that string is displayed in the test results as the reason why the test isTODO
. Default:false
. -
timeout
<number> 测试失败的毫秒数。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the test will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
-
fn
<Function> | <AsyncFunction> 被测试的函数。此函数的第一个参数是TestContext
对象。如果测试使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The function under test. The first argument to this function is aTestContext
object. If the test uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
返回:<Promise> 测试完成后使用
undefined
解决,或者如果测试在describe()
内运行则立即解决。¥Returns: <Promise> Resolved with
undefined
once the test completes, or immediately if the test runs withindescribe()
.
test()
函数是从 test
模块导入的值。每次调用此函数都会向 <TestsStream> 报告测试。
¥The test()
function is the value imported from the test
module. Each
invocation of this function results in reporting the test to the <TestsStream>.
传给 fn
参数的 TestContext
对象可用于执行与当前测试相关的操作。示例包括跳过测试、添加额外的诊断信息或创建子测试。
¥The 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 diagnostic information, or creating subtests.
test()
返回 Promise
,一旦测试完成就解决。如果在 describe()
块中调用 test()
,它会立即解析。返回值通常可以被顶层测试丢弃。但是,应该使用子测试的返回值来防止父测试先完成并取消子测试,如下例所示。
¥test()
returns a Promise
that resolves once the test completes.
if test()
is called within a describe()
block, it resolve immediately.
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.
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);
});
});
});
如果完成时间超过 timeout
毫秒,则可以使用 timeout
选项使测试失败。但是,它不是取消测试的可靠机制,因为正在运行的测试可能会阻塞应用线程,从而阻止预定的取消。
¥The timeout
option can be used to fail the test if it takes longer than
timeout
milliseconds to complete. However, it is not a reliable mechanism for
canceling tests because a running test might block the application thread and
thus prevent the scheduled cancellation.
test.skip([name][, options][, fn])
#
跳过测试的简写,与 test([name], { skip: true }[, fn])
相同。
¥Shorthand for skipping a test,
same as test([name], { skip: true }[, fn])
.
test.todo([name][, options][, fn])
#
将测试标记为 TODO
的简写,与 test([name], { todo: true }[, fn])
相同。
¥Shorthand for marking a test as TODO
,
same as test([name], { todo: true }[, fn])
.
test.only([name][, options][, fn])
#
将测试标记为 only
的简写,与 test([name], { only: true }[, fn])
相同。
¥Shorthand for marking a test as only
,
same as test([name], { only: true }[, fn])
.
describe([name][, options][, fn])
#
-
name
<string> 套件名称,报告测试结果时显示。默认值:fn
的name
属性,如果fn
没有名称,则为'<anonymous>'
。¥
name
<string> The name of the suite, which is displayed when reporting test results. Default: Thename
property offn
, or'<anonymous>'
iffn
does not have a name. -
options
<Object> 套件的配置选项。支持与test([name][, options][, fn])
相同的选项。¥
options
<Object> Configuration options for the suite. supports the same options astest([name][, options][, fn])
. -
fn
<Function> | <AsyncFunction> 套件下的函数声明所有子测试和子套件。此函数的第一个参数是SuiteContext
对象。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The function under suite declaring all subtests and subsuites. The first argument to this function is aSuiteContext
object. Default: A no-op function. -
返回:<Promise> 立即满足
undefined
。¥Returns: <Promise> Immediately fulfilled with
undefined
.
从 node:test
模块导入的 describe()
函数。每次调用此函数都会创建一个子测试。调用顶层 describe
函数后,所有顶层测试和套件都将执行。
¥The describe()
function imported from the node:test
module. Each
invocation of this function results in the creation of a Subtest.
After invocation of top level describe
functions,
all top level tests and suites will execute.
describe.skip([name][, options][, fn])
#
跳过套件的简写,与 describe([name], { skip: true }[, fn])
相同。
¥Shorthand for skipping a suite, same as describe([name], { skip: true }[, fn])
.
describe.todo([name][, options][, fn])
#
将套件标记为 TODO
的简写,与 describe([name], { todo: true }[, fn])
相同。
¥Shorthand for marking a suite as TODO
, same as
describe([name], { todo: true }[, fn])
.
describe.only([name][, options][, fn])
#
将套件标记为 only
的简写,与 describe([name], { only: true }[, fn])
相同。
¥Shorthand for marking a suite as only
, same as
describe([name], { only: true }[, fn])
.
it([name][, options][, fn])
#
test()
的简写。
¥Shorthand for test()
.
it()
函数是从 node:test
模块导入的。
¥The it()
function is imported from the node:test
module.
it.skip([name][, options][, fn])
#
跳过测试的简写,与 it([name], { skip: true }[, fn])
相同。
¥Shorthand for skipping a test,
same as it([name], { skip: true }[, fn])
.
it.todo([name][, options][, fn])
#
将测试标记为 TODO
的简写,与 it([name], { todo: true }[, fn])
相同。
¥Shorthand for marking a test as TODO
,
same as it([name], { todo: true }[, fn])
.
it.only([name][, options][, fn])
#
将测试标记为 only
的简写,与 it([name], { only: true }[, fn])
相同。
¥Shorthand for marking a test as only
,
same as it([name], { only: true }[, fn])
.
before([fn][, options])
#
-
fn
<Function> | <AsyncFunction> 钩子函数。如果钩子使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The hook function. If the hook uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
options
<Object> 钩子的配置选项。支持以下属性:¥
options
<Object> Configuration options for the hook. The following properties are supported:-
signal
<AbortSignal> 允许中止正在进行的钩子。¥
signal
<AbortSignal> Allows aborting an in-progress hook. -
timeout
<number> 钩子会在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the hook will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
此函数用于在运行套件之前创建一个钩子运行。
¥This function is used to create a hook running before running a suite.
describe('tests', async () => {
before(() => console.log('about to run some test'));
it('is a subtest', () => {
assert.ok('some relevant assertion here');
});
});
after([fn][, options])
#
-
fn
<Function> | <AsyncFunction> 钩子函数。如果钩子使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The hook function. If the hook uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
options
<Object> 钩子的配置选项。支持以下属性:¥
options
<Object> Configuration options for the hook. The following properties are supported:-
signal
<AbortSignal> 允许中止正在进行的钩子。¥
signal
<AbortSignal> Allows aborting an in-progress hook. -
timeout
<number> 钩子会在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the hook will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
该函数用于创建一个在运行套件后运行的钩子。
¥This function is used to create a hook running after running a suite.
describe('tests', async () => {
after(() => console.log('finished running tests'));
it('is a subtest', () => {
assert.ok('some relevant assertion here');
});
});
beforeEach([fn][, options])
#
-
fn
<Function> | <AsyncFunction> 钩子函数。如果钩子使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The hook function. If the hook uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
options
<Object> 钩子的配置选项。支持以下属性:¥
options
<Object> Configuration options for the hook. The following properties are supported:-
signal
<AbortSignal> 允许中止正在进行的钩子。¥
signal
<AbortSignal> Allows aborting an in-progress hook. -
timeout
<number> 钩子会在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the hook will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
此函数用于创建一个在当前套件的每个子测试之前运行的钩子。
¥This function is used to create a hook running before each subtest of the current suite.
describe('tests', async () => {
beforeEach(() => console.log('about to run a test'));
it('is a subtest', () => {
assert.ok('some relevant assertion here');
});
});
afterEach([fn][, options])
#
-
fn
<Function> | <AsyncFunction> 钩子函数。如果钩子使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The hook function. If the hook uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
options
<Object> 钩子的配置选项。支持以下属性:¥
options
<Object> Configuration options for the hook. The following properties are supported:-
signal
<AbortSignal> 允许中止正在进行的钩子。¥
signal
<AbortSignal> Allows aborting an in-progress hook. -
timeout
<number> 钩子会在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the hook will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
此函数用于创建一个在当前测试的每个子测试之后运行的钩子。
¥This function is used to create a hook running after each subtest of the current test.
describe('tests', async () => {
afterEach(() => console.log('finished running a test'));
it('is a subtest', () => {
assert.ok('some relevant assertion here');
});
});
类:MockFunctionContext
#
¥Class: MockFunctionContext
MockFunctionContext
类用于检查或操纵通过 MockTracker
API 创建的模拟的行为。
¥The MockFunctionContext
class is used to inspect or manipulate the behavior of
mocks created via the MockTracker
APIs.
ctx.calls
#
返回用于跟踪模拟调用的内部数组副本的获取器。数组中的每个条目都是一个具有以下属性的对象。
¥A getter that returns a copy of the internal array used to track calls to the mock. Each entry in the array is an object with the following properties.
-
arguments
<Array> 传递给模拟函数的参数数组。¥
arguments
<Array> An array of the arguments passed to the mock function. -
error
<any> 如果模拟函数抛出,则此属性包含抛出的值。默认值:undefined
。¥
error
<any> If the mocked function threw then this property contains the thrown value. Default:undefined
. -
result
<any> 模拟函数返回的值。¥
result
<any> The value returned by the mocked function. -
stack
<Error> 一个Error
对象,其堆栈可用于确定模拟函数调用的调用点。¥
stack
<Error> AnError
object whose stack can be used to determine the callsite of the mocked function invocation. -
target
<Function> | <undefined> 如果模拟函数是构造函数,则此字段包含正在构造的类。否则这将是undefined
。¥
target
<Function> | <undefined> If the mocked function is a constructor, this field contains the class being constructed. Otherwise this will beundefined
. -
this
<any> 模拟函数的this
值。¥
this
<any> The mocked function'sthis
value.
ctx.callCount()
#
此函数返回此模拟已被调用的次数。此函数比检查 ctx.calls.length
更有效,因为 ctx.calls
是创建内部调用跟踪数组副本的获取器。
¥This function returns the number of times that this mock has been invoked. This
function is more efficient than checking ctx.calls.length
because ctx.calls
is a getter that creates a copy of the internal call tracking array.
ctx.mockImplementation(implementation)
#
-
implementation
<Function> | <AsyncFunction> 要用作模拟的新实现的函数。¥
implementation
<Function> | <AsyncFunction> The function to be used as the mock's new implementation.
此函数用于更改现有模拟的行为。
¥This function is used to change the behavior of an existing mock.
以下示例使用 t.mock.fn()
创建模拟函数,调用模拟函数,然后将模拟实现更改为不同的函数。
¥The following example creates a mock function using t.mock.fn()
, calls the
mock function, and then changes the mock implementation to a different function.
test('changes a mock behavior', (t) => {
let cnt = 0;
function addOne() {
cnt++;
return cnt;
}
function addTwo() {
cnt += 2;
return cnt;
}
const fn = t.mock.fn(addOne);
assert.strictEqual(fn(), 1);
fn.mock.mockImplementation(addTwo);
assert.strictEqual(fn(), 3);
assert.strictEqual(fn(), 5);
});
ctx.mockImplementationOnce(implementation[, onCall])
#
-
implementation
<Function> | <AsyncFunction> 要用作onCall
指定的调用编号的模拟实现的函数。¥
implementation
<Function> | <AsyncFunction> The function to be used as the mock's implementation for the invocation number specified byonCall
. -
onCall
<integer> 将使用implementation
的调用编号。如果指定的调用已经发生,则抛出异常。默认值:下一次调用的次数。¥
onCall
<integer> The invocation number that will useimplementation
. If the specified invocation has already occurred then an exception is thrown. Default: The number of the next invocation.
此函数用于更改单个调用的现有模拟的行为。一旦调用 onCall
发生,模拟将恢复到没有调用 mockImplementationOnce()
时它会使用的任何行为。
¥This function is used to change the behavior of an existing mock for a single
invocation. Once invocation onCall
has occurred, the mock will revert to
whatever behavior it would have used had mockImplementationOnce()
not been
called.
以下示例使用 t.mock.fn()
创建模拟函数,调用模拟函数,将模拟实现更改为下一次调用的不同函数,然后恢复其先前的行为。
¥The following example creates a mock function using t.mock.fn()
, calls the
mock function, changes the mock implementation to a different function for the
next invocation, and then resumes its previous behavior.
test('changes a mock behavior once', (t) => {
let cnt = 0;
function addOne() {
cnt++;
return cnt;
}
function addTwo() {
cnt += 2;
return cnt;
}
const fn = t.mock.fn(addOne);
assert.strictEqual(fn(), 1);
fn.mock.mockImplementationOnce(addTwo);
assert.strictEqual(fn(), 3);
assert.strictEqual(fn(), 4);
});
ctx.resetCalls()
#
重置模拟函数的调用历史。
¥Resets the call history of the mock function.
ctx.restore()
#
将模拟函数的实现重置为其原始行为。调用此函数后仍然可以使用模拟。
¥Resets the implementation of the mock function to its original behavior. The mock can still be used after calling this function.
类:MockTracker
#
¥Class: MockTracker
MockTracker
类用于管理模拟功能。测试运行器模块提供了一个顶层 mock
导出,它是一个 MockTracker
实例。每个测试还通过测试上下文的 mock
属性提供自己的 MockTracker
实例。
¥The MockTracker
class is used to manage mocking functionality. The test runner
module provides a top level mock
export which is a MockTracker
instance.
Each test also provides its own MockTracker
instance via the test context's
mock
property.
mock.fn([original[, implementation]][, options])
#
-
original
<Function> | <AsyncFunction> 创建模拟的可选函数。默认值:空操作函数。¥
original
<Function> | <AsyncFunction> An optional function to create a mock on. Default: A no-op function. -
implementation
<Function> | <AsyncFunction> 用作original
的模拟实现的可选函数。这对于创建针对指定次数的调用表现出一种行为然后恢复original
的行为的模拟非常有用。默认值:original
指定的函数。¥
implementation
<Function> | <AsyncFunction> An optional function used as the mock implementation fororiginal
. This is useful for creating mocks that exhibit one behavior for a specified number of calls and then restore the behavior oforiginal
. Default: The function specified byoriginal
. -
options
<Object> 模拟功能的可选配置选项。支持以下属性:¥
options
<Object> Optional configuration options for the mock function. The following properties are supported:-
times
<integer> 模拟将使用implementation
的行为的次数。一旦模拟函数被调用了times
次,它会自动恢复original
的行为。此值必须是大于零的整数。默认值:Infinity
。¥
times
<integer> The number of times that the mock will use the behavior ofimplementation
. Once the mock function has been calledtimes
times, it will automatically restore the behavior oforiginal
. This value must be an integer greater than zero. Default:Infinity
.
-
-
返回:<Proxy> 模拟函数。模拟函数包含一个特殊的
mock
属性,它是MockFunctionContext
的一个实例,可用于检查和更改模拟函数的行为。¥Returns: <Proxy> The mocked function. The mocked function contains a special
mock
property, which is an instance ofMockFunctionContext
, and can be used for inspecting and changing the behavior of the mocked function.
此函数用于创建模拟函数。
¥This function is used to create a mock function.
以下示例创建了一个模拟函数,每次调用时计数器都会递增 1。times
选项用于修改模拟行为,以便前两次调用将两个而不是一个添加到计数器。
¥The following example creates a mock function that increments a counter by one
on each invocation. The times
option is used to modify the mock behavior such
that the first two invocations add two to the counter instead of one.
test('mocks a counting function', (t) => {
let cnt = 0;
function addOne() {
cnt++;
return cnt;
}
function addTwo() {
cnt += 2;
return cnt;
}
const fn = t.mock.fn(addOne, addTwo, { times: 2 });
assert.strictEqual(fn(), 2);
assert.strictEqual(fn(), 4);
assert.strictEqual(fn(), 5);
assert.strictEqual(fn(), 6);
});
mock.getter(object, methodName[, implementation][, options])
#
此函数是 MockTracker.method
的语法糖,options.getter
设置为 true
。
¥This function is syntax sugar for MockTracker.method
with options.getter
set to true
.
mock.method(object, methodName[, implementation][, options])
#
-
object
<Object> 其方法被模拟的对象。¥
object
<Object> The object whose method is being mocked. -
methodName
<string> | <symbol> 要模拟的object
上的方法的标识符。如果object[methodName]
不是函数,则会抛出错误。¥
methodName
<string> | <symbol> The identifier of the method onobject
to mock. Ifobject[methodName]
is not a function, an error is thrown. -
implementation
<Function> | <AsyncFunction> 用作object[methodName]
的模拟实现的可选函数。默认值:object[methodName]
指定的原始方法。¥
implementation
<Function> | <AsyncFunction> An optional function used as the mock implementation forobject[methodName]
. Default: The original method specified byobject[methodName]
. -
options
<Object> 模拟方法的可选配置选项。支持以下属性:¥
options
<Object> Optional configuration options for the mock method. The following properties are supported:-
getter
<boolean> 如果为true
,object[methodName]
被当作获取器。此选项不能与setter
选项一起使用。默认值:false。¥
getter
<boolean> Iftrue
,object[methodName]
is treated as a getter. This option cannot be used with thesetter
option. Default: false. -
setter
<boolean> 如果为true
,object[methodName]
被视为设置器。此选项不能与getter
选项一起使用。默认值:false。¥
setter
<boolean> Iftrue
,object[methodName]
is treated as a setter. This option cannot be used with thegetter
option. Default: false. -
times
<integer> 模拟将使用implementation
的行为的次数。一旦被模拟的方法被调用了times
次,它会自动恢复原来的行为。此值必须是大于零的整数。默认值:Infinity
。¥
times
<integer> The number of times that the mock will use the behavior ofimplementation
. Once the mocked method has been calledtimes
times, it will automatically restore the original behavior. This value must be an integer greater than zero. Default:Infinity
.
-
-
返回:<Proxy> 被模拟的方法。模拟方法包含一个特殊的
mock
属性,它是MockFunctionContext
的实例,可用于检查和更改模拟方法的行为。¥Returns: <Proxy> The mocked method. The mocked method contains a special
mock
property, which is an instance ofMockFunctionContext
, and can be used for inspecting and changing the behavior of the mocked method.
此函数用于在现有对象方法上创建模拟。以下示例演示了如何在现有对象方法上创建模拟。
¥This function is used to create a mock on an existing object method. The following example demonstrates how a mock is created on an existing object method.
test('spies on an object method', (t) => {
const number = {
value: 5,
subtract(a) {
return this.value - a;
},
};
t.mock.method(number, 'subtract');
assert.strictEqual(number.subtract.mock.calls.length, 0);
assert.strictEqual(number.subtract(3), 2);
assert.strictEqual(number.subtract.mock.calls.length, 1);
const call = number.subtract.mock.calls[0];
assert.deepStrictEqual(call.arguments, [3]);
assert.strictEqual(call.result, 2);
assert.strictEqual(call.error, undefined);
assert.strictEqual(call.target, undefined);
assert.strictEqual(call.this, number);
});
mock.reset()
#
此函数恢复了此 MockTracker
之前创建的所有模拟的默认行为,并解除了模拟与 MockTracker
实例的关联。一旦解除关联,模拟仍然可以使用,但 MockTracker
实例不能再用于重置它们的行为或以其他方式与它们交互。
¥This function restores the default behavior of all mocks that were previously
created by this MockTracker
and disassociates the mocks from the
MockTracker
instance. Once disassociated, the mocks can still be used, but the
MockTracker
instance can no longer be used to reset their behavior or
otherwise interact with them.
每次测试完成后,都会在测试上下文的 MockTracker
上调用此函数。如果广泛使用全局 MockTracker
,建议手动调用该函数。
¥After each test completes, this function is called on the test context's
MockTracker
. If the global MockTracker
is used extensively, calling this
function manually is recommended.
mock.restoreAll()
#
此函数恢复此 MockTracker
之前创建的所有模拟的默认行为。与 mock.reset()
不同,mock.restoreAll()
不会取消模拟与 MockTracker
实例的关联。
¥This function restores the default behavior of all mocks that were previously
created by this MockTracker
. Unlike mock.reset()
, mock.restoreAll()
does
not disassociate the mocks from the MockTracker
instance.
mock.setter(object, methodName[, implementation][, options])
#
此函数是 MockTracker.method
的语法糖,options.setter
设置为 true
。
¥This function is syntax sugar for MockTracker.method
with options.setter
set to true
.
类:MockTimers
#
¥Class: MockTimers
¥Stability: 1 - Experimental
模拟定时器是软件测试中常用的一种技术,用于模拟和控制定时器(例如 setInterval
和 setTimeout
)的行为,而无需实际等待指定的时间间隔。
¥Mocking timers is a technique commonly used in software testing to simulate and
control the behavior of timers, such as setInterval
and setTimeout
,
without actually waiting for the specified time intervals.
MockTracker
提供顶层 timers
导出,它是 MockTimers
实例。
¥The MockTracker
provides a top-level timers
export
which is a MockTimers
instance.
timers.enable([timers])
#
启用指定定时器的定时器模拟。
¥Enables timer mocking for the specified timers.
-
timers
<Array> 包含要模拟的定时器的可选数组。当前支持的定时器值为'setInterval'
、'setTimeout'
和'setImmediate'
。如果未提供值,则默认情况下将模拟所有定时器('setInterval'
、'clearInterval'
、'setTimeout'
、'clearTimeout'
、'setImmediate'
和'clearImmediate'
)。¥
timers
<Array> An optional array containing the timers to mock. The currently supported timer values are'setInterval'
,'setTimeout'
, and'setImmediate'
. If no value is provided, all timers ('setInterval'
,'clearInterval'
,'setTimeout'
,'clearTimeout'
,'setImmediate'
, and'clearImmediate'
) will be mocked by default.
注意:当你为特定定时器启用模拟时,其关联的清除函数也将被隐式模拟。
¥Note: When you enable mocking for a specific timer, its associated clear function will also be implicitly mocked.
用法示例:
¥Example usage:
import { mock } from 'node:test';
mock.timers.enable(['setInterval']);
const { mock } = require('node:test');
mock.timers.enable(['setInterval']);
上面的示例启用了对 setInterval
定时器的模拟,并隐式模拟了 clearInterval
函数。仅 node:timers、node:timers/promises 和 globalThis
中的 setInterval
和 clearInterval
函数将被模拟。
¥The above example enables mocking for the setInterval
timer and
implicitly mocks the clearInterval
function. Only the setInterval
and clearInterval
functions from node:timers,
node:timers/promises, and
globalThis
will be mocked.
或者,如果你调用 mock.timers.enable()
时不带任何参数:
¥Alternatively, if you call mock.timers.enable()
without any parameters:
所有定时器('setInterval'
、'clearInterval'
、'setTimeout'
和 'clearTimeout'
)都将被模拟。node:timers
、node:timers/promises
和 globalThis
中的 setInterval
、clearInterval
、setTimeout
和 clearTimeout
函数将被模拟。
¥All timers ('setInterval'
, 'clearInterval'
, 'setTimeout'
, and 'clearTimeout'
)
will be mocked. The setInterval
, clearInterval
, setTimeout
, and clearTimeout
functions from node:timers
, node:timers/promises
,
and globalThis
will be mocked.
timers.reset()
#
此函数恢复此 MockTimers
实例之前创建的所有模拟的默认行为,并取消这些模拟与 MockTracker
实例的关联。
¥This function restores the default behavior of all mocks that were previously
created by this MockTimers
instance and disassociates the mocks
from the MockTracker
instance.
注意:每次测试完成后,都会在测试上下文的 MockTracker
上调用此函数。
¥Note: After each test completes, this function is called on
the test context's MockTracker
.
import { mock } from 'node:test';
mock.timers.reset();
const { mock } = require('node:test');
mock.timers.reset();
timers[Symbol.dispose]()
#
调用 timers.reset()
。
¥Calls timers.reset()
.
timers.tick(milliseconds)
#
提前所有模拟定时器的时间。
¥Advances time for all mocked timers.
-
milliseconds
<number> 定时器提前的时间量(以毫秒为单位)。¥
milliseconds
<number> The amount of time, in milliseconds, to advance the timers.
注意:这与 Node.js 中 setTimeout
的行为不同,它只接受正数。在 Node.js 中,仅出于 Web 兼容性原因才支持带有负数的 setTimeout
。
¥Note: This diverges from how setTimeout
in Node.js behaves and accepts
only positive numbers. In Node.js, setTimeout
with negative numbers is
only supported for web compatibility reasons.
以下示例模拟 setTimeout
函数,并通过使用 .tick
时间提前来触发所有挂起的定时器。
¥The following example mocks a setTimeout
function and
by using .tick
advances in
time triggering all pending timers.
import assert from 'node:assert';
import { test } from 'node:test';
test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
const fn = context.mock.fn();
context.mock.timers.enable(['setTimeout']);
setTimeout(fn, 9999);
assert.strictEqual(fn.mock.callCount(), 0);
// Advance in time
context.mock.timers.tick(9999);
assert.strictEqual(fn.mock.callCount(), 1);
});
const assert = require('node:assert');
const { test } = require('node:test');
test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
const fn = context.mock.fn();
context.mock.timers.enable(['setTimeout']);
setTimeout(fn, 9999);
assert.strictEqual(fn.mock.callCount(), 0);
// Advance in time
context.mock.timers.tick(9999);
assert.strictEqual(fn.mock.callCount(), 1);
});
或者,.tick
函数可以被调用多次
¥Alternativelly, the .tick
function can be called many times
import assert from 'node:assert';
import { test } from 'node:test';
test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
const fn = context.mock.fn();
context.mock.timers.enable(['setTimeout']);
const nineSecs = 9000;
setTimeout(fn, nineSecs);
const twoSeconds = 3000;
context.mock.timers.tick(twoSeconds);
context.mock.timers.tick(twoSeconds);
context.mock.timers.tick(twoSeconds);
assert.strictEqual(fn.mock.callCount(), 1);
});
const assert = require('node:assert');
const { test } = require('node:test');
test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
const fn = context.mock.fn();
context.mock.timers.enable(['setTimeout']);
const nineSecs = 9000;
setTimeout(fn, nineSecs);
const twoSeconds = 3000;
context.mock.timers.tick(twoSeconds);
context.mock.timers.tick(twoSeconds);
context.mock.timers.tick(twoSeconds);
assert.strictEqual(fn.mock.callCount(), 1);
});
使用明确的函数#
¥Using clear functions
如前所述,定时器(clearTimeout
和 clearInterval
)中的所有清除函数都被隐式模拟。看一下使用 setTimeout
的示例:
¥As mentioned, all clear functions from timers (clearTimeout
and clearInterval
)
are implicity mocked. Take a look at this example using setTimeout
:
import assert from 'node:assert';
import { test } from 'node:test';
test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
const fn = context.mock.fn();
// Optionally choose what to mock
context.mock.timers.enable(['setTimeout']);
const id = setTimeout(fn, 9999);
// Implicity mocked as well
clearTimeout(id);
context.mock.timers.tick(9999);
// As that setTimeout was cleared the mock function will never be called
assert.strictEqual(fn.mock.callCount(), 0);
});
const assert = require('node:assert');
const { test } = require('node:test');
test('mocks setTimeout to be executed synchronously without having to actually wait for it', (context) => {
const fn = context.mock.fn();
// Optionally choose what to mock
context.mock.timers.enable(['setTimeout']);
const id = setTimeout(fn, 9999);
// Implicity mocked as well
clearTimeout(id);
context.mock.timers.tick(9999);
// As that setTimeout was cleared the mock function will never be called
assert.strictEqual(fn.mock.callCount(), 0);
});
使用 Node.js 定时器模块#
¥Working with Node.js timers modules
启用模拟定时器后,就会启用 Node.js 全局上下文中的 node:timers、node:timers/promises 模块和定时器:
¥Once you enable mocking timers, node:timers, node:timers/promises modules, and timers from the Node.js global context are enabled:
注意:该 API 目前不支持 import { setTimeout } from 'node:timers'
等解构函数。
¥Note: Destructuring functions such as
import { setTimeout } from 'node:timers'
is currently
not supported by this API.
import assert from 'node:assert';
import { test } from 'node:test';
import nodeTimers from 'node:timers';
import nodeTimersPromises from 'node:timers/promises';
test('mocks setTimeout to be executed synchronously without having to actually wait for it', async (context) => {
const globalTimeoutObjectSpy = context.mock.fn();
const nodeTimerSpy = context.mock.fn();
const nodeTimerPromiseSpy = context.mock.fn();
// Optionally choose what to mock
context.mock.timers.enable(['setTimeout']);
setTimeout(globalTimeoutObjectSpy, 9999);
nodeTimers.setTimeout(nodeTimerSpy, 9999);
const promise = nodeTimersPromises.setTimeout(9999).then(nodeTimerPromiseSpy);
// Advance in time
context.mock.timers.tick(9999);
assert.strictEqual(globalTimeoutObjectSpy.mock.callCount(), 1);
assert.strictEqual(nodeTimerSpy.mock.callCount(), 1);
await promise;
assert.strictEqual(nodeTimerPromiseSpy.mock.callCount(), 1);
});
const assert = require('node:assert');
const { test } = require('node:test');
const nodeTimers = require('node:timers');
const nodeTimersPromises = require('node:timers/promises');
test('mocks setTimeout to be executed synchronously without having to actually wait for it', async (context) => {
const globalTimeoutObjectSpy = context.mock.fn();
const nodeTimerSpy = context.mock.fn();
const nodeTimerPromiseSpy = context.mock.fn();
// Optionally choose what to mock
context.mock.timers.enable(['setTimeout']);
setTimeout(globalTimeoutObjectSpy, 9999);
nodeTimers.setTimeout(nodeTimerSpy, 9999);
const promise = nodeTimersPromises.setTimeout(9999).then(nodeTimerPromiseSpy);
// Advance in time
context.mock.timers.tick(9999);
assert.strictEqual(globalTimeoutObjectSpy.mock.callCount(), 1);
assert.strictEqual(nodeTimerSpy.mock.callCount(), 1);
await promise;
assert.strictEqual(nodeTimerPromiseSpy.mock.callCount(), 1);
});
在 Node.js 中,node:timers/promises 中的 setInterval
是 AsyncGenerator
,并且也受此 API 支持:
¥In Node.js, setInterval
from node:timers/promises
is an AsyncGenerator
and is also supported by this API:
import assert from 'node:assert';
import { test } from 'node:test';
import nodeTimersPromises from 'node:timers/promises';
test('should tick five times testing a real use case', async (context) => {
context.mock.timers.enable(['setInterval']);
const expectedIterations = 3;
const interval = 1000;
const startedAt = Date.now();
async function run() {
const times = [];
for await (const time of nodeTimersPromises.setInterval(interval, startedAt)) {
times.push(time);
if (times.length === expectedIterations) break;
}
return times;
}
const r = run();
context.mock.timers.tick(interval);
context.mock.timers.tick(interval);
context.mock.timers.tick(interval);
const timeResults = await r;
assert.strictEqual(timeResults.length, expectedIterations);
for (let it = 1; it < expectedIterations; it++) {
assert.strictEqual(timeResults[it - 1], startedAt + (interval * it));
}
});
const assert = require('node:assert');
const { test } = require('node:test');
const nodeTimersPromises = require('node:timers/promises');
test('should tick five times testing a real use case', async (context) => {
context.mock.timers.enable(['setInterval']);
const expectedIterations = 3;
const interval = 1000;
const startedAt = Date.now();
async function run() {
const times = [];
for await (const time of nodeTimersPromises.setInterval(interval, startedAt)) {
times.push(time);
if (times.length === expectedIterations) break;
}
return times;
}
const r = run();
context.mock.timers.tick(interval);
context.mock.timers.tick(interval);
context.mock.timers.tick(interval);
const timeResults = await r;
assert.strictEqual(timeResults.length, expectedIterations);
for (let it = 1; it < expectedIterations; it++) {
assert.strictEqual(timeResults[it - 1], startedAt + (interval * it));
}
});
timers.runAll()
#
立即触发所有待处理的模拟定时器。
¥Triggers all pending mocked timers immediately.
下面的示例立即触发所有待处理的定时器,使它们立即执行。
¥The example below triggers all pending timers immediately, causing them to execute without any delay.
import assert from 'node:assert';
import { test } from 'node:test';
test('runAll functions following the given order', (context) => {
context.mock.timers.enable(['setTimeout']);
const results = [];
setTimeout(() => results.push(1), 9999);
// Notice that if both timers have the same timeout,
// the order of execution is guaranteed
setTimeout(() => results.push(3), 8888);
setTimeout(() => results.push(2), 8888);
assert.deepStrictEqual(results, []);
context.mock.timers.runAll();
assert.deepStrictEqual(results, [3, 2, 1]);
});
const assert = require('node:assert');
const { test } = require('node:test');
test('runAll functions following the given order', (context) => {
context.mock.timers.enable(['setTimeout']);
const results = [];
setTimeout(() => results.push(1), 9999);
// Notice that if both timers have the same timeout,
// the order of execution is guaranteed
setTimeout(() => results.push(3), 8888);
setTimeout(() => results.push(2), 8888);
assert.deepStrictEqual(results, []);
context.mock.timers.runAll();
assert.deepStrictEqual(results, [3, 2, 1]);
});
注意:runAll()
函数是专门为在定时器模拟上下文中触发定时器而设计的。它对模拟环境之外的实时系统时钟或实际定时器没有任何影响。
¥Note: The runAll()
function is specifically designed for
triggering timers in the context of timer mocking.
It does not have any effect on real-time system
clocks or actual timers outside of the mocking environment.
类:TestsStream
#
¥Class: TestsStream
-
¥Extends <ReadableStream>
成功调用 run()
方法将返回一个新的 <TestsStream> 对象,流式传输代表测试执行的一系列事件。TestsStream
将按照测试定义的顺序触发事件
¥A successful call to run()
method will return a new <TestsStream>
object, streaming a series of events representing the execution of the tests.
TestsStream
will emit events, in the order of the tests definition
事件:'test:coverage'
#
¥Event: 'test:coverage'
-
data
<Object>-
summary
<Object> 包含覆盖率报告的对象。¥
summary
<Object> An object containing the coverage report.-
files
<Array> 单个文件的一系列覆盖率报告。每个报告都是具有以下架构的对象:¥
files
<Array> An array of coverage reports for individual files. Each report is an object with the following schema:-
path
<string> 文件的绝对路径。¥
path
<string> The absolute path of the file. -
totalLineCount
<number> 总行数。¥
totalLineCount
<number> The total number of lines. -
totalBranchCount
<number> 分支总数。¥
totalBranchCount
<number> The total number of branches. -
totalFunctionCount
<number> 函数总数。¥
totalFunctionCount
<number> The total number of functions. -
coveredLineCount
<number> 被覆盖的行数。¥
coveredLineCount
<number> The number of covered lines. -
coveredBranchCount
<number> 覆盖的分支数。¥
coveredBranchCount
<number> The number of covered branches. -
coveredFunctionCount
<number> 覆盖函数的个数。¥
coveredFunctionCount
<number> The number of covered functions. -
coveredLinePercent
<number> 覆盖行的百分比。¥
coveredLinePercent
<number> The percentage of lines covered. -
coveredBranchPercent
<number> 覆盖的分支百分比。¥
coveredBranchPercent
<number> The percentage of branches covered. -
coveredFunctionPercent
<number> 覆盖的函数百分比。¥
coveredFunctionPercent
<number> The percentage of functions covered. -
uncoveredLineNumbers
<Array> 一个整数数组,表示未覆盖的行号。¥
uncoveredLineNumbers
<Array> An array of integers representing line numbers that are uncovered.
-
-
totals
<Object> 包含所有文件覆盖率摘要的对象。¥
totals
<Object> An object containing a summary of coverage for all files.-
totalLineCount
<number> 总行数。¥
totalLineCount
<number> The total number of lines. -
totalBranchCount
<number> 分支总数。¥
totalBranchCount
<number> The total number of branches. -
totalFunctionCount
<number> 函数总数。¥
totalFunctionCount
<number> The total number of functions. -
coveredLineCount
<number> 被覆盖的行数。¥
coveredLineCount
<number> The number of covered lines. -
coveredBranchCount
<number> 覆盖的分支数。¥
coveredBranchCount
<number> The number of covered branches. -
coveredFunctionCount
<number> 覆盖函数的个数。¥
coveredFunctionCount
<number> The number of covered functions. -
coveredLinePercent
<number> 覆盖行的百分比。¥
coveredLinePercent
<number> The percentage of lines covered. -
coveredBranchPercent
<number> 覆盖的分支百分比。¥
coveredBranchPercent
<number> The percentage of branches covered. -
coveredFunctionPercent
<number> 覆盖的函数百分比。¥
coveredFunctionPercent
<number> The percentage of functions covered.
-
-
workingDirectory
<string> 代码覆盖开始时的工作目录。这对于显示相对路径名很有用,以防测试更改了 Node.js 进程的工作目录。¥
workingDirectory
<string> The working directory when code coverage began. This is useful for displaying relative path names in case the tests changed the working directory of the Node.js process.
-
-
nesting
<number> 测试的嵌套级别。¥
nesting
<number> The nesting level of the test.
-
启用代码覆盖率并且所有测试都已完成时触发。
¥Emitted when code coverage is enabled and all tests have completed.
事件:'test:dequeue'
#
¥Event: 'test:dequeue'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
file
<string> | <undefined> 测试文件的路径,如果测试是通过 REPL 运行的,则为undefined
。¥
file
<string> | <undefined> The path of the test file,undefined
if test was run through the REPL. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
name
<string> 测试名称。¥
name
<string> The test name. -
nesting
<number> 测试的嵌套级别。¥
nesting
<number> The nesting level of the test.
-
当测试出列时(在执行之前)触发。
¥Emitted when a test is dequeued, right before it is executed.
事件:'test:diagnostic'
#
¥Event: 'test:diagnostic'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
file
<string> | <undefined> 测试文件的路径,如果测试是通过 REPL 运行的,则为undefined
。¥
file
<string> | <undefined> The path of the test file,undefined
if test was run through the REPL. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
message
<string> 诊断消息。¥
message
<string> The diagnostic message. -
nesting
<number> 测试的嵌套级别。¥
nesting
<number> The nesting level of the test.
-
调用 context.diagnostic
时触发。
¥Emitted when context.diagnostic
is called.
事件:'test:enqueue'
#
¥Event: 'test:enqueue'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
file
<string> | <undefined> 测试文件的路径,如果测试是通过 REPL 运行的,则为undefined
。¥
file
<string> | <undefined> The path of the test file,undefined
if test was run through the REPL. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
name
<string> 测试名称。¥
name
<string> The test name. -
nesting
<number> 测试的嵌套级别。¥
nesting
<number> The nesting level of the test.
-
当测试排队执行时触发。
¥Emitted when a test is enqueued for execution.
事件:'test:fail'
#
¥Event: 'test:fail'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
details
<Object> 额外的执行元数据。¥
details
<Object> Additional execution metadata.-
duration_ms
<number> 以毫秒为单位的测试持续时间。¥
duration_ms
<number> The duration of the test in milliseconds. -
error
<Error> 封装测试引发的错误的错误。¥
error
<Error> An error wrapping the error thrown by the test. -
type
<string> | <undefined> 测试的类型,用于指示这是否是一个套件。¥
type
<string> | <undefined> The type of the test, used to denote whether this is a suite.
-
-
file
<string> | <undefined> 测试文件的路径,如果测试是通过 REPL 运行的,则为undefined
。¥
file
<string> | <undefined> The path of the test file,undefined
if test was run through the REPL. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
name
<string> 测试名称。¥
name
<string> The test name. -
nesting
<number> 测试的嵌套级别。¥
nesting
<number> The nesting level of the test. -
testNumber
<number> 测试的序号。¥
testNumber
<number> The ordinal number of the test. -
todo
<string> | <boolean> | <undefined> 如果调用context.todo
,则存在¥
todo
<string> | <boolean> | <undefined> Present ifcontext.todo
is called -
skip
<string> | <boolean> | <undefined> 如果调用context.skip
,则存在¥
skip
<string> | <boolean> | <undefined> Present ifcontext.skip
is called
-
测试失败时触发。
¥Emitted when a test fails.
事件:'test:pass'
#
¥Event: 'test:pass'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
details
<Object> 额外的执行元数据。¥
details
<Object> Additional execution metadata.-
duration_ms
<number> 以毫秒为单位的测试持续时间。¥
duration_ms
<number> The duration of the test in milliseconds. -
type
<string> | <undefined> 测试的类型,用于指示这是否是一个套件。¥
type
<string> | <undefined> The type of the test, used to denote whether this is a suite.
-
-
file
<string> | <undefined> 测试文件的路径,如果测试是通过 REPL 运行的,则为undefined
。¥
file
<string> | <undefined> The path of the test file,undefined
if test was run through the REPL. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
name
<string> 测试名称。¥
name
<string> The test name. -
nesting
<number> 测试的嵌套级别。¥
nesting
<number> The nesting level of the test. -
testNumber
<number> 测试的序号。¥
testNumber
<number> The ordinal number of the test. -
todo
<string> | <boolean> | <undefined> 如果调用context.todo
,则存在¥
todo
<string> | <boolean> | <undefined> Present ifcontext.todo
is called -
skip
<string> | <boolean> | <undefined> 如果调用context.skip
,则存在¥
skip
<string> | <boolean> | <undefined> Present ifcontext.skip
is called
-
测试通过时触发。
¥Emitted when a test passes.
事件:'test:plan'
#
¥Event: 'test:plan'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
file
<string> | <undefined> 测试文件的路径,如果测试是通过 REPL 运行的,则为undefined
。¥
file
<string> | <undefined> The path of the test file,undefined
if test was run through the REPL. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
nesting
<number> 测试的嵌套级别。¥
nesting
<number> The nesting level of the test. -
count
<number> 已运行的子测试数。¥
count
<number> The number of subtests that have ran.
-
当给定测试的所有子测试都完成时触发。
¥Emitted when all subtests have completed for a given test.
事件:'test:start'
#
¥Event: 'test:start'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
file
<string> | <undefined> 测试文件的路径,如果测试是通过 REPL 运行的,则为undefined
。¥
file
<string> | <undefined> The path of the test file,undefined
if test was run through the REPL. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
name
<string> 测试名称。¥
name
<string> The test name. -
nesting
<number> 测试的嵌套级别。¥
nesting
<number> The nesting level of the test.
-
当测试开始报告其自身及其子测试状态时触发。该事件保证按照测试定义的顺序触发。
¥Emitted when a test starts reporting its own and its subtests status. This event is guaranteed to be emitted in the same order as the tests are defined.
事件:'test:stderr'
#
¥Event: 'test:stderr'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
file
<string> 测试文件的路径。¥
file
<string> The path of the test file. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
message
<string> 写入stderr
的消息。¥
message
<string> The message written tostderr
.
-
当正在运行的测试写入 stderr
时触发。只有在传递 --test
标志时才会触发此事件。
¥Emitted when a running test writes to stderr
.
This event is only emitted if --test
flag is passed.
事件:'test:stdout'
#
¥Event: 'test:stdout'
-
data
<Object>-
column
<number> | <undefined> 定义测试的列号,如果测试是通过 REPL 运行的,则为undefined
。¥
column
<number> | <undefined> The column number where the test is defined, orundefined
if the test was run through the REPL. -
file
<string> 测试文件的路径。¥
file
<string> The path of the test file. -
line
<number> | <undefined> 定义测试的行号,如果测试是通过 REPL 运行的,则为undefined
。¥
line
<number> | <undefined> The line number where the test is defined, orundefined
if the test was run through the REPL. -
message
<string> 写入stdout
的消息。¥
message
<string> The message written tostdout
.
-
当正在运行的测试写入 stdout
时触发。只有在传递 --test
标志时才会触发此事件。
¥Emitted when a running test writes to stdout
.
This event is only emitted if --test
flag is passed.
事件:'test:watch:drained'
#
¥Event: 'test:watch:drained'
当没有更多测试排队等待以监视模式执行时触发。
¥Emitted when no more tests are queued for execution in watch mode.
类:TestContext
#
¥Class: TestContext
TestContext
的实例被传给每个测试函数,以便与测试运行器交互。但是,TestContext
构造函数没有作为 API 的一部分公开。
¥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.
context.before([fn][, options])
#
-
fn
<Function> | <AsyncFunction> 钩子函数。此函数的第一个参数是TestContext
对象。如果钩子使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The hook function. The first argument to this function is aTestContext
object. If the hook uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
options
<Object> 钩子的配置选项。支持以下属性:¥
options
<Object> Configuration options for the hook. The following properties are supported:-
signal
<AbortSignal> 允许中止正在进行的钩子。¥
signal
<AbortSignal> Allows aborting an in-progress hook. -
timeout
<number> 钩子会在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the hook will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
此函数用于创建在当前测试的子测试之前运行的钩子。
¥This function is used to create a hook running before subtest of the current test.
context.beforeEach([fn][, options])
#
-
fn
<Function> | <AsyncFunction> 钩子函数。此函数的第一个参数是TestContext
对象。如果钩子使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The hook function. The first argument to this function is aTestContext
object. If the hook uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
options
<Object> 钩子的配置选项。支持以下属性:¥
options
<Object> Configuration options for the hook. The following properties are supported:-
signal
<AbortSignal> 允许中止正在进行的钩子。¥
signal
<AbortSignal> Allows aborting an in-progress hook. -
timeout
<number> 钩子会在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the hook will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
此函数用于创建一个在当前测试的每个子测试之前运行的钩子。
¥This function is used to create a hook running before each subtest of the current test.
test('top level test', async (t) => {
t.beforeEach((t) => t.diagnostic(`about to run ${t.name}`));
await t.test(
'This is a subtest',
(t) => {
assert.ok('some relevant assertion here');
},
);
});
context.after([fn][, options])
#
-
fn
<Function> | <AsyncFunction> 钩子函数。此函数的第一个参数是TestContext
对象。如果钩子使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The hook function. The first argument to this function is aTestContext
object. If the hook uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
options
<Object> 钩子的配置选项。支持以下属性:¥
options
<Object> Configuration options for the hook. The following properties are supported:-
signal
<AbortSignal> 允许中止正在进行的钩子。¥
signal
<AbortSignal> Allows aborting an in-progress hook. -
timeout
<number> 钩子会在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the hook will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
此函数用于创建一个在当前测试完成后运行的钩子。
¥This function is used to create a hook that runs after the current test finishes.
test('top level test', async (t) => {
t.after((t) => t.diagnostic(`finished running ${t.name}`));
assert.ok('some relevant assertion here');
});
context.afterEach([fn][, options])
#
-
fn
<Function> | <AsyncFunction> 钩子函数。此函数的第一个参数是TestContext
对象。如果钩子使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The hook function. The first argument to this function is aTestContext
object. If the hook uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
options
<Object> 钩子的配置选项。支持以下属性:¥
options
<Object> Configuration options for the hook. The following properties are supported:-
signal
<AbortSignal> 允许中止正在进行的钩子。¥
signal
<AbortSignal> Allows aborting an in-progress hook. -
timeout
<number> 钩子会在几毫秒后失败。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the hook will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
此函数用于创建一个在当前测试的每个子测试之后运行的钩子。
¥This function is used to create a hook running after each subtest of the current test.
test('top level test', async (t) => {
t.afterEach((t) => t.diagnostic(`finished running ${t.name}`));
await t.test(
'This is a subtest',
(t) => {
assert.ok('some relevant assertion here');
},
);
});
context.diagnostic(message)
#
此函数用于将诊断写入输出。任何诊断信息都包含在测试结果的末尾。此函数不返回值。
¥This function is used to write diagnostics to the output. Any diagnostic information is included at the end of the test's results. This function does not return a value.
test('top level test', (t) => {
t.diagnostic('A diagnostic message');
});
context.name
#
测试名称。
¥The name of the test.
context.runOnly(shouldRunOnlyTests)
#
-
shouldRunOnlyTests
<boolean> 是否运行only
测试。¥
shouldRunOnlyTests
<boolean> Whether or not to runonly
tests.
如果 shouldRunOnlyTests
为真,则测试上下文将只运行设置了 only
选项的测试。否则,将运行所有测试。如果 Node.js 不是使用 --test-only
命令行选项启动的,则此函数是无操作的。
¥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.
test('top level test', (t) => {
// The test context can be set to run subtests with the 'only' option.
t.runOnly(true);
return Promise.all([
t.test('this subtest is now skipped'),
t.test('this subtest is run', { only: true }),
]);
});
context.signal
#
-
<AbortSignal> 可用于在测试中止时中止测试子任务。
¥<AbortSignal> Can be used to abort test subtasks when the test has been aborted.
test('top level test', async (t) => {
await fetch('some/uri', { signal: t.signal });
});
context.skip([message])
#
此函数使测试的输出指示测试已跳过。如果提供了 message
,它会包含在输出中。调用 skip()
不会终止测试函数的执行。此函数不返回值。
¥This function causes the test's output to indicate the test as skipped. If
message
is provided, it is included in the output. Calling skip()
does
not terminate execution of the test function. This function does not return a
value.
test('top level test', (t) => {
// Make sure to return here as well if the test contains additional logic.
t.skip('this is skipped');
});
context.todo([message])
#
此函数将 TODO
指令添加到测试的输出中。如果提供了 message
,它会包含在输出中。调用 todo()
不会终止测试函数的执行。此函数不返回值。
¥This function adds a TODO
directive to the test's output. If message
is
provided, it is included in the output. Calling todo()
does not terminate
execution of the test function. This function does not return a value.
test('top level test', (t) => {
// This test is marked as `TODO`
t.todo('this is a todo');
});
context.test([name][, options][, fn])
#
-
name
<string> 子测试的名称,在报告测试结果时显示。默认值:fn
的name
属性,如果fn
没有名称,则为'<anonymous>'
。¥
name
<string> The name of the subtest, which is displayed when reporting test results. Default: Thename
property offn
, or'<anonymous>'
iffn
does not have a name. -
options
<Object> 子测试的配置选项。支持以下属性:¥
options
<Object> Configuration options for the subtest. The following properties are supported:-
concurrency
<number> | <boolean> | <null> 如果提供了一个数字,那么许多测试将在应用线程中并行运行。如果是true
,它将并行运行所有子测试。如果是false
,它一次只会运行一个测试。如果未指定,则子测试从其父测试继承此值。默认值:null
。¥
concurrency
<number> | <boolean> | <null> If a number is provided, then that many tests would run in parallel within the application thread. Iftrue
, it would run all subtests in parallel. Iffalse
, it would only run one test at a time. If unspecified, subtests inherit this value from their parent. Default:null
. -
only
<boolean> 如果为真,并且测试上下文配置为运行only
测试,则将运行此测试。否则跳过测试。默认值:false
。¥
only
<boolean> If truthy, and the test context is configured to runonly
tests, then this test will be run. Otherwise, the test is skipped. Default:false
. -
signal
<AbortSignal> 允许中止正在进行的测试。¥
signal
<AbortSignal> Allows aborting an in-progress test. -
skip
<boolean> | <string> 如果为真,则跳过测试。如果提供了字符串,则该字符串将作为跳过测试的原因显示在测试结果中。默认值:false
。¥
skip
<boolean> | <string> 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
. -
todo
<boolean> | <string> 如果为真,则测试标记为TODO
。如果提供了字符串,则该字符串会显示在测试结果中作为测试为TODO
的原因。默认值:false
。¥
todo
<boolean> | <string> If truthy, the test marked asTODO
. If a string is provided, that string is displayed in the test results as the reason why the test isTODO
. Default:false
. -
timeout
<number> 测试失败的毫秒数。如果未指定,则子测试从其父测试继承此值。默认值:Infinity
。¥
timeout
<number> A number of milliseconds the test will fail after. If unspecified, subtests inherit this value from their parent. Default:Infinity
.
-
-
fn
<Function> | <AsyncFunction> 被测试的函数。此函数的第一个参数是TestContext
对象。如果测试使用回调,则回调函数作为第二个参数传入。默认值:空操作函数。¥
fn
<Function> | <AsyncFunction> The function under test. The first argument to this function is aTestContext
object. If the test uses callbacks, the callback function is passed as the second argument. Default: A no-op function. -
返回:<Promise> 测试完成后使用
undefined
解决。¥Returns: <Promise> Resolved with
undefined
once the test completes.
此函数用于在当前测试下创建子测试。此函数的行为方式与顶层的 test()
函数相同。
¥This function is used to create subtests under the current test. This function
behaves in the same fashion as the top level test()
function.
test('top level test', async (t) => {
await t.test(
'This is a subtest',
{ only: false, skip: false, concurrency: 1, todo: false },
(t) => {
assert.ok('some relevant assertion here');
},
);
});
类:SuiteContext
#
¥Class: SuiteContext
SuiteContext
的实例被传给每个套件函数,以便与测试运行器进行交互。但是,SuiteContext
构造函数没有作为 API 的一部分公开。
¥An instance of SuiteContext
is passed to each suite function in order to
interact with the test runner. However, the SuiteContext
constructor is not
exposed as part of the API.
context.name
#
套件名称。
¥The name of the suite.
context.signal
#
-
<AbortSignal> 可用于在测试中止时中止测试子任务。
¥<AbortSignal> Can be used to abort test subtasks when the test has been aborted.