TestSuite

TestSuite 类代表一个测试套件。该类仅在主线程中可用。如果处理运行时任务，请参考 "Runner API"。

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

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

project

这引用了测试所属的 TestProject 实例。

module

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

name

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

import { describe } from 'vitest';

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

fullName

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

import { describe, test } from 'vitest';

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

id

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

ID 看起来像这样：

1223128da3_0_0_0
^^^^^^^^^^ 文件哈希
           ^ 套件索引
             ^ 嵌套套件索引
               ^ 测试索引

TIP

您可以使用 Vitest 3 中提供的 vitest/node 的 generateFileHash 函数生成文件哈希：

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 { 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 {
    // task 为 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 对象来附加：

import { test } from 'vitest';

describe('the validation works correctly', task => {
  // 在收集期间分配 "decorated"
  task.meta.decorated = false;

  test('some test', ({ task }) => {
    // 在测试运行期间分配 "decorated"，它将仅在 onTestCaseReady 钩子中可用
    task.suite.meta.decorated = false;
  });
});

TIP

如果元数据是在收集期间（在 test 函数之外）附加的，那么它将在自定义报告器中的 onTestModuleCollected 钩子中可用。