TestProject 3.0.0+

WARNING

このガイドでは、Vitest の高度な Node.js API について説明します。単にプロジェクトを定義したい場合は、「テストプロジェクト」ガイドを参照してください。

name

name は、ユーザーが割り当てるか、Vitest が決定する一意の文字列です。ユーザーが名前を指定しなかった場合、Vitest はプロジェクトのルートにある package.json を読み込み、その name プロパティを取得しようとします。package.json が存在しない場合、Vitest はデフォルトでフォルダー名を使用します。インラインで定義されたプロジェクトの場合、名前には数字が使用されます（文字列に変換されます）。

node.jsvitest.config.js

import { createVitest } from 'vitest/node';

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

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    projects: [
      './packages/server', // "@pkg/server" を含む package.json がある
      './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 プロパティはゲッターです。アクセスされるたびに、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+

このプロジェクトの一意のハッシュ値です。この値は再実行時にも一貫性があります。

プロジェクトのルートとその名前に基づいています。ルートパスは異なる OS 間で一貫性がないため、ハッシュも異なります。

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.jstest.spec.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();

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 が使用するのと同じ設定プロパティを使用します。

このメソッドは、ソースコードである2番目のパラメータも受け入れます。これは、ファイルがインソーステストであるかどうかを検証するために使用されます。複数のプロジェクトに対してこのメソッドを複数回呼び出す場合は、ファイルを一度読み込んで直接渡すことをお勧めします。ファイルがテストファイルではないが、includeSource グロブに一致する場合、source が提供されない限り、Vitest はファイルを同期的に読み取ります。

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 サーバーを閉じ、型チェッカーサービスを停止し、実行中の場合はブラウザを閉じ、ソースコードを保持する一時ディレクトリを削除し、提供されたコンテキストをリセットします。

TestProject 3.0.0+ ​

name ​

vitest ​

serializedConfig ​

globalConfig ​

config ​

hash 3.2.0+ ​

vite ​

browser ​

provide ​

getProvidedContext ​

createSpecification ​

isRootProject ​

globTestFiles ​

matchesTestGlob ​

import ​

onTestsRerun ​

isBrowserEnabled ​

close ​

TestProject 3.0.0+

name

vitest

serializedConfig

globalConfig

config

hash 3.2.0+

vite

browser

provide

getProvidedContext

createSpecification

isRootProject

globTestFiles

matchesTestGlob

import

onTestsRerun

isBrowserEnabled

close