TestCase

TestCase 類別代表單一測試。此類別僅在主執行緒中可用。若您正在處理執行時任務，請參閱「執行器 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 基於專案 (project) 名稱、模組 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

此屬性為父測試套件 (suite)。若測試直接在模組 (module) 內部呼叫，則父級將是模組本身。

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。

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。

TestCase ​

project ​

module ​

name ​

fullName ​

id ​

location ​

parent ​

options ​

ok ​

meta ​

result ​

diagnostic ​