测试运行器

概述与架构

Node.js 测试运行器由一组 JavaScript API 和可执行组件组成，允许开发人员编写和运行测试。可以通过 node:test 模块访问。

测试运行器支持三种风格的测试函数：

同步函数 - 如果不抛出异常，则认为通过
返回 Promise 的函数 - 如果 Promise fulfilled，则认为通过
接受回调参数的函数 - 如果回调的第一个参数为 falsy 值，则认为通过

核心架构

测试运行器的架构由多个关键组件组成，这些组件协同工作以发现、执行和报告测试结果。

来源：lib/test.js1-73 lib/internal/test_runner/test.js1-260 lib/internal/test_runner/harness.js1-100 lib/internal/test_runner/tests_stream.js1-165

测试执行模型

运行时，测试运行器遵循特定的执行模型。

来源：lib/internal/test_runner/runner.js100-180 lib/internal/test_runner/test.js990-1090

默认情况下，在使用 node --test 时，测试运行器会查找匹配特定模式的文件（请参阅“从命令行运行测试”部分），并根据是否使用隔离来在单独的进程或同一进程中执行它们。

编写测试

测试运行器提供了多种定义测试的方式：

基本测试

来源：doc/api/test.md18-92

带有 `describe` 和 `it` 的测试套件

测试运行器还支持带有 describe() 和 it() 函数的 BDD 风格接口

来源：doc/api/test.md182-214

测试钩子

测试钩子允许您在测试之前和之后运行代码。

来源：test/fixtures/test-runner/output/hooks.js1-300 lib/internal/test_runner/test.js375-415

用途

与 describe 和 it 也可以使用相同的钩子。

来源：doc/api/test.md97-116 test/fixtures/test-runner/output/hooks.js10-54

控制测试执行

跳过测试

可以使用 skip 选项或方法跳过测试。

来源：doc/api/test.md123-149

TODO 测试

TODO 测试将测试标记为尚未实现或标记为未来将修复的失败测试。

来源：doc/api/test.md151-180

仅运行特定测试

可以使用 only 选项来运行测试的子集。

来源：doc/api/test.md216-282

按名称过滤测试

可以使用 --test-name-pattern 和 --test-skip-pattern 命令行选项按名称过滤测试。

这些也可以作为正则表达式提供。

来源：doc/api/test.md284-343

测试报告

测试运行器使用各种报告器输出测试结果。

可用的报告器

来源：lib/internal/test_runner/reporter/tap.js1-282 lib/internal/test_runner/reporter/spec.js1-118 doc/api/test.md1039-1097

可用的报告器有：

报告器	描述
`spec`	人类可读的层级式测试视图（默认）
`tap`	Test Anything Protocol 格式
`dot`	紧凑的输出，用点表示通过的测试
`junit`	JUnit XML 格式，用于 CI 集成
`lcov`	LCOV 覆盖率报告格式

来源：doc/api/test.md1058-1076 lib/internal/test_runner/utils.js119-131

使用报告器

来源：doc/api/test.md1052-1057 lib/internal/test_runner/utils.js145-187

自定义报告器

您可以通过实现一个 transform stream 来创建自定义报告器。

来源：doc/api/test.md1094-1144

高级特性

模拟

测试运行器提供了内置的模拟功能。

TestContext 也提供了相同的模拟功能。

模拟 API 还提供计时器模拟功能。

来源：doc/api/test.md572-762

快照测试

快照测试允许您将测试输出与已知良好值进行比较。

快照存储在 .snapshot 文件中，并可以使用 --test-update-snapshots 标志进行更新。

来源： doc/api/test.md979-1037

监视模式

测试运行器支持监视模式，当文件更改时会自动重新运行测试

它会监视测试文件及其依赖项，在检测到更改时重新运行受影响的测试。

来源： doc/api/test.md379-399 lib/internal/test_runner/runner.js462-541

代码覆盖率

测试运行器可以收集代码覆盖率信息

覆盖率报告可以生成为不同的格式

来源： doc/api/test.md515-569

从命令行运行测试

Node.js 测试运行器可以使用 `--test` 标志从命令行调用

默认情况下，Node.js 将运行匹配以下模式的文件

模式	描述
`*/.test.{cjs,mjs,js}`	以 .test.js 结尾的文件
`*/-test.{cjs,mjs,js}`	以 -test.js 结尾的文件
`*/_test.{cjs,mjs,js}`	以 _test.js 结尾的文件
`*/test-.{cjs,mjs,js}`	以 test- 开头的文件
`**/test.{cjs,mjs,js}`	名为 test.js 的文件
`/test//*.{cjs,mjs,js}`	test 目录下的 JS 文件

TypeScript 测试文件默认也受支持，除非提供了 `--no-experimental-strip-types`。

可以提供自定义模式

来源： doc/api/test.md454-491 lib/internal/test_runner/utils.js60-66

命令行选项

选项	描述
`--test`	启用测试运行器
`--test-only`	仅运行带有 `only` 选项的测试
`--test-reporter=<reporter>`	指定要使用的测试报告器
`--test-reporter-destination=<destination>`	指定报告器的输出去向
`--test-name-pattern=<pattern>`	仅运行匹配模式的测试
`--test-skip-pattern=<pattern>`	跳过匹配模式的测试
`--test-timeout=<ms>`	设置默认测试超时时间
`--watch`	监视更改并重新运行测试
`--experimental-test-coverage`	启用代码覆盖率

来源： lib/internal/test_runner/utils.js193-348 lib/internal/main/test_runner.js19-38

通过编程 API 使用

测试运行器可以通过 `run()` API 以编程方式使用

来源： lib/test.js11-21 lib/internal/test_runner/runner.js543-875 test/parallel/test-runner-run.mjs10-325

结论

Node.js 测试运行器提供了一个全面的内置解决方案，用于测试 JavaScript 代码。其功能包括用于定义测试的灵活 API、各种报告选项、测试过滤、模拟功能以及对快照测试和代码覆盖率等高级功能的支持。

该设计遵循 Node.js 的核心原则，重点关注简单性、可组合性以及与现有生态系统的集成。通过提供 API 和命令行界面，它适应了不同的测试工作流程和环境。