はじめに

概要

Vitest（「ヴァイテスト」と発音）は、Vite を基盤とした次世代のテストフレームワークです。

このプロジェクトの背景や設計思想については、Vitest を選ぶ理由セクションで詳しく学ぶことができます。

Vitest をオンラインで試す

StackBlitz で Vitest をオンラインで試すことができます。Vitest はブラウザ上で直接実行され、ローカル環境とほぼ同じように動作しますが、PC に何もインストールする必要はありません。

プロジェクトに Vitest を追加する

ビデオでインストール方法を学ぶ

npm

npm install -D vitest

yarn

yarn add -D vitest

pnpm

pnpm add -D vitest

bun

bun add -D vitest

TIP

Vitest は Vite v5.0.0 以降および Node v18.0.0 以降を必要とします。

上記いずれかの方法で vitest パッケージを package.json にインストールすることを推奨します。ただし、vitest を直接実行したい場合は、npx vitest を使用できます（npx ツールは npm および Node.js に付属しています）。

npx ツールは指定されたコマンドを実行します。デフォルトでは、npx はまずローカルプロジェクトのバイナリ内にコマンドがあるかを確認します。見つからない場合は、システムの $PATH を探し、見つかれば実行します。いずれの場所にもコマンドが見つからない場合、npx は実行前に一時的な場所にインストールします。

テストの記述

例として、2つの数値を加算する関数の出力が正しいことを検証する簡単なテストを作成します。

// sum.js
export function sum(a, b) {
  return a + b;
}

// sum.test.js
import { expect, test } from 'vitest';
import { sum } from './sum.js';

test('adds 1 + 2 to equal 3', () => {
  expect(sum(1, 2)).toBe(3);
});

TIP

デフォルトでは、テストファイル名に ".test." または ".spec." を含む必要があります。

次に、テストを実行するために、package.json に以下のセクションを追加します。

{
  "scripts": {
    "test": "vitest"
  }
}

最後に、使用しているパッケージマネージャーに応じて npm run test、yarn test、または pnpm test を実行すると、Vitest は次のメッセージを出力します。

✓ sum.test.js (1)
  ✓ adds 1 + 2 to equal 3

Test Files  1 passed (1)
     Tests  1 passed (1)
  Start at  02:15:44
  Duration  311ms

WARNING

パッケージマネージャーとして Bun を使用している場合、bun test ではなく bun run test コマンドを使用してください。そうしない場合、Bun 独自のテストランナーが実行されます。

Vitest の使用方法の詳細については、API セクションを参照してください。

Vitest の設定

Vitest の主なメリットの一つは、Vite との統合設定です。Vitest は、存在すればルートの vite.config.ts を読み込み、Vite アプリケーションのプラグインや設定に合わせます。例えば、Vite の resolve.alias および plugins 設定は、そのまま機能します。テスト時に別の設定が必要な場合は、以下の方法があります。

• vitest.config.ts を作成する（こちらが優先されます）
• CLI に --config オプションを渡す（例: vitest --config ./path/to/vitest.config.ts）
• defineConfig の process.env.VITEST または mode プロパティを使用する（上書きされない場合は test に設定されます）ことで、vite.config.ts で条件付きで異なる設定を適用する

Vitest は、Vite と同じ設定ファイルの拡張子として、.js、.mjs、.cjs、.ts、.cts、.mts をサポートしています。Vitest は .json 拡張子をサポートしていません。

Vite をビルドツールとして使用していない場合でも、設定ファイルの test プロパティを使用して Vitest を設定できます。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    // ...
  },
});

TIP

Vite を直接使用していなくても、Vitest はその変換パイプラインのために Vite に強く依存しています。そのため、Vite ドキュメントに記載されている任意のプロパティも設定できます。

すでに Vite を使用している場合は、Vite の設定に test プロパティを追加します。また、設定ファイルの先頭にトリプルスラッシュディレクティブを使用して Vitest の型への参照を追加する必要があります。

/// <reference types="vitest" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ...
  },
});

<reference types="vitest" /> は Vitest 3 では機能しなくなりますが、Vitest 2.1 から vitest/config への移行を開始できます。

/// <reference types="vitest/config" />
import { defineConfig } from 'vite';

export default defineConfig({
  test: {
    // ... オプションをここに指定します。
  },
});

設定オプションのリストについては、設定リファレンスを参照してください。

WARNING

