Vitest Setup

プロジェクトタイプを検出し、適切な Vitest 設定を生成し、機能するテストインフラストラクチャを提供します。リファレンスカードではなく、このスキルはファイルを作成します。

ワークフロー

1. 検出 — プロジェクトをスキャンしてタイプと既存セットアップを特定
2. 設定 — 環境に合わせた vitest.config.ts を生成
3. スキャフォルド — テストセットアップ、ユーティリティ、サンプルテストを作成
4. 配線 — package.json スクリプトと TypeScript 設定を追加

ステップ 1: プロジェクトタイプを検出

以下のファイルを読んでプロジェクトを特定します：

package.json          → dependencies、scripts、type フィールド
tsconfig.json         → paths、コンパイラオプション
wrangler.toml         → Cloudflare Workers プロジェクト
vite.config.ts        → 既存の Vite セットアップ（置き換えではなく拡張）
vitest.config.ts      → すでに設定済み？ギャップを埋める
jest.config.*         → マイグレーション候補
src/                  → ソース構造

以下のいずれかに分類します：

タイプ	検出信号	環境
Cloudflare Workers	wrangler.toml、@cloudflare/workers-types、cloudflare vite プラグイン	Workers 固有セットアップ付き node
React (Vite)	@vitejs/plugin-react、react-dom	jsdom または happy-dom
React (SSR/TanStack Start)	@tanstack/start、vinxi	分割：サーバー用 node、クライアント用 jsdom
Node/Hono API	hono、express、react-dom なし	node
ライブラリ	exports フィールド、フレームワーク依存なし	node

vite.config.ts がすでに存在する場合、別の vitest.config.ts を作成するのではなく拡張します。Vitest は Vite 設定をネイティブに読み込みます。

ステップ 2: 依存関係をインストール

検出されたタイプに基づいてインストールコマンドを生成します：

# ベース（常に）
pnpm add -D vitest

# React プロジェクト — jsdom と Testing Library を追加
pnpm add -D @vitest/coverage-v8 jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event

# Workers プロジェクト — Cloudflare テストユーティリティを追加
pnpm add -D @vitest/coverage-v8 @cloudflare/vitest-pool-workers

# Node/Hono プロジェクト
pnpm add -D @vitest/coverage-v8

# Jest からマイグレーション中の場合は、以下も削除：
pnpm remove jest ts-jest @types/jest jest-environment-jsdom babel-jest

プロジェクトのパッケージマネージャを使用します（pnpm-lock.yaml、yarn.lock、bun.lockb、または package-lock.json をチェック）。

ステップ 3: vitest.config.ts を生成

Cloudflare Workers

import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";

export default defineWorkersConfig({
  test: {
    globals: true,
    poolOptions: {
      workers: {
        wrangler: { configPath: "./wrangler.toml" },
      },
    },
  },
});

プロジェクトが Cloudflare Vite プラグイン（@cloudflare/vite-plugin）を使用する場合は、代わりに既存の vite.config.ts に統合します：

/// <reference types="vitest/config" />
import { defineConfig } from "vite";
import { cloudflare } from "@cloudflare/vite-plugin";

export default defineConfig({
  plugins: [cloudflare()],
  test: {
    globals: true,
  },
});

React (Vite)

/// <reference types="vitest/config" />
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  test: {
    globals: true,
    environment: "jsdom",
    setupFiles: ["./src/test/setup.ts"],
    css: true,
  },
});

vite.config.ts がすでに存在する場合は、新しいファイルを作成するのではなく test ブロックを追加します。

Node / Hono API

import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    globals: true,
    environment: "node",
  },
});

カバレッジ付き（任意の設定に追加）

  test: {
    // ... 既存の設定
    coverage: {
      provider: "v8",
      reporter: ["text", "html", "lcov"],
      exclude: [
        "node_modules/",
        "**/*.config.*",
        "**/*.d.ts",
        "**/test/**",
      ],
    },
  },

