TypeScriptでJestからVitestへ:高速セットアップ、速度最適化、In-source Testing

Development tutorial - IT technology blog
Development tutorial - IT technology blog

Jestは動くが、問題がある

TypeScriptでJestを使っているなら、こんな経験があるはずだ:テストスイートの初回起動だけで10〜15秒かかり、小さなファイルを修正するたびにさらに数秒待つことになる。原因は、Jestが実行前にTypeScriptをBabelまたはts-jestでトランスパイルする必要があるためで、そのモジュールシステムは依然として古いCommonJS方式で動作している。

Vitestはまさにこの問題を解決する。TypeScriptはesbuildで処理され——Babelより何倍も高速だ。さらに重要なのは、変換パイプライン全体が一度だけ起動し、ファイルを変更するたびにリセットされないことだ。

実際に、180のテストファイルと5人の開発者が関わるWebアプリプロジェクトをJestからVitestに移行してみた。フルテストスイートの実行時間は47秒から11秒に短縮された。ウォッチモードはほぼ瞬時に応答する。チーム全員が移行初日から違いを実感した。

TypeScriptプロジェクトへのVitestのインストール

Viteを使っているプロジェクトなら設定が楽だが、必須ではない——VitestはViteなしでも動作する。インストールは他のdev dependencyと同じ手順だ:

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

# npmを使う場合
npm install -D vitest

# pnpmを使う場合
pnpm add -D vitest

# yarnを使う場合
yarn add -D vitest

UIコンポーネント(React、Vueなど)のテストにはjsdom環境が必要だ:

npm install -D @vitest/ui jsdom

package.jsonにスクリプトを追加する

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

runなしのvitestはウォッチモードで実行され、変更されたファイルを自動検出して関連テストを再実行する。vitest runは一度実行して終了するため、CI/CDに適している。

詳細な設定

vite.config.tsへの統合

すでにvite.config.tsがあるなら、直接testブロックを追加するだけ——別のconfigファイルは不要だ:

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

export default defineConfig({
  test: {
    globals: true,          // describe/it/expectをimportなしで使用
    environment: 'jsdom',   // 純粋なNode.jsテストはこの行を削除
    setupFiles: './src/test/setup.ts',
    include: ['**/*.{test,spec}.{ts,tsx}'],
    coverage: {
      reporter: ['text', 'html'],
      exclude: ['node_modules/', 'src/test/']
    }
  }
})

先頭の/// <reference types="vitest" />行により、TypeScriptはdescribe、it、expectなどの型を追加宣言なしに認識できるようになる。

独立したvitest.config.tsを使う場合

Viteを使っていない場合は、独立したvitest.config.tsファイルを作成する:

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    globals: true,
    environment: 'node',
    include: ['src/**/*.test.ts'],
    reporters: ['verbose']
  }
})

tsconfig.jsonを更新する

IDEがエラーを表示しないよう、tsconfig.jsonにVitestの型を追加する:

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

テストを書く——Jestとほぼ100%同じ構文

これがVitestへの移行が思ったより苦痛でない理由だ:既存のJestテストファイルはそのまま動作し、変更は不要。Jestを知っていれば、新たにドキュメントを読む必要もない。

// src/utils/format.test.ts
import { describe, it, expect } from 'vitest'
import { formatCurrency } from './format'

describe('formatCurrency', () => {
  it('VND金額を正しくフォーマットする', () => {
    expect(formatCurrency(1500000)).toBe('1,500,000 ₫')
  })

  it('inputが0の場合0 ₫を返す', () => {
    expect(formatCurrency(0)).toBe('0 ₫')
  })

  it('負の数を処理する', () => {
    expect(formatCurrency(-50000)).toBe('-50,000 ₫')
  })
})

globals: trueをconfigで設定すれば、import行を省略してJestと同様に直接使用できる。

In-source Testing——Vitestだけの独自機能

Jestにはこの機能がない。In-source Testingにより、.test.tsファイルを別途作成しなくても、ソースファイル内に直接テストを書ける。小さなユーティリティ関数なら、関数定義のすぐ下にテストを配置できる——コードを読む人は別ファイルを開かなくても関数の動作を即座に把握できる。

動作の仕組み

Vitestはif (import.meta.vitest)ブロックを使用する。本番ビルド時、Viteがこのブロック全体をツリーシェイクするため、バンドルサイズには影響しない:

// src/utils/math.ts
export function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max)
}

// テストをソースファイル内に直接記述
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest

  it('clampが[min, max]の範囲内に値を保持する', () => {
    expect(clamp(5, 0, 10)).toBe(5)
    expect(clamp(-1, 0, 10)).toBe(0)
    expect(clamp(15, 0, 10)).toBe(10)
  })
}

configでIn-source Testingを有効にする

// vite.config.ts
export default defineConfig({
  test: {
    includeSource: ['src/**/*.ts']  // この行を追加
  },
  define: {
    // 本番ビルドからテストコードを除外
    'import.meta.vitest': 'undefined'
  }
})

このパターンをプロジェクト内のヘルパー関数に活用している:date-utils.test.tsを別途作成する代わりに、テストを関数定義のすぐ下に配置する。コードレビュー時、読者は関数の動作と期待される結果を即座に把握できる——別ファイルを開く必要がない。

テスト実行とcoverageの確認

初回のテスト実行

# ウォッチモード(開発時)
npm test

# 一回実行(CI用)
npm run test:run

# ブラウザで視覚的なUIを確認
npm run test:ui

UIモード(--ui)はブラウザでダッシュボードを開き、ファイルツリーごとにテストを表示し、pass/failの結果を色分けで明確に示す。多くのネストされたdescribeを含む大規模なテストスイートのデバッグに便利だ。

coverageレポートの確認

coverageパッケージを追加インストールする:

npm install -D @vitest/coverage-v8
npm run coverage

出力にはファイルごとの統計表が表示される:statement、branch、function、lineの各カバレッジが何%かを確認できる。HTMLレポートはcoverage/ディレクトリに生成され、ブラウザで開くと各行の詳細を確認できる。

CI/CDへの統合

GitHub ActionsまたはGitLab CIでは、jestをvitest runに置き換える:

- name: Run tests
  run: npm run test:run

- name: Check coverage
  run: npm run coverage

JestからVitestへ移行する際の注意点

  • モックモジュール:jest.mock()の代わりにvi.mock()を使用
  • スパイ:jest.spyOn()の代わりにvi.spyOn()を使用
  • フェイクタイマー:jest.useFakeTimers()の代わりにvi.useFakeTimers()を使用
  • スナップショット:構文は同じ、スナップショットファイルは以前と同じく__snapshots__に保存

ほとんどの場合、jest.をvi.に一括置換するだけで済む。sedコマンドで180のテストファイルを2分でmigrationでき、ロジックが複雑な箇所だけ数カ所を手動修正した。

Vitestを使うべき場面、Jestを維持すべき場面

判断はシンプルだ。Viteを使っているならVitestを選べばいい、迷う必要はない。独立したTypeScriptライブラリをビルドする場合もVitestがデフォルトの良い選択だ。

古いCRA、WebpackのNext.js、あるいは触りたくない特殊なセットアップがある場合——Jestは安定しており、変更の必要はない。

新規プロジェクトのセットアップやViteへの移行を進めているなら、最初からVitestを選ぼう。フルテストスイートの実行が47秒ではなく11秒——数ヶ月の開発期間に積み重なると、かなりの時間節約になる。

Share: