vitest

Vitest

Vite を基盤とする次世代テストフレームワークです。

クイックナビゲーション

• テスト API - test、describe、フック
• Expect API - マッチャーとアサーション
• モック - vi.fn、vi.mock、フェイクタイマー
• 設定 - vitest.config.ts のオプション
• CLI - コマンドラインリファレンス
• ブラウザモード - 実ブラウザでのテスト

使用する場面

• Vite ベースのアプリケーションのテスト（設定を共有）
• ネイティブ ESM をサポートする Jest 互換 API が必要な場合
• 実ブラウザでのコンポーネントテスト
• HMR に対応した高速なウォッチモード
• 追加設定なしでの TypeScript テスト
• テストの並列実行

インストール

インストール：npm install -D vitest。Node.js >=22 と、v5 では Vite >=6.4 が必要です。

リリースの主な変更点（5.0.0）

• 要件： Node.js >=22 と Vite >=6.4 が必要です。@vitest/runner がインライン化され（パッケージは公開されなくなりました）、expect もインライン化されたため、古いエントリポイントは削除されました。
• モック／タイマーの動作： 各テストの前にモックがデフォルトでクリアされるようになり、フェイクタイマーの有無にかかわらず Temporal をモックできるようになりました。
• API の置き換え： テスト／スイートの sequential オプションは削除され、concurrent に置き換えられました。ブラウザプロバイダーの webdriverio は削除されました。toHaveTextContent は厳密な動作になり、代替として toMatchTextContent が用意されました。関数が時間内に解決しない場合、expect.poll は失敗します。
• 新しいデフォルト／出力： attachmentsDir のデフォルトが .vitest-attachments/ から .vitest/attachments/ に変更され、blob/json/junit/html レポーターの出力先のデフォルトが .vitest になりました。また、createReport API と .vitest レポートディレクトリの規約が導入されました。
• プロジェクト： インラインプロジェクトはデフォルトでルート設定を拡張し、ネストされたプロジェクトがサポートされます。異なるプロジェクトは 1 つの Vite サーバーを共有し、設定ファイルは親ディレクトリから検索されなくなりました（親ディレクトリの設定は適用されません）。
• ブラウザ： ロケーター文字列はロケーターオブジェクトに置き換えられ、locators.exact がデフォルトで有効になりました。また、screenshotDirectory 設定で toMatchScreenshot の出力先を制御できます。
• その他： ベンチマークの公開 API が、プラグイン可能なプロバイダー API を備えた形に書き換えられました。-p は --project の短縮形です。-t の区切り文字に > が使われます。カバレッジの thresholds.perFile でオブジェクトを指定できるようになり、TypeScript のビルドモードと vitest list の静的解析がサポートされました。

リリースの主な変更点（4.1.0 → 4.1.6）

• 新しい制御フローフック：aroundEach と aroundAll。
• テストメタデータが拡張され、タグと meta が追加され、test.extend の型推論も改善されました。
• CLI に --detect-async-leaks、より多彩な --update モード、vitest list の静的なテスト収集が追加されました。
• ブラウザモードで Playwright の永続コンテキスト、userEvent.wheel、強化されたトレース／成果物処理がサポートされました。
• モック／タイマーに、破棄可能な doMock()、mockThrow／mockThrowOnce、setTickMode が追加されました。
• 4.1.4 では、実験的な ARIA スナップショット、JSON レポーター用の filterMeta が追加され、assertion が実験的な公開フィールドとして公開されました。
• 4.1.5 では、カバレッジの instrumenter がサポートされ、大きなスナップショットや HTML 出力に関するレポーター／UI の動作が改善されました。
• 4.1.6 では、ブラウザのスクリーンショットパス解決が厳密になり、並行テストのスケジューリングにおける sequence.concurrent の処理が修正されました。

クイックスタート

// 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);
});

// package.json
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "coverage": "vitest run --coverage"
  }
}

設定

// vitest.config.ts (recommended)
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true, // Enable global test APIs
    environment: "jsdom", // Browser-like environment
    include: ["**/*.{test,spec}.{js,ts,jsx,tsx}"],
    coverage: {
      provider: "v8",
      reporter: ["text", "html"],
    },
  },
});

または、Vite の設定を拡張します。

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

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

テストファイルの命名

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

• sum.test.js
• sum.spec.ts
• __tests__/sum.js

主なコマンド

# Watch mode (default)
vitest

# Single run
vitest run

# With coverage
vitest run --coverage

# Filter by file/test name
vitest sum
vitest -t "should add"

# UI mode
vitest --ui

# Browser tests
vitest --browser.enabled

よく使われるパターン

基本的なテスト

import { describe, it, expect, beforeEach } from "vitest";

describe("Calculator", () => {
  let calc: Calculator;

  beforeEach(() => {
    calc = new Calculator();
  });

  it("adds numbers", () => {
    expect(calc.add(1, 2)).toBe(3);
  });

  it("throws on invalid input", () => {
    expect(() => calc.add("a", 1)).toThrow();
  });
});

モック

import { vi, expect, test } from "vitest";
import { fetchUser } from "./api";

vi.mock("./api", () => ({
  fetchUser: vi.fn(),
}));

test("uses mocked API", async () => {
  vi.mocked(fetchUser).mockResolvedValue({ name: "John" });

  const user = await fetchUser(1);

  expect(fetchUser).toHaveBeenCalledWith(1);
  expect(user.name).toBe("John");
});

スナップショットテスト

import { expect, test } from "vitest";

test("matches snapshot", () => {
  const result = generateConfig();
  expect(result).toMatchSnapshot();
});

// Inline snapshot (auto-updates)
test("inline snapshot", () => {
  expect({ foo: "bar" }).toMatchInlineSnapshot();
});

非同期テスト

import { expect, test } from "vitest";

test("async/await", async () => {
  const result = await fetchData();
  expect(result).toBeDefined();
});

test("resolves", async () => {
  await expect(Promise.resolve("ok")).resolves.toBe("ok");
});

test("rejects", async () => {
  await expect(Promise.reject(new Error())).rejects.toThrow();
});

フェイクタイマー

import { vi, expect, test, beforeEach, afterEach } from "vitest";

beforeEach(() => {
  vi.useFakeTimers();
});

afterEach(() => {
  vi.useRealTimers();
});

test("advances time", () => {
  const callback = vi.fn();
  setTimeout(callback, 1000);

  vi.advanceTimersByTime(1000);

  expect(callback).toHaveBeenCalled();
});

Jest からの移行

ほとんどの Jest コードは、最小限の変更で動作します。

- import { jest } from '@jest/globals'
+ import { vi } from 'vitest'

- jest.fn()
+ vi.fn()

- jest.mock('./module')
+ vi.mock('./module')

- jest.useFakeTimers()
+ vi.useFakeTimers()

主な違い：

• jest の代わりに vi を使用します
• グローバルはデフォルトで有効ではありません（globals: true を追加してください）
• vi.mock はホイストされます（ホイストされないモックには vi.doMock を使用してください）
• jest.requireActual はありません（vi.importActual を使用してください）

環境の選択

// vitest.config.ts
{
  test: {
    environment: 'jsdom', // or 'happy-dom', 'node', 'edge-runtime'
  }
}

// Per-file (docblock at top)
/** @vitest-environment jsdom */

TypeScript

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

参考資料

詳細なドキュメントについては、references/ ディレクトリを参照してください。

• テスト API とフック
• すべての expect マッチャー
• 関数とモジュールのモック
• 設定オプション
• CLI コマンド
• ブラウザモードのテスト

リンク

• ドキュメント
• API リファレンス
• GitHub
• VS Code 拡張機能