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/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 { 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 is 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 鉤子中可用。