TestCase

TestCase 类代表一个独立的测试。该类仅在主线程中可用。如果你正在处理运行时任务，请参考 "Runner API"。

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

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

project

这指的是测试所属的 TestProject 实例。

module

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

name

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

import { test } from 'vitest';

// [!code word:'the validation works correctly']
test('the validation works correctly', () => {
  // ...
});

fullName

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

import { describe, test } from 'vitest';

// [!code word:'the validation works correctly']
// [!code word:'the validation logic']
describe('the validation logic', () => {
  test('the validation works correctly', () => {
    // ...
  });
});

id

这是测试的唯一标识符。此 ID 是确定性的，对于同一个测试在多次运行中将保持不变。ID 基于 项目 名称、模块 ID 和测试顺序生成。

ID 的格式如下：

1223128da3_0_0
^^^^^^^^^^ 文件哈希值
           ^ 套件索引
             ^ 测试索引

TIP

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

import { generateFileHash } from 'vitest/node';

const hash = generateFileHash(
  '/file/path.js', // 相对路径
  undefined // 项目名称，如果未设置则为 `undefined`。
);

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

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

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';
}

用于收集测试的选项。

ok

function ok(): boolean;

检查测试是否未导致套件失败。如果测试尚未完成或已被跳过，则返回 true。

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;

测试结果。若测试未完成或刚被收集，则其将等于 TestResultPending：

export interface TestResultPending {
  /**
   * 测试已被收集但尚未完成运行。
   */
  readonly state: 'pending';
  /**
   * 待处理测试没有错误。
   */
  readonly errors: undefined;
}

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

interface TestResultSkipped {
  /**
   * 测试被 `skip` 或 `todo` 标记跳过。
   * 可通过 `options.mode` 选项查看使用了哪个标记。
   */
  readonly state: 'skipped';
  /**
   * 跳过的测试无错误。
   */
  readonly errors: undefined;
  /**
   * 传递给 `ctx.skip(note)` 的自定义注释。
   */
  readonly note: string | undefined;
}

TIP

若因其他测试带有 only 标记而被跳过，options.mode 将等于 skip。

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

interface TestResultFailed {
  /**
   * 测试执行失败。
   */
  readonly state: 'failed';
  /**
   * 测试执行期间抛出的错误。
   */
  readonly errors: ReadonlyArray<TestError>;
}

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

interface TestResultPassed {
  /**
   * 测试成功通过。
   */
  readonly state: 'passed';
  /**
   * 测试执行期间抛出的错误。
   */
  readonly errors: ReadonlyArray<TestError> | undefined;
}

WARNING

注意：状态为 passed 的测试仍可能包含错误——当至少触发一次 retry 时可能出现这种情况。

diagnostic

function diagnostic(): TestDiagnostic | undefined;

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

interface TestDiagnostic {
  /**
   * 若测试持续时间超过 `slowTestThreshold`。
   */
  readonly slow: boolean;
  /**
   * 测试占用的内存量（字节）。
   * 该值仅在测试以 `logHeapUsage` 标记执行时可用。
   */
  readonly heap: number | undefined;
  /**
   * 测试执行耗时（毫秒）。
   */
  readonly duration: number;
  /**
   * 测试开始时间（毫秒）。
   */
  readonly startTime: number;
  /**
   * 测试重试次数。
   */
  readonly retryCount: number;
  /**
   * 按 `repeats` 选项配置的测试重复次数。
   * 若测试在重复期间失败且未配置 `retry`，该值可能更小。
   */
  readonly repeatCount: number;
  /**
   * 若测试在第二次重试时通过。
   */
  readonly flaky: boolean;
}

INFO

若测试尚未安排运行，diagnostic() 将返回 undefined。