---
url: /api/advanced/test-module.md
---
# TestModule

`TestModule` 类代表单个项目中的单个模块。此类仅在主线程中可用。如果您正在处理运行时任务，请参阅 ["Runner API"](/api/advanced/runner#tasks)。

`TestModule` 实例始终具有值为 `module` 的 `type` 属性。您可以使用它来区分不同的任务类型：

```ts
if (task.type === 'module') {
  task // TestModule 实例
}
```

::: warning 扩展套件方法
`TestModule` 类继承自 [`TestSuite`](/api/advanced/test-suite) 的所有方法和属性。本指南仅列出 `TestModule` 独有的方法和属性。
:::

## moduleId

这通常是一个绝对的 Unix 文件路径（即使在 Windows 上）。如果文件不在磁盘上，它可能是一个虚拟 id。此值对应于 Vite 的 `ModuleGraph` id。

```ts
'C:/Users/Documents/project/example.test.ts' // ✅
'/Users/mac/project/example.test.ts' // ✅
'C:\\Users\\Documents\\project\\example.test.ts' // ❌
```

## relativeModuleId

相对于项目的模块 ID。这与已弃用 API 中的 `task.name` 相同。

```ts
'project/example.test.ts' // ✅
'example.test.ts' // ✅
'project\\example.test.ts' // ❌
```

## viteEnvironment 4.1.0 {#viteenvironment}

这是一个 Vite 的 [`DevEnvironment`](https://vite.dev/guide/api-environment)，用于转换测试模块中的所有文件。

::: details 历史

* `v4.0.15`：作为实验性功能添加

:::

## state

```ts
function state(): TestModuleState
```

工作方式与 [`testSuite.state()`](/api/advanced/test-suite#state) 相同，但如果模块尚未执行，也可以返回 `queued`。

## 元数据 3.1.0 {#meta}

```ts
function meta(): TaskMeta
```

在模块执行或收集期间附加到模块的自定义 [元数据](/api/advanced/metadata)。可以通过在测试运行期间将属性分配给 `task.meta` 对象来附加元数据：

```ts {5,10}
import { test } from 'vitest'

describe('验证工作正常', (task) => {
  // 在收集期间分配 "decorated"
  task.file.meta.decorated = false

  test('某个测试', ({ task }) => {
    // 在测试运行期间分配 "decorated"，它将可用
    // 仅在 onTestCaseReady 钩子中
    task.file.meta.decorated = false
  })
})
```

:::tip
如果元数据是在收集期间附加的（在 `test` 函数之外），那么它在自定义报告器中的 [`onTestModuleCollected`](./reporters#ontestmodulecollected) 钩子中将可用。
:::

## diagnostic

```ts
function diagnostic(): ModuleDiagnostic
```

关于模块的有用信息，如持续时间、内存使用情况等。如果模块尚未执行，所有诊断值将返回 `0`。

```ts
interface ModuleDiagnostic {
  /**
   * 导入和启动环境所需的时间。
   */
  readonly environmentSetupDuration: number
  /**
   * Vitest 设置测试 harness（运行器、模拟等）所需的时间。
   */
  readonly prepareDuration: number
  /**
   * 导入测试模块所需的时间。
   * 这包括导入模块中的所有内容并执行套件回调。
   */
  readonly collectDuration: number
  /**
   * 导入设置模块所需的时间。
   */
  readonly setupDuration: number
  /**
   * 模块中所有测试和钩子的累计持续时间。
   */
  readonly duration: number
  /**
   * 模块使用的内存量（以字节为单位）。
   * 仅当测试使用 `logHeapUsage` 标志执行时，此值才可用。
   */
  readonly heap: number | undefined
  /**
   * Vitest 处理的每个非外部化依赖项的导入耗时。
   */
  readonly importDurations: Record<string, ImportDuration>
  /**
   * 运行此文件的工作线程的 ID。此值不能高于 `maxWorkers`。
   * 如果文件尚未运行，则此值为 0。
   *
   * **警告**：Node.js 测试和浏览器测试在不同的池中运行，并且不共享 `concurrencyId`。
   * 因此，可能会有多个模块具有相同的 `concurrencyId`。
   * 使用 `project.isBrowserEnabled()` 来区分并发环境。
   */
  readonly concurrencyId: number
  /**
   * 运行此文件的工作线程的递增编号。此编号会随每个工作线程递增。
   * 如果文件尚未运行，则此值为 0。
   *
   * **警告**：Node.js 测试和浏览器测试在不同的池中运行，并且不共享 `workerId`。
   * 因此，可能会有多个模块具有相同的 `workerId`。
   * 使用 `project.isBrowserEnabled()` 来区分并发环境。
   */
  readonly workerId: number
}

/** 导入和执行非外部化文件所花费的时间。 */
interface ImportDuration {
  /** 导入和执行文件本身所花费的时间，不计该文件执行的所有非外部化导入。 */
  selfTime: number

  /** 导入和执行文件及其所有导入所花费的时间。 */
  totalTime: number
}
```

## 日志 5.0.0 {#logs}

```ts
function logs(): ReadonlyArray<UserConsoleLog>
```

测试收集期间在模块顶层记录的控制台日志。例如：

```ts
console.log('included') // [!code highlight]

describe('suite', () => {
  console.log('not included') // [!code error]

  test('test', () => {
    console.log('not included') // [!code error]
  })
})
```

## toTestSpecification 4.1.0 {#totestspecification}

```ts
function toTestSpecification(testCases?: TestCase[]): TestSpecification
```

返回一个新的 [测试规范](/api/advanced/test-specification)，可用于过滤或运行此特定测试模块。

它接受一个可选的测试用例数组进行过滤。