Zenn
🦁

【Vitest】公式ドキュメント日本語訳（概要・インストール）

2024/06/03に公開
Test
Vite
Vitest
tech

Vite ネイティブ・テストランナーの必要性

Vite は、一般的なWebパターン、globインポートやSSRプリミティブなどの機能、そして多数のプラグインとすぐ統合できます。その開発とビルドの流れが成功の鍵です。ドキュメントについては、Viteを利用したSSGベースの手法があるものの、Viteのユニットテストのドキュメントは明確ではありません。また、JestとViteは共通点が多く、ユーザーは2つの異なるパイプラインを構成する必要があります。

テスト中にVite開発サーバーを使用してファイルを変換すると、ソースファイルを変換する手間が省け、テスト中に最高のDXを提供することに専念できるシンプルなランナーを作成できます。アプリと同じ構成 (vite.config.js 経由) を使用するテストランナーは、開発、ビルド、テスト時に共通の変換パイプラインを共有します。これは、同じプラグインAPIを使用して拡張可能で、ユーザーとツールのメンテナーがViteとのファーストクラスの統合を提供できます。最初からViteを念頭に置いて構築されたツールで、HMR(ホットモジュール交換)などのDX改善を活用しています。これが、Viteを搭載した次世代のテストフレームワークであるVitestです。

Vitestは、Jestと互換性のあるAPIを提供しているため、多くのプロジェクトにインストールするだけで使用できます。また、ユニットテスト(モック、スナップショット、カバレッジ)の一般的な機能も設定されています。Vitestはパフォーマンスを重視しており、ワーカースレッドを使用して可能な限り並列で実行します。一部のポートでは、テストの実行が桁違いに高速化されています。ウォッチモードはデフォルトで有効になっており、Viteが開発者ファーストのエクスペリエンスを推進する方法と一致しています。DXでこれらすべての改善が行われても、Vitestは依存関係を慎重に選択(または必要な部分を直接インライン化)することで軽量のままです。

Vitest は、Vite プロジェクトに最適なテストランナーとして、またViteを使用していないプロジェクトでも確実な代替手段として位置付けることを目指しています。

プロジェクトにインストール

vitestをpackage.jsonにインストール。
vitest を直接実行したい場合は、npx vitestを使用します。

npm install -D vitest

＊Vitest1.0には Vite v5.0.0以上、および Node v18.0.0以上が必要です。

npxコマンドは、コマンドを実行するために必要なパッケージをインストールして、ローカルの node_modules/.bin からコマンドを実行します。デフォルトでは、npxはコマンドが$PATHに存在するか、ローカルのプロジェクトバイナリに存在するかを確認し、それを実行します。コマンドが見つからない場合は、実行前にインストールされます。

テストを書く

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

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

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

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

デフォルトでは、テストのファイル名には「.test.」または「.spec.」が含まれている必要があります。

次に、テストを実行するために、package.json に下記を追加します。

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

最後に、テストを起動します。

npm run test

すると、出力結果が返ってきます。

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

 Test Files  1 passed (1)
      Tests  1 passed (1)
   Start at  17:12:12
   Duration  125ms (transform 13ms, setup 0ms, collect 7ms, tests 1ms, environment 0ms, prepare 36ms)

Vitestの設定

Vitestの主な利点の1つは、Viteと統合された構成です。vitestはルートにvite.config.tsが存在する場合、読み取り、プラグインと一致させてViteアプリとして設定します。たとえば、Viteのresolv.aliasとプラグインの構成は、そのまま使用できます。テスト中に別の構成が必要な場合は、下記の方法で変更できます。

  1. 優先度の高い vitest.config.ts を作成
  2. --configオプションをCLIに渡す (例: vitest --config ./path/to/vitest.config.ts)
  3. process.env.VITESTまたはdefineConfigの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: {
    // ...
  },
})
  • Viteを使用していない場合でも、Vitestの変換パイプラインはViteに大きく依存しています。そのため、Vite のドキュメントに記載されているプロパティを設定することもできます。設定リファレンスの設定オプションのリストをご覧ください。

ワークスペースの設定

Vitest Workspaces を使用して、同じプロジェクト内で異なるプロジェクト構成を実行します。 vitest.workspaceファイルで、ワークスペースを定義するファイルとフォルダーのリストを定義できます。このファイルは、js/ts/json拡張子をサポートしています。この機能は、モノレポな環境(プロダクトに関するコードをすべて単一のリポジトリで管理する方法)で非常に有効です。

import { defineWorkspace } from 'vitest/config'

export default defineWorkspace([
  // globパターンのリストを使用してワークスペースを定義できます

  // 設定ファイルまたは設定ファイルが存在するディレクトリのリスト
  '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'],
    },
  },
])

Command Line Interface

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

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

ファイルの変更を監視せずにテストを1回実行するには、vitest runを使用します。--portや--httpsなどの追加のCLIオプションを指定できます。CLIオプションのリストは、プロジェクトで npx vitest --helpを実行して確認できます。

IDE統合

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

VS Code Marketplace からインストール

IDE 統合の詳細

リリース前のコミットを使う

最新の機能をテストするために新しいリリースを使う場合は、 vitestリポジトリをローカルにクローンし、自分でビルドしてリンクする必要があります(pnpm が必要です)。

git clone https://github.com/vitest-dev/vitest.git
cd vitest
pnpm install
cd packages/vitest
pnpm run build
pnpm link --global # you can use your preferred package manager for this step

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

Discussion