ステップ 4: テストセットアップファイルを生成

src/test/setup.ts を作成します（React プロジェクトのみ）：

import "@testing-library/jest-dom/vitest";

この単一インポートは、すべてのカスタムマッチャー（toBeInTheDocument、toHaveTextContent など）を追加し、Vitest expect.extend を自動的に登録します。

ステップ 5: TypeScript 設定を追加

tsconfig.json の compilerOptions に追加：

{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

複数の tsconfig ファイルを持つプロジェクト（例えば tsconfig.app.json + tsconfig.node.json）の場合は、テストファイルをカバーするものに追加します。通常はルート tsconfig.json または、それを拡張する tsconfig.test.json です。

ステップ 6: package.json スクリプトを追加

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

既存のスクリプトを上書きしないでください。既存のものとマージします。

ステップ 7: サンプルテストを生成

このプロジェクトの正しいパターンを示す 1 つのテストファイルを作成します。別の __tests__ ディレクトリではなく、実際のソースコードの隣に配置します。

Hono API ルート用（例：src/routes/health.ts）：

import { describe, it, expect } from "vitest";
import { app } from "../index";

describe("GET /health", () => {
  it("returns 200 with status ok", async () => {
    const res = await app.request("/health");
    expect(res.status).toBe(200);

    const body = await res.json();
    expect(body).toEqual({ status: "ok" });
  });
});

React コンポーネント用（例：src/components/Button.tsx）：

import { describe, it, expect } from "vitest";
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Button } from "./Button";

describe("Button", () => {
  it("renders with label", () => {
    render(<Button>Click me</Button>);
    expect(screen.getByRole("button", { name: /click me/i })).toBeInTheDocument();
  });

  it("calls onClick when clicked", async () => {
    const user = userEvent.setup();
    const handleClick = vi.fn();
    render(<Button onClick={handleClick}>Click me</Button>);

    await user.click(screen.getByRole("button"));
    expect(handleClick).toHaveBeenCalledOnce();
  });
});

ユーティリティ関数用（例：src/utils/format.ts）：

import { describe, it, expect } from "vitest";
import { formatCurrency } from "./format";

describe("formatCurrency", () => {
  it("formats whole numbers", () => {
    expect(formatCurrency(1000)).toBe("$1,000.00");
  });

  it("formats decimals", () => {
    expect(formatCurrency(49.9)).toBe("$49.90");
  });

  it("handles zero", () => {
    expect(formatCurrency(0)).toBe("$0.00");
  });
});

プロジェクトから実際のファイルを選択してテストします。架空のモジュールを作ってはいけません。サンプルテストはセットアップ直後にすぐ実行できるべきです。

ステップ 8: 検証

テストを実行してすべてが機能していることを確認します：

pnpm test:run

失敗する場合は、診断と修正を行います。よくある問題：

エラー	修正方法
Cannot find module 'vitest'	インストール完了を確認、node_modules/.vitest の存在をチェック
ReferenceError: describe is not defined	設定に globals: true を追加、または tsconfig に types: ["vitest/globals"] を追加
document is not defined	環境が間違っている。React テスト用に environment: "jsdom" を設定
Cannot use import.meta	vitest.config が .ts 拡張子を使用していることを確認、プロジェクトに "type": "module" があるか Vite が変換を処理していることを確認
Workers バインディングが未定義	素の vitest ではなく @cloudflare/vitest-pool-workers を使用、wrangler.toml パスをチェック

---

モッキングリファレンス

これらのパターンはセットアップ完了後にテストを書くためのものです。サンプルテストに含めるか、ユーザーがモッキング例を求めた場合は src/test/examples.test.ts に含めます。

モジュールモッキング（vi.mock）

import { vi, describe, it, expect } from "vitest";
import { getUser } from "./api";

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

