TestSuite

TestSuite 类表示一个单一的套件。此类仅在主线程中可用。如果你正在处理运行时任务，请参阅 “Runner API”。

TestSuite 实例始终具有一个 type 属性，其值为 suite。你可以使用它来区分不同的任务类型：

if (task.type === 'suite') {
  task // TestSuite
}

WARNING

我们计划引入一个新的 Reporter API，默认将使用此 API。目前，Reporter API 使用 runner tasks，但你仍然可以通过 vitest.state.getReportedEntity 方法访问 TestSuite：

import type { RunnerTestFile, TestModule, Vitest } from 'vitest/node'

class Reporter {
  private vitest!: Vitest

  onInit(vitest: Vitest) {
    this.vitest = vitest
  }

  onFinished(files: RunnerTestFile[]) {
    for (const file of files) {
      const testModule = this.vitest.state.getReportedEntity(file) as TestModule
      for (const suite of testModule.children.allSuites()) {
        console.log(suite) // TestSuite
      }
    }
  }
}

project

这引用了测试所属的 TestProject。

module

这是对定义测试的 TestModule 的直接引用。

name

这是传递给 describe 函数的套件名称。

import { describe } from 'vitest'

describe('the validation logic', () => {
  // ...
})

fullName

包括所有父级套件名称并用 > 符号分隔的套件名称。此套件的完整名称为 "the validation logic > validating cities"：

import { describe, test } from 'vitest'

describe('the validation logic', () => {
  describe('validating cities', () => {
    // ...
  })
})

id

这是套件的唯一标识符。此 ID 是确定性的，在多次运行中相同的套件将具有相同的 ID。ID 基于 项目 名称、模块 ID 和套件顺序。

ID 的格式如下：

1223128da3_0_0_0
^^^^^^^^^^ the file hash
           ^ suite index
             ^ nested suite index
               ^ test index

TIP

你可以使用 vitest/node 中的 generateFileHash 函数生成文件哈希，该函数自 Vitest 3 起可用：

import { generateFileHash } from 'vitest/node'

const hash = generateFileHash(
  '/file/path.js', // relative path
  undefined, // the project name or `undefined` is not set
)

DANGER

不要尝试解析 ID。它可能以减号开头，例如：-1223128da3_0_0_0。

location

套件在模块中定义的位置。仅当配置中启用了 includeTaskLocation 时才会收集位置信息。请注意，如果使用了 --reporter=html、--ui 或 --browser 标志，此选项会自动启用。

此套件的位置将等于 { line: 3, column: 1 }：

import { describe } from 'vitest'

describe('the validation works correctly', () => {
  // ...
})

parent

父级套件。如果套件是在 模块 内直接调用的，则父级将是模块本身。

options

interface TaskOptions {
  each: boolean | undefined
  concurrent: boolean | undefined
  shuffle: boolean | undefined
  retry: number | undefined
  repeats: number | undefined
  mode: 'run' | 'only' | 'skip' | 'todo'
}

收集套件时使用的选项。

children

这是当前套件内所有套件和测试的 集合。

for (const task of suite.children) {
  if (task.type === 'test') {
    console.log('test', task.fullName)
  }
  else {
    // task is TaskSuite
    console.log('suite', task.name)
  }
}

WARNING

请注意，suite.children 只会迭代第一层嵌套，不会深入更多层次。

ok

function ok(): boolean

检查套件中是否有任何失败的测试。如果套件在收集过程中失败，这也将返回 false。在这种情况下，请检查 errors() 以获取抛出的错误。

skipped

function skipped(): boolean

检查套件在收集过程中是否被跳过。

errors

function errors(): TestError[]

在收集过程中发生的、测试运行之外的错误，例如语法错误。

import { describe } from 'vitest'

describe('collection failed', () => {
  throw new Error('a custom error')
})

WARNING

请注意，错误被序列化为简单对象：instanceof Error 始终返回 false。