Vitest TestModule 任务 API 详解掌握测试模块的标识、状态与诊断信息【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestTestModule是 Vitest 测试任务树Task Tree中代表单个项目中的单个测试文件模块的核心类它只在主线程main thread中可用是自定义 Reporter、Test Runner 与各类工具链集成时最常打交道的任务类型之一。本文将基于官方 API 文档并结合 Vitest 仓库源码完整讲解TestModule的type判别、moduleId/relativeModuleId标识体系、viteEnvironment、state()、meta()、diagnostic()、logs()与toTestSpecification()等全部属性与方法读完你可以在自定义 Reporter、Runner 或 CLI 工具中准确读取、过滤并重新调度测试模块。一、TestModule 是什么主线程中的模块级任务TestModule类表示单个项目中的单个测试模块通常对应一个测试文件并且只存在于主线程。如果你在 Runtime 中处理任务应使用 Runner API 中对应的运行时任务类型。在 reported-tasks.ts 源码中TestModule继承自SuiteImplementation并声明了public readonly type module。由于测试任务存在模块module、套件suite、用例test等多种形态官方推荐通过type属性进行运行时判别if (task.type module) { task // TestModule }与之相对TestSuite 的type恒为suite用例的type恒为test。::: warning 继承说明TestModule继承自TestSuite的全部方法与属性如children、errors()、ok()、options、fullName等本文只列出TestModule独有的方法与属性。相关继承能力可参考 TestSuite API。 :::二、模块标识moduleId 与 relativeModuleIdmoduleIdmoduleId是该模块在 ViteModuleGraph中的唯一标识通常是绝对 UNIX 风格路径即使在 Windows 上也是。如果文件不在磁盘上例如虚拟模块它可以是虚拟 IDvirtual id。C:/Users/Documents/project/example.test.ts // ✅ 合法UNIX 风格 /Users/mac/project/example.test.ts // ✅ 合法 C:\\Users\\Documents\\project\\example.test.ts // ❌ 非法反斜杠形式从源码实现看moduleId直接取自底层任务的filepath// packages/vitest/src/node/reporters/reported-tasks.ts this.moduleId task.filepathrelativeModuleIdrelativeModuleId是相对当前项目根目录的模块 ID与旧 API 中的task.name完全一致project/example.test.ts // ✅ 合法 example.test.ts // ✅ 合法 project\\example.test.ts // ❌ 非法反斜杠形式源码中它直接对应底层任务的name字段this.relativeModuleId task.name这两个标识符是构建测试文件过滤、去重、缓存与报告输出的基础例如自定义 Reporter 中常用relativeModuleId展示给用户而用moduleId与 Vite 模块图对齐。三、viteEnvironment模块的 Vite 开发环境版本要求Vitest 4.1.0 起正式提供在 v4.0.15 中以实验性 API 加入。viteEnvironment是用于转换该测试模块内所有文件的 ViteDevEnvironment实例。它是理解 Vitest 环境隔离机制的关键每个测试模块都在特定的 Vite 环境中被转换与执行环境决定了模块可用的插件、解析与转换管线。源码中的对应定义如下注意模块尚未执行时该字段可能为空// packages/vitest/src/node/reporters/reported-tasks.ts public readonly viteEnvironment: DevEnvironment | undefined // 构造函数中按环境名从项目环境中解析 if (typeof task.viteEnvironment string) { this.viteEnvironment project.vite.environments[task.viteEnvironment] }因此当你需要通过编程方式读取某个模块的转换结果、模块图或依赖关系时可以借助viteEnvironment拿到底层环境对象。四、state()查询模块运行状态function state(): TestModuleStatestate()与 TestSuite.state() 工作方式相同可返回pending、failed、passed、skipped区别在于TestModule还可以返回queued表示模块尚未被执行仍在队列中等待调度。源码中的TestModuleState类型在TestSuiteState基础上扩展了queuedexport type TestSuiteState skipped | pending | failed | passed export type TestModuleState TestSuiteState | queued实现逻辑为先读取底层任务的result.state若为queued直接返回否则复用套件状态计算逻辑public state(): TestModuleState { const state this.task.result?.state if (state queued) { return queued } return getSuiteState(this.task) }五、meta()读写模块级自定义元数据版本要求Vitest 3.1.0 起提供。function meta(): TaskMeta返回模块在收集collection或执行execution期间被附加的自定义元数据。元数据的附加方式是在测试运行期间直接给task.meta对象赋值属性。官方文档给出如下示例import { test } from vitest describe(the validation works correctly, (task) { // assign decorated during collection task.file.meta.decorated false test(some test, ({ task }) { // assign decorated during test run, it will be available // only in onTestCaseReady hook task.file.meta.decorated false }) })::: tip 使用时机提示 如果元数据是在收集阶段test函数之外附加的那么它在自定义 Reporter 的onTestModuleCollected钩子中即可读取若是在测试运行期间附加则只能在onTestCaseReady钩子之后才可见。 :::六、diagnostic()模块级性能与资源诊断function diagnostic(): ModuleDiagnostic返回模块的有用诊断信息如耗时、内存占用等。如果模块尚未执行所有诊断值都会返回0。完整的ModuleDiagnostic接口与源码 reported-tasks.ts 定义一致如下interface ModuleDiagnostic { /** * 导入并初始化环境所花费的时间。 */ readonly environmentSetupDuration: number /** * Vitest 搭建测试脚手架runner、mocks 等所花费的时间。 */ readonly prepareDuration: number /** * 导入测试模块所花费的时间。 * 包含导入模块内所有内容以及执行套件回调。 */ readonly collectDuration: number /** * 导入 setup 模块所花费的时间。 */ readonly setupDuration: number /** * 模块内所有测试与钩子的累计耗时。 */ readonly duration: number /** * 模块占用的内存字节数。 * 仅当使用 logHeapUsage 标志执行测试时可用。 */ readonly heap: number | undefined /** * Vitest 处理过的每个非外部化依赖的导入耗时。 */ readonly importDurations: Recordstring, ImportDuration /** * 运行该文件的 worker 的 id。该值不会高于 maxWorkers。 * 如果文件尚未运行该值为 0。 * * 注意Node.js 测试与浏览器测试运行在不同的 pool 中不共享 concurrencyId * 因此可能出现多个模块拥有相同 concurrencyId 的情况。 * 请使用 project.isBrowserEnabled() 加以区分。 */ readonly concurrencyId: number /** * 运行该文件的 worker 的递增编号随每个 worker 增加。 * 如果文件尚未运行该值为 0。 * * 注意Node.js 测试与浏览器测试运行在不同的 pool 中不共享 workerId * 因此可能出现多个模块拥有相同 workerId 的情况。 * 请使用 project.isBrowserEnabled() 加以区分。 */ readonly workerId: number } /** 导入并执行某个非外部化文件所花费的时间。 */ interface ImportDuration { /** 导入并执行该文件本身不计其非外部化导入的时间。 */ selfTime: number /** 导入并执行该文件及其所有导入的时间。 */ totalTime: number }各字段在源码diagnostic()实现中的取值来源非常清晰——它们直接映射到底层任务的不同耗时记录const setupDuration this.task.setupDuration || 0 const collectDuration this.task.collectDuration || 0 const prepareDuration this.task.prepareDuration || 0 const environmentSetupDuration this.task.environmentLoad || 0 const duration this.task.result?.duration || 0 const heap this.task.result?.heap const importDurations this.task.importDurations ?? {}实战建议分析慢测试模块时可对比collectDuration与duration前者代表收集开销后者代表执行开销heap需要配合 logHeapUsage 配置开启后才会有值通过importDurations可以精确定位哪个依赖导入最耗时selfTime是该文件自身耗时totalTime含其全部传递导入是排查启动缓慢的得力工具。七、logs()收集阶段的顶层控制台日志版本要求Vitest 5.0.0 起提供。function logs(): ReadonlyArrayUserConsoleLog返回在测试收集期间、模块顶层记录的 console 日志。注意它只包含模块顶层top level的输出不包含套件回调或测试函数内部的输出console.log(included) // ✅ 会被记录模块顶层 describe(suite, () { console.log(not included) // ❌ 套件回调内 test(test, () { console.log(not included) // ❌ 测试函数内 }) })这与 TestSuite.logs()记录套件及其beforeAll钩子收集期间的日志形成了粒度上的互补模块级只看文件顶层套件级覆盖套件作用域。八、toTestSpecification()生成可执行的测试规格版本要求Vitest 4.1.0 起提供。function toTestSpecification(testCases?: TestCase[]): TestSpecification返回一个新的测试规格TestSpecification可用于过滤或运行这个特定的测试模块。它接受一个可选的测试用例数组用于限定要运行的用例范围。源码实现reported-tasks.ts展示了其内部逻辑它会识别该模块是否为 typecheck 模块meta.typecheck true并调用TestProject.createSpecification生成规格public toTestSpecification(testCases?: TestCase[]): TestSpecification { const isTypecheck this.task.meta.typecheck true return this.project.createSpecification( this.moduleId, testCases?.length ? { testIds: testCases.map(t t.id) } : undefined, isTypecheck ? typecheck : undefined, ) }而createSpecification见 project.ts会结合模块 ID、目标测试用例 ID 与项目 pool 信息构建出 Vitest 调度器可消费的规格对象public createSpecification( moduleId: string, locationsOrOptions?: number[] | TestSpecificationOptions | undefined, pool?: string, taskIdOverride?: string, ): TestSpecification { return new TestSpecification( this, moduleId, pool || getFilePoolName(this), locationsOrOptions, taskIdOverride, ) }典型用法在自定义工具或 Reporter 中若需要只重跑某个模块/某几个用例可以用module.toTestSpecification()拿到规格再交给运行调度层处理传入testCases数组即可把范围收窄到指定用例底层按test.id过滤。九、小结与源码索引TestModule是 Vitest 任务体系中最顶层的文件级任务其职责可以概括为三块标识moduleIdVite 模块图 ID与relativeModuleId相对项目路径状态与数据state()含独有的queued、meta()自定义元数据、diagnostic()耗时/内存/worker 诊断、logs()收集期顶层日志调度toTestSpecification()把模块或部分用例包装成可执行的测试规格。它继承自TestSuite因此 TestSuite API 中的children、errors()、options、project、module等能力同样适用。如需继续深入研究类实现与ModuleDiagnostic接口定义packages/vitest/src/node/reporters/reported-tasks.tsTestSpecification的创建入口packages/vitest/src/node/project.ts元数据机制API 高级 · metadataRunner 侧运行时任务API 高级 · runner【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Vitest TestModule 任务 API 详解掌握测试模块的标识、状态与诊断信息【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitestTestModule是 Vitest 测试任务树Task Tree中代表单个项目中的单个测试文件模块的核心类它只在主线程main thread中可用是自定义 Reporter、Test Runner 与各类工具链集成时最常打交道的任务类型之一。本文将基于官方 API 文档并结合 Vitest 仓库源码完整讲解TestModule的type判别、moduleId/relativeModuleId标识体系、viteEnvironment、state()、meta()、diagnostic()、logs()与toTestSpecification()等全部属性与方法读完你可以在自定义 Reporter、Runner 或 CLI 工具中准确读取、过滤并重新调度测试模块。一、TestModule 是什么主线程中的模块级任务TestModule类表示单个项目中的单个测试模块通常对应一个测试文件并且只存在于主线程。如果你在 Runtime 中处理任务应使用 Runner API 中对应的运行时任务类型。在 reported-tasks.ts 源码中TestModule继承自SuiteImplementation并声明了public readonly type module。由于测试任务存在模块module、套件suite、用例test等多种形态官方推荐通过type属性进行运行时判别if (task.type module) { task // TestModule }与之相对TestSuite 的type恒为suite用例的type恒为test。::: warning 继承说明TestModule继承自TestSuite的全部方法与属性如children、errors()、ok()、options、fullName等本文只列出TestModule独有的方法与属性。相关继承能力可参考 TestSuite API。 :::二、模块标识moduleId 与 relativeModuleIdmoduleIdmoduleId是该模块在 ViteModuleGraph中的唯一标识通常是绝对 UNIX 风格路径即使在 Windows 上也是。如果文件不在磁盘上例如虚拟模块它可以是虚拟 IDvirtual id。C:/Users/Documents/project/example.test.ts // ✅ 合法UNIX 风格 /Users/mac/project/example.test.ts // ✅ 合法 C:\\Users\\Documents\\project\\example.test.ts // ❌ 非法反斜杠形式从源码实现看moduleId直接取自底层任务的filepath// packages/vitest/src/node/reporters/reported-tasks.ts this.moduleId task.filepathrelativeModuleIdrelativeModuleId是相对当前项目根目录的模块 ID与旧 API 中的task.name完全一致project/example.test.ts // ✅ 合法 example.test.ts // ✅ 合法 project\\example.test.ts // ❌ 非法反斜杠形式源码中它直接对应底层任务的name字段this.relativeModuleId task.name这两个标识符是构建测试文件过滤、去重、缓存与报告输出的基础例如自定义 Reporter 中常用relativeModuleId展示给用户而用moduleId与 Vite 模块图对齐。三、viteEnvironment模块的 Vite 开发环境版本要求Vitest 4.1.0 起正式提供在 v4.0.15 中以实验性 API 加入。viteEnvironment是用于转换该测试模块内所有文件的 ViteDevEnvironment实例。它是理解 Vitest 环境隔离机制的关键每个测试模块都在特定的 Vite 环境中被转换与执行环境决定了模块可用的插件、解析与转换管线。源码中的对应定义如下注意模块尚未执行时该字段可能为空// packages/vitest/src/node/reporters/reported-tasks.ts public readonly viteEnvironment: DevEnvironment | undefined // 构造函数中按环境名从项目环境中解析 if (typeof task.viteEnvironment string) { this.viteEnvironment project.vite.environments[task.viteEnvironment] }因此当你需要通过编程方式读取某个模块的转换结果、模块图或依赖关系时可以借助viteEnvironment拿到底层环境对象。四、state()查询模块运行状态function state(): TestModuleStatestate()与 TestSuite.state() 工作方式相同可返回pending、failed、passed、skipped区别在于TestModule还可以返回queued表示模块尚未被执行仍在队列中等待调度。源码中的TestModuleState类型在TestSuiteState基础上扩展了queuedexport type TestSuiteState skipped | pending | failed | passed export type TestModuleState TestSuiteState | queued实现逻辑为先读取底层任务的result.state若为queued直接返回否则复用套件状态计算逻辑public state(): TestModuleState { const state this.task.result?.state if (state queued) { return queued } return getSuiteState(this.task) }五、meta()读写模块级自定义元数据版本要求Vitest 3.1.0 起提供。function meta(): TaskMeta返回模块在收集collection或执行execution期间被附加的自定义元数据。元数据的附加方式是在测试运行期间直接给task.meta对象赋值属性。官方文档给出如下示例import { test } from vitest describe(the validation works correctly, (task) { // assign decorated during collection task.file.meta.decorated false test(some test, ({ task }) { // assign decorated during test run, it will be available // only in onTestCaseReady hook task.file.meta.decorated false }) })::: tip 使用时机提示 如果元数据是在收集阶段test函数之外附加的那么它在自定义 Reporter 的onTestModuleCollected钩子中即可读取若是在测试运行期间附加则只能在onTestCaseReady钩子之后才可见。 :::六、diagnostic()模块级性能与资源诊断function diagnostic(): ModuleDiagnostic返回模块的有用诊断信息如耗时、内存占用等。如果模块尚未执行所有诊断值都会返回0。完整的ModuleDiagnostic接口与源码 reported-tasks.ts 定义一致如下interface ModuleDiagnostic { /** * 导入并初始化环境所花费的时间。 */ readonly environmentSetupDuration: number /** * Vitest 搭建测试脚手架runner、mocks 等所花费的时间。 */ readonly prepareDuration: number /** * 导入测试模块所花费的时间。 * 包含导入模块内所有内容以及执行套件回调。 */ readonly collectDuration: number /** * 导入 setup 模块所花费的时间。 */ readonly setupDuration: number /** * 模块内所有测试与钩子的累计耗时。 */ readonly duration: number /** * 模块占用的内存字节数。 * 仅当使用 logHeapUsage 标志执行测试时可用。 */ readonly heap: number | undefined /** * Vitest 处理过的每个非外部化依赖的导入耗时。 */ readonly importDurations: Recordstring, ImportDuration /** * 运行该文件的 worker 的 id。该值不会高于 maxWorkers。 * 如果文件尚未运行该值为 0。 * * 注意Node.js 测试与浏览器测试运行在不同的 pool 中不共享 concurrencyId * 因此可能出现多个模块拥有相同 concurrencyId 的情况。 * 请使用 project.isBrowserEnabled() 加以区分。 */ readonly concurrencyId: number /** * 运行该文件的 worker 的递增编号随每个 worker 增加。 * 如果文件尚未运行该值为 0。 * * 注意Node.js 测试与浏览器测试运行在不同的 pool 中不共享 workerId * 因此可能出现多个模块拥有相同 workerId 的情况。 * 请使用 project.isBrowserEnabled() 加以区分。 */ readonly workerId: number } /** 导入并执行某个非外部化文件所花费的时间。 */ interface ImportDuration { /** 导入并执行该文件本身不计其非外部化导入的时间。 */ selfTime: number /** 导入并执行该文件及其所有导入的时间。 */ totalTime: number }各字段在源码diagnostic()实现中的取值来源非常清晰——它们直接映射到底层任务的不同耗时记录const setupDuration this.task.setupDuration || 0 const collectDuration this.task.collectDuration || 0 const prepareDuration this.task.prepareDuration || 0 const environmentSetupDuration this.task.environmentLoad || 0 const duration this.task.result?.duration || 0 const heap this.task.result?.heap const importDurations this.task.importDurations ?? {}实战建议分析慢测试模块时可对比collectDuration与duration前者代表收集开销后者代表执行开销heap需要配合 logHeapUsage 配置开启后才会有值通过importDurations可以精确定位哪个依赖导入最耗时selfTime是该文件自身耗时totalTime含其全部传递导入是排查启动缓慢的得力工具。七、logs()收集阶段的顶层控制台日志版本要求Vitest 5.0.0 起提供。function logs(): ReadonlyArrayUserConsoleLog返回在测试收集期间、模块顶层记录的 console 日志。注意它只包含模块顶层top level的输出不包含套件回调或测试函数内部的输出console.log(included) // ✅ 会被记录模块顶层 describe(suite, () { console.log(not included) // ❌ 套件回调内 test(test, () { console.log(not included) // ❌ 测试函数内 }) })这与 TestSuite.logs()记录套件及其beforeAll钩子收集期间的日志形成了粒度上的互补模块级只看文件顶层套件级覆盖套件作用域。八、toTestSpecification()生成可执行的测试规格版本要求Vitest 4.1.0 起提供。function toTestSpecification(testCases?: TestCase[]): TestSpecification返回一个新的测试规格TestSpecification可用于过滤或运行这个特定的测试模块。它接受一个可选的测试用例数组用于限定要运行的用例范围。源码实现reported-tasks.ts展示了其内部逻辑它会识别该模块是否为 typecheck 模块meta.typecheck true并调用TestProject.createSpecification生成规格public toTestSpecification(testCases?: TestCase[]): TestSpecification { const isTypecheck this.task.meta.typecheck true return this.project.createSpecification( this.moduleId, testCases?.length ? { testIds: testCases.map(t t.id) } : undefined, isTypecheck ? typecheck : undefined, ) }而createSpecification见 project.ts会结合模块 ID、目标测试用例 ID 与项目 pool 信息构建出 Vitest 调度器可消费的规格对象public createSpecification( moduleId: string, locationsOrOptions?: number[] | TestSpecificationOptions | undefined, pool?: string, taskIdOverride?: string, ): TestSpecification { return new TestSpecification( this, moduleId, pool || getFilePoolName(this), locationsOrOptions, taskIdOverride, ) }典型用法在自定义工具或 Reporter 中若需要只重跑某个模块/某几个用例可以用module.toTestSpecification()拿到规格再交给运行调度层处理传入testCases数组即可把范围收窄到指定用例底层按test.id过滤。九、小结与源码索引TestModule是 Vitest 任务体系中最顶层的文件级任务其职责可以概括为三块标识moduleIdVite 模块图 ID与relativeModuleId相对项目路径状态与数据state()含独有的queued、meta()自定义元数据、diagnostic()耗时/内存/worker 诊断、logs()收集期顶层日志调度toTestSpecification()把模块或部分用例包装成可执行的测试规格。它继承自TestSuite因此 TestSuite API 中的children、errors()、options、project、module等能力同样适用。如需继续深入研究类实现与ModuleDiagnostic接口定义packages/vitest/src/node/reporters/reported-tasks.tsTestSpecification的创建入口packages/vitest/src/node/project.ts元数据机制API 高级 · metadataRunner 侧运行时任务API 高级 · runner【免费下载链接】vitestNext generation testing framework powered by Vite.项目地址: https://gitcode.com/GitHub_Trending/vi/vitest创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
