TestProject 3.0.0+

WARNING

本指南說明進階的 Node.js API。如果您僅需定義專案，請參閱「測試專案」指南。

name

名稱是一個由使用者指定或由 Vitest 解析的唯一字串。若使用者未提供名稱，Vitest 會嘗試在專案根目錄中載入 package.json 並取得其 name 屬性。如果沒有 package.json，Vitest 預設會使用資料夾的名稱。行內專案則使用數字作為名稱（轉換為字串）。

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.projects.map(p => p.name) === ['@pkg/server', 'utils', '2', 'custom'];

vitest.config.js

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // 包含 package.json，其中有 "@pkg/server"
      './utils', // 沒有 package.json 檔案
      {
        // 不自訂名稱
        test: {
          pool: 'threads',
        },
      },
      {
        // 自訂名稱
        test: {
          name: 'custom',
        },
      },
    ],
  },
});

INFO

如果根專案不屬於使用者專案的一部分，則其 name 將不會被解析。

vitest

vitest 參考全域的 Vitest 實例。

serializedConfig

這是測試程序接收的配置。Vitest 會手動序列化配置，移除所有無法序列化的函數和屬性。由於此值在測試環境和 Node.js 環境中皆可使用，其類型會從主入口點匯出。

import type { SerializedConfig } from 'vitest';

const config: SerializedConfig = vitest.projects[0].serializedConfig;

WARNING

serializedConfig 屬性是一個 getter。每次存取時，Vitest 都會重新序列化配置，以防其已變更。這也表示它總是返回不同的參考：

project.serializedConfig === project.serializedConfig; // ❌

globalConfig

初始化 Vitest 時的測試配置。如果這是根專案，globalConfig 和 config 將指向相同的物件。此配置對於無法在專案層級設定的值很有用，例如 coverage 或 reporters。

import type { ResolvedConfig } from 'vitest/node';

vitest.config === vitest.projects[0].globalConfig;

config

這是專案解析後的測試配置。

hash 3.2.0+

此專案的唯一雜湊碼。此值在重新執行時保持一致。

它基於專案的根目錄及其名稱。請注意，根路徑在不同作業系統之間可能不一致，因此雜湊碼也會有所不同。

vite

這是專案的 ViteDevServer 實例。所有專案都有其獨立的 Vite 伺服器。

browser

此值僅在測試於瀏覽器中執行時設定。如果 browser 已啟用，但測試尚未執行，則此值將為 undefined。如果您需要檢查專案是否支援瀏覽器測試，請使用 project.isBrowserEnabled() 方法。

WARNING

瀏覽器 API 仍處於實驗階段，不遵循 SemVer。瀏覽器 API 將與其他 API 分開標準化。

provide

function provide<T extends keyof ProvidedContext & string>(
  key: T,
  value: ProvidedContext[T]
): void;

除了 config.provide 欄位外，此方法還能為測試提供自訂值。所有值在儲存之前都會使用 structuredClone 進行驗證，但 providedContext 本身的值不會被複製。

node.js

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');
await vitest.start();

test.spec.js

import { inject } from 'vitest';
const value = inject('key');

這些值可以動態提供。測試中提供的值將在下次執行時更新。

TIP

此方法也適用於全域設定檔，適用於無法使用公開 API 的情況：

export default function setup({ provide }) {
  provide('wsPort', 3000);
}

getProvidedContext

function getProvidedContext(): ProvidedContext;

此方法會回傳上下文物件。每個專案也會繼承由 vitest.provide 設定的全域上下文。

import { createVitest } from 'vitest/node';

const vitest = await createVitest('test');
vitest.provide('global', true);
const project = vitest.projects.find(p => p.name === 'custom');
project.provide('key', 'value');

// { global: true, key: 'value' }
const context = project.getProvidedContext();

TIP

專案上下文值將始終覆寫根專案的上下文。

createSpecification

function createSpecification(
  moduleId: string,
  locations?: number[]
): TestSpecification;

建立一個可用於 vitest.runTestSpecifications 的測試規格。規格會將測試檔案限定於特定的 project 和可選的測試 locations。測試位置是原始碼中定義測試的程式碼行。如果提供了位置，Vitest 將只執行在這些行上定義的測試。請注意，如果定義了 testNamePattern，則也會應用它。

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];
const specification = project.createSpecification(
  resolve('./example.test.ts'),
  [20, 40] // 可選的測試行
);
await vitest.runTestSpecifications([specification]);

