TestCase

TestCase 类表示单个测试。此类仅在主线程中可用。如果您正在处理运行时任务，请参阅“Runner API”。

TestCase 实例始终有一个值为 test 的 type 属性。您可以使用它来区分不同的任务类型：

if (task.type === 'test') {
  task // TestCase
}

WARNING

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

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.getReportedEntity(file) as TestModule
      for (const test of testModule.children.allTests()) {
        console.log(test) // TestCase
      }
    }
  }
}

project

这引用了测试所属的 TestProject。

module

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

name

这是传递给 test 函数的测试名称。

import { test } from 'vitest'

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

fullName

包括所有父套件并用 > 符号分隔的测试名称。此测试的完整名称为 "the validation logic > the validation works correctly"：

import { describe, test } from 'vitest'

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

id

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

ID 的格式如下：

1223128da3_0_0
^^^^^^^^^^ the file hash
           ^ 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 { test } from 'vitest'

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

parent

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

options

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

收集测试时使用的选项。

ok

function ok(): boolean

检查测试是否未使套件失败。如果测试尚未完成或被跳过，它将返回 true。

skipped

function skipped(): boolean

检查测试是否在收集期间或通过 ctx.skip() 动态跳过。

meta

function meta(): TaskMeta

在测试执行期间附加的自定义元数据。可以通过在测试运行期间将属性赋值给 ctx.task.meta 对象来附加元数据：

import { test } from 'vitest'

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

  task.meta.decorated = false
})

如果测试尚未完成运行，元数据将是一个空对象。

result

function result(): TestResult | undefined

测试结果。如果测试在收集期间被跳过、尚未完成或只是被收集，则结果将为 undefined。

如果测试被跳过，返回值将是 TestResultSkipped：

interface TestResultSkipped {
  /**
   * The test was skipped with `skip` or `todo` flag.
   * You can see which one was used in the `options.mode` option.
   */
  state: 'skipped'
  /**
   * Skipped tests have no errors.
   */
  errors: undefined
  /**
   * A custom note passed down to `ctx.skip(note)`.
   */
  note: string | undefined
}

TIP

如果测试因为其他测试有 only 标志而被跳过，则 options.mode 将等于 skip。

如果测试失败，返回值将是 TestResultFailed：

interface TestResultFailed {
  /**
   * The test failed to execute.
   */
  state: 'failed'
  /**
   * Errors that were thrown during the test execution.
   */
  errors: TestError[]
}

如果测试通过，返回值将是 TestResultPassed：

interface TestResultPassed {
  /**
   * The test passed successfully.
   */
  state: 'passed'
  /**
   * Errors that were thrown during the test execution.
   */
  errors: TestError[] | undefined
}

WARNING

请注意，状态为 passed 的测试仍可能附带有错误——如果 retry 至少触发了一次，这种情况就可能发生。

diagnostic

function diagnostic(): TestDiagnostic | undefined

有关测试的有用信息，例如持续时间、内存使用等：

interface TestDiagnostic {
  /**
   * If the duration of the test is above `slowTestThreshold`.
   */
  slow: boolean
  /**
   * The amount of memory used by the test in bytes.
   * This value is only available if the test was executed with `logHeapUsage` flag.
   */
  heap: number | undefined
  /**
   * The time it takes to execute the test in ms.
   */
  duration: number
  /**
   * The time in ms when the test started.
   */
  startTime: number
  /**
   * The amount of times the test was retried.
   */
  retryCount: number
  /**
   * The amount of times the test was repeated as configured by `repeats` option.
   * This value can be lower if the test failed during the repeat and no `retry` is configured.
   */
  repeatCount: number
  /**
   * If test passed on a second retry.
   */
  flaky: boolean
}