Skip to content

TestSuite

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

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

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

WARNING

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

ts
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 函数的套件名称。

ts
import { describe } from 'vitest'

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

fullName

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

ts
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 起可用:

ts
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 }

ts
import { describe } from 'vitest'

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

parent

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

options

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

收集套件时使用的选项。

children

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

ts
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

ts
function ok(): boolean

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

skipped

ts
function skipped(): boolean

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

errors

ts
function errors(): TestError[]

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

ts
import { describe } from 'vitest'

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

WARNING

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

Released under the MIT License.