TestSuite

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

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

if (task.type === 'suite') {
  task // 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 {
  readonly each: boolean | undefined
  readonly fails: boolean | undefined
  readonly concurrent: boolean | undefined
  readonly shuffle: boolean | undefined
  readonly retry: number | undefined
  readonly repeats: number | undefined
  readonly mode: 'run' | 'only' | 'skip' | 'todo'
}

收集套件时使用的选项。

children

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

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

WARNING

请注意，suite.children 只会遍历第一层嵌套，不会深入嵌套层次。如果我们需要遍历所有测试或套件，请使用 children.allTests() 或 children.allSuites()。如果我们需要遍历所有内容，请使用递归函数。

function visit(collection: TestCollection) {
  for (const task of collection) {
    if (task.type === 'suite') {
      // 报告套件
      visit(task.children)
    }
    else {
      // 报告测试
    }
  }
}

ok

function ok(): boolean

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

state

function state(): TestSuiteState

检查套件的运行状态。可能的返回值包括：

• pending：此套件中的测试尚未完成运行。
• failed：此套件中有失败的测试或无法收集测试。如果 errors() 不为空，则表示套件未能收集测试。
• passed：此套件中的每个测试均已通过。
• skipped：此套件在收集过程中被跳过。

WARNING

请注意，测试模块 也有一个 state 方法，返回相同的值，但如果模块尚未执行，它还可以返回一个额外的 queued 状态。

errors

function errors(): TestError[]

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

import { describe } from 'vitest'

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

WARNING

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

meta 3.1.0+

function meta(): TaskMeta

在执行或收集过程中附加到套件的自定义元数据。在测试运行期间，可以通过向 task.meta 对象分配属性来附加 meta：

import { test } from 'vitest'

describe('the validation works correctly', (task) => {
  // 在收集过程中指定 “decorated”
  task.meta.decorated = false

  test('some test', ({ task }) => {
    // 在试运行期间指定 “decorated”，它将可用
    // 仅在 onTestCaseReady hook
    task.suite.meta.decorated = false
  })
})

TIP

如果元数据是在收集阶段（而非 test 函数内部）附加的，那么它将在 available 的 onTestModuleCollected 中可用。