it("mocks a module function", async () => {
  vi.mocked(getUser).mockResolvedValue({ id: 1, name: "Test" });
  const user = await getUser(1);
  expect(user.name).toBe("Test");
  expect(getUser).toHaveBeenCalledWith(1);
});

メソッドをスパイ（vi.spyOn）

it("spies on console.warn", () => {
  const spy = vi.spyOn(console, "warn").mockImplementation(() => {});
  doSomethingThatWarns();
  expect(spy).toHaveBeenCalledOnce();
  spy.mockRestore();
});

フェイクタイマー

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

beforeEach(() => {
  vi.useFakeTimers();
  vi.setSystemTime(new Date("2026-01-15T10:00:00Z"));
});

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

it("uses controlled time", () => {
  expect(new Date().toISOString()).toBe("2026-01-15T10:00:00.000Z");
});

グローバルスタブ

it("stubs fetch", async () => {
  const mockFetch = vi.fn().mockResolvedValue({
    ok: true,
    json: () => Promise.resolve({ data: "test" }),
  });
  vi.stubGlobal("fetch", mockFetch);

  const res = await fetch("/api/data");
  expect(mockFetch).toHaveBeenCalledWith("/api/data");

  vi.unstubAllGlobals();
});

スナップショットテスト

it("matches snapshot", () => {
  const result = generateConfig({ debug: true });
  expect(result).toMatchSnapshot();
});

it("matches inline snapshot", () => {
  expect({ status: "ok", count: 3 }).toMatchInlineSnapshot(`
    {
      "count": 3,
      "status": "ok",
    }
  `);
});

パラメータ化テスト

describe.each([
  { input: "hello", expected: "HELLO" },
  { input: "world", expected: "WORLD" },
  { input: "", expected: "" },
])("toUpperCase($input)", ({ input, expected }) => {
  it(`returns ${expected}`, () => {
    expect(input.toUpperCase()).toBe(expected);
  });
});

---

Jest マイグレーション

検出されたプロジェクトが Jest（jest.config.*、@types/jest、依存関係に ts-jest がある）を持つ場合：

1. 上記のステップを使用して vitest.config.ts を生成
2. 既存のテストファイルのインポートを更新：

// Before
import { jest } from "@jest/globals";
jest.mock("./api");
jest.fn();
jest.spyOn(obj, "method");

// After
import { vi } from "vitest";
vi.mock("./api");
vi.fn();
vi.spyOn(obj, "method");

3. Jest パッケージを削除：

pnpm remove jest ts-jest @types/jest jest-environment-jsdom babel-jest @jest/globals

4. tsconfig を更新 — "types": ["jest"] を "types": ["vitest/globals"] に置き換え

5. テストを実行し、残りの問題を修正

主な置き換え：

Jest	Vitest
jest.fn()	vi.fn()
jest.mock()	vi.mock()
jest.spyOn()	vi.spyOn()
jest.useFakeTimers()	vi.useFakeTimers()
jest.clearAllMocks()	vi.clearAllMocks()
jest.requireActual()	vi.importActual()
@jest/globals	vitest
jest.config.js	vitest.config.ts

---

ワークスペースセットアップ（モノレポ）

複数のパッケージを持つモノレポプロジェクトの場合：

// vitest.workspace.ts
import { defineWorkspace } from "vitest/config";

export default defineWorkspace([
  "packages/*/vitest.config.ts",
]);

各パッケージは独自の設定を持ちます。ワークスペースファイルは単にそれらをポイントします。

---

このスキルが生成するもの

実行後、プロジェクトは以下を持つべきです：

• vitest.config.ts（または既存の vite.config.ts に追加されたテストブロック）
• src/test/setup.ts（React プロジェクト）
• vitest/globals タイプで更新された tsconfig.json
• テストスクリプトで更新された package.json
• 実際のソースコードに対する少なくとも 1 つのパスするサンプルテスト
• インストールされた依存関係

テストは初回実行時にパスすべきです。そうでない場合は、終了する前に修正してください。