Vite と Vitest で設定ファイルを分ける場合、Vitest の設定ファイルは Vite のファイルを上書きし、拡張しないため、同じ Vite オプションを Vitest の設定ファイルで定義するようにしてください。また、vite または vitest/config から mergeConfig メソッドを使用して、Vite の設定と Vitest の設定をマージすることもできます。

vitest.config.mjs

import { defineConfig, mergeConfig } from 'vitest/config';
import viteConfig from './vite.config.mjs';

export default mergeConfig(
  viteConfig,
  defineConfig({
    test: {
      // ...
    },
  })
);

vite.config.mjs

import { defineConfig } from 'vite';
import Vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [Vue()],
});

ただし、ファイルを分けるのではなく、Vite と Vitest の両方に同じファイルを使用することをお勧めします。

ワークスペースのサポート

同じプロジェクト内で異なるプロジェクト設定をVitest Workspacesで実行できます。vitest.workspace ファイルで、ワークスペースを定義するファイルやフォルダーのリストを定義できます。このファイルは .js、.ts、.json 拡張子をサポートしています。この機能はモノレポのセットアップに非常に有効です。

import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  // ワークスペースを定義するためにグロブパターンのリストを使用できます。
  // Vitest は設定ファイルのリスト、または設定ファイルがあるディレクトリを想定しています。
  'packages/*',
  'tests/*/vitest.config.{e2e,unit}.ts',
  // 同じ `vitest` プロセス内で、
  // 異なる設定で同じテストを実行することもできます。
  {
    test: {
      name: 'happy-dom',
      root: './shared_tests',
      environment: 'happy-dom',
      setupFiles: ['./setup.happy-dom.ts'],
    },
  },
  {
    test: {
      name: 'node',
      root: './shared_tests',
      environment: 'node',
      setupFiles: ['./setup.node.ts'],
    },
  },
]);

コマンドラインインターフェース

Vitest がインストールされているプロジェクトでは、npm スクリプトで vitest バイナリを使用するか、npx vitest で直接実行できます。スキャフォールドされたVitestプロジェクトのデフォルトのnpmスクリプトは以下の通りです。

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

ファイルの変更を監視せずに一度だけテストを実行するには、vitest run を使用します。 --port や --https などの追加の CLI オプションを指定できます。CLI オプションの完全なリストについては、プロジェクトで npx vitest --help を実行してください。

コマンドラインインターフェースの詳細はこちら

自動依存関係インストール

Vitest は、特定の依存関係がまだインストールされていない場合に、それらをインストールするように促します。この動作は、VITEST_SKIP_INSTALL_CHECKS=1 環境変数を設定することで無効にすることができます。

IDE 統合

Vitest のテスト体験を向上させるために、Visual Studio Code 用の公式拡張機能も提供しています。

VS Code Marketplace からインストール

IDE 統合の詳細はこちら

例

例	ソース	プレイグラウンド
basic	GitHub	Play Online
fastify	GitHub	Play Online
in-source-test	GitHub	Play Online
lit	GitHub	Play Online
vue	GitHub	Play Online
marko	GitHub	Play Online
preact	GitHub	Play Online
react	GitHub	Play Online
solid	GitHub	Play Online
svelte	GitHub	Play Online
sveltekit	GitHub	Play Online
profiling	GitHub	利用不可
typecheck	GitHub	Play Online
workspace	GitHub	Play Online

Vitest を使用しているプロジェクト

• unocss
• unplugin-auto-import
• unplugin-vue-components
• vue
• vite
• vitesse
• vitesse-lite
• fluent-vue
• vueuse
• milkdown
• gridjs-svelte
• spring-easing
• bytemd
• faker
• million
• Vitamin
• neodrag
• svelte-multiselect
• iconify
• tdesign-vue-next
• cz-git

未リリースコミットの使用

メインブランチの各コミットと cr-tracked ラベルが付いた PR は、pkg.pr.new に公開されます。npm i https://pkg.pr.new/vitest@{commit} でインストールできます。

ローカルで独自の修正をテストしたい場合は、自分でビルドしてリンクできます（pnpm が必要です）。

git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # このステップではお好みのパッケージマネージャーを使用できます

次に、Vitest を使用しているプロジェクトに移動し、pnpm link --global vitest を実行します（または、vitest をグローバルにリンクするために使用したパッケージマネージャーを使用します）。

コミュニティ

ご質問やサポートが必要な場合は、Discord および GitHub Discussions のコミュニティにお問い合わせください。