WARNING

createSpecification 預期已解析的模組 ID。它不會自動解析檔案，也不會檢查檔案系統上是否存在。

另請注意，project.createSpecification 總是返回一個新實例。

isRootProject

function isRootProject(): boolean;

檢查目前專案是否為根專案。您也可以透過呼叫 vitest.getRootProject() 取得根專案。

globTestFiles

function globTestFiles(filters?: string[]): {
  /**
   * 符合篩選條件的測試檔案。
   */
  testFiles: string[];
  /**
   * 符合篩選條件的類型檢查測試檔案。除非 `typecheck.enabled` 為 `true`，否則此為空。
   */
  typecheckTestFiles: string[];
};

全域搜尋所有測試檔案。此函式會回傳一個包含一般測試和類型檢查測試的物件。

此方法接受 filters 參數。篩選條件只能是檔案路徑的一部分，與 Vitest 實例上的其他方法不同：

project.globTestFiles(['foo']); // ✅
project.globTestFiles(['basic/foo.js:10']); // ❌

TIP

Vitest 使用 fast-glob 來尋找測試檔案。test.dir、test.root、root 或 process.cwd() 定義 cwd 選項。

此方法會查看多個設定選項：

• test.include、test.exclude 用於尋找一般測試檔案
• test.includeSource、test.exclude 用於尋找行內測試
• test.typecheck.include、test.typecheck.exclude 用於尋找類型檢查測試

matchesTestGlob

function matchesTestGlob(moduleId: string, source?: () => string): boolean;

此方法會檢查檔案是否為一般測試檔案。它使用與 globTestFiles 相同的設定屬性進行驗證。

此方法也接受第二個參數，即原始碼。這用於驗證檔案是否為行內測試。如果您多次為多個專案呼叫此方法，建議一次讀取檔案並直接傳遞。如果檔案不是測試檔案，但符合 includeSource 全域模式，Vitest 將同步讀取檔案，除非提供了 source。

import { createVitest } from 'vitest/node';
import { resolve } from 'node:path/posix';

const vitest = await createVitest('test');
const project = vitest.projects[0];

project.matchesTestGlob(resolve('./basic.test.ts')); // true
project.matchesTestGlob(resolve('./basic.ts')); // false
project.matchesTestGlob(
  resolve('./basic.ts'),
  () => `
if (import.meta.vitest) {
  // ...
}
`
); // 如果設定了 `includeSource` 則為 true

import

function import<T>(moduleId: string): Promise<T>

使用 Vite 模組執行器匯入檔案。檔案將由 Vite 使用提供的專案設定進行轉換，並在單獨的上下文中執行。請注意，moduleId 將相對於 config.root。

DANGER

project.import 複用 Vite 的模組圖，因此使用常規匯入匯入相同的模組將回傳不同的模組：

import * as staticExample from './example.js';
const dynamicExample = await project.import('./example.js');

dynamicExample !== staticExample; // ✅

INFO

在內部，Vitest 使用此方法匯入全域設定、自訂覆蓋率提供者和自訂報告器，這表示只要它們屬於同一個 Vite 伺服器，它們就共享相同的模組圖。

onTestsRerun

function onTestsRerun(cb: OnTestsRerunHandler): void;

這是 project.vitest.onTestsRerun 的簡寫。它接受一個回調函數，當測試被排程重新執行時（通常是由於檔案變更），該回調函數將被等待。

project.onTestsRerun(specs => {
  console.log(specs);
});

isBrowserEnabled

function isBrowserEnabled(): boolean;

如果此專案在瀏覽器中執行測試，則返回 true。

close

function close(): Promise<void>;

關閉專案和所有相關資源。此方法只能呼叫一次；關閉承諾會被快取，直到伺服器重新啟動。如果再次需要資源，請建立一個新專案。

具體來說，此方法會關閉 Vite 伺服器、停止類型檢查服務、關閉瀏覽器（如果正在執行）、刪除包含原始碼的臨時目錄，並重設提供的上下文。