WebStorm 2026.2 Help

Vitest

WebStorm は Vitest と統合されており、 Vite ネイティブのユニットテストフレームワークです。 実行、デバッグ、スナップショットテストの実行、およびエディターと実行 / デバッグ構成の両方からのテストカバレッジの測定を行うことができます。

失敗したテストを再実行するか、 ウォッチモードをオンにできます。 このモードでテストセッションを開始すると、WebStorm がプロジェクトのソースコードの変更を監視します。 テストまたはその対象に変更があるとすぐに、WebStorm が該当テストを再実行します。実行/デバッグ構成を再起動する必要はありません。

始める前に

  1. コンピューターに Node.js(英語) があることを確認してください。

  2. 設定で Vite プラグインが有効になっていることを確認します。 Ctrl+Alt+S を押して設定を開き、 プラグイン を選択します。 インストール済み タブをクリックします。 検索フィールドに Vite と入力します。 プラグインの詳細については、 プラグインの管理を参照してください。

Vitest をインストールする

  • コマンドラインシェルまたは組み込み ターミナル （Alt+F12） で、次を入力してください：

    npm install --save-dev vitest

Vitest 公式 Web サイトで オンラインドキュメント(英語)および Vitest の設定(英語)の詳細を参照してください。

テストの実行とデバッグ

WebStorm を使うと、エディターから直接単一の Vitest テストを素早く実行またはデバッグしたり、実行/デバッグ構成を作成してテストの一部または全てを実行またはデバッグできます。

JavaScript および TypeScript コードの Vitest テストの作成の詳細については、Vitest 公式 Web サイトの Vitest の機能(英語)を参照してください。

エディターから単一のテストを実行またはデバッグする

  • ガターで 実行アイコン または Rerun アイコン⁠ をクリックし、リストから <test_name> を実行 を選択します。

    エディターから 1 つの Vitest テストを実行する

    実行 ツールウィンドウでテストの実行結果を確認します。 失敗したテストについては、エラーが発生した場所と原因に関する情報が表示されます。

    エラーの詳細情報

    ガターの テストステータスアイコン テスト成功 および テスト失敗 により、エディターでテストが成功したか失敗したかを確認することもできます。

    テスト用のガターのアイコン

  • テストをデバッグするには、テスト内に ブレークポイントを設定し 、ガターで 実行アイコン または Rerun アイコン⁠ をクリックし、リストから デバッグ <テスト名> を選択します。

    エディターから 1 つの Vitest テストをデバッグする

    デバッグ ツールウィンドウで、 中断されたテストを調べ、 ステップ実行します。

    Vitest デバッグセッション

Vitest 実行構成を作成する

  1. 実行 / デバッグ構成ダイアログ (メインメニューの 実行 | 実行構成の編集) を開き、左側のペインで 追加ボタン をクリックし、リストから Vitest を選択します。 「実行 / デバッグ構成: Vitest 」ダイアログが開きます。

  2. 使用する Node.js ランタイムを指定します。

    プロジェクト エイリアスを選択した場合、WebStorm は JavaScript Runtime ページの ノードランタイム フィールドにあるプロジェクトのデフォルトインタープリターを自動的に使用します。 ほとんどの場合、WebStorm はプロジェクトのデフォルトランタイムを検出し、自動的にフィールドに入力します。

    別の構成済みのローカルインタープリターまたはリモートインタープリターを選択するか、 参照ボタン をクリックして新しいインタープリターを構成することもできます。

    詳細については、「リモート Node.js ランタイムの構成」、「ローカル Node.js ランタイムの構成」、「Linux の Windows サブシステムで Node.js を使用する 」を参照してください。

    必要に応じて、Node.js に渡す Node.js 固有のオプションパラメーターと 環境変数(英語)を指定します。

    変数の定義は、 環境変数 フィールドにセミコロン（; ）で区切って表示されます。例えば：

    • NODE_PATH

      モジュール解決時に検索する追加ディレクトリのリストです。 リスト内のディレクトリを区切るには、macOS または Linux ではコロン（: ）、Windows ではセミコロン（; ）を使用します。

    • NODE_MODULE_CONTEXTS

      モジュールをそれぞれ独自のグローバルコンテキストで読み込むには、1 に設定します。

    • NODE_DISABLE_COLORS

      REPL で色を無効にするには、1 に設定します。

    環境変数

    または、フィールドの右側にある 閲覧する 環境変数の編集アイコン をクリックし、表示される 環境変数 ダイアログで変数のリストを設定します：

    • カスタム変数のリストを管理するには、 、 、 、 ボタンを使用します。

    • ダイアログには、利用可能なシステム環境変数のリストも表示されます。 現在の構成でシステム環境変数を使用しない場合は、 システム環境変数を含める チェックボックスをオフにしてください。

    • 準備ができたら OK をクリックします。

  3. vitest パッケージの場所を指定します。

  4. アプリケーションの作業ディレクトリを指定します。 デフォルトでは、 作業ディレクトリ フィールドにはプロジェクトのルートフォルダーが表示されます。 この事前定義された設定を変更するには、目的のフォルダーへのパスを指定してください。

  5. 実行するテストを指定します。 これは、特定のテストまたはスイート、テストファイル全体、テストファイルを含むフォルダーにすることができます。

  6. デフォルトでは、 vite.config.ts が使用されます。 vite.config.ts が存在しない場合、またはカスタム構成を使用する場合は、使用する vitest.config.ts を指定します。 詳細については、 Vitest オフィシャル Web サイト(英語)を参照してください。

  7. オプション:

    それらまたは関連するソースファイルの変更時に自動的に再実行されるテストを構成します。 これを行うには、 Vitest オプション フィールドに --watch フラグを追加します。

    他の Vitest オプションを追加することもできます。 詳細については、 Vitest オフィシャル Web サイト(英語)を参照してください。

  8. オプション:

    Node オプション フィールドに、Node.js 実行可能ファイルに渡される Node.js 固有のコマンドラインオプションを入力します。 許容されるオプションは次のとおりです。

    • 実行中に CoffeeScript ファイルをオンザフライで JavaScript にコンパイルするには、 --require coffeescript/register を使用します。

      このモードでは、 coffeescript パッケージの一部である register.js ファイルがプロジェクト内に配置されている必要があります。 そのため、 CoffeeScript コンパイラーをインストールするで説明されているように、 coffeescript パッケージがローカルにインストールされていることを確認してください。

    • Chrome デバッグプロトコル(英語)サポートには --inspect または --inspect-brk パラメーターを使用します。

実行構成を介してテストを実行する

  1. 構成のリストから Vitest 実行/デバッグ構成を選択し、リストまたはツールバーの 実行アイコン をクリックします。

    実行 / デバッグ構成を選択

  2. 実行 ツールウィンドウの テストランナー タブで、テストの実行を監視し、テスト結果を分析します。 詳細については、 テスト結果を確認するを参照してください。

    テストをデバッグするには、必要に応じて ブレークポイントを設定し 、実行 / デバッグ構成を選択して、 「デバッグ」ボタン をクリックします。

    Vitest: テスト結果

テストの再実行

指定したスコープ Alt+Shift+R 内のすべてのテストを再実行するか、失敗したテストのみを再実行できます。

--watch モード(英語)でテストを起動することもできます。 このモードでは、WebStorm がテストおよび関連するテスト対象への保存された変更を監視します。 変更が検出されるとすぐに、WebStorm は現在のテストセッションを停止することなく、影響を受けたテストを再実行します。

失敗したテストを再実行

  • テスト結果ツールバーの Rerun Failed Tests アイコン⁠ をクリックします。 WebStorm は前回のセッションで失敗したすべてのテストを実行します。

    Vitest: 失敗したすべてのテストの再実行

  • 特定の失敗したテストを再実行するには、そのコンテキストメニューで 実行 <テスト名> を選択します。

詳細は、 テストの再実行を参照してください。

更新されたテストを自動的に再実行する (--watch モード)

  1. Vitest 実行 / デバッグ構成を開くか、 上記のように新しい構成を作成します。

  2. Vitest オプション フィールドに --watch と入力します。 自動生成された すべてのテスト 構成では、 --watch オプションがすでに指定されています。

  3. 実行 / デバッグ構成を起動します。 一部のテストが失敗した場合、テストセッションを停止することなく、それらのテストまたは関連するテストサブジェクトを更新できます。 変更が保存されるとすぐに、WebStorm がそれらを検出し、該当するテストを再実行します。

    以下の例では、 vue.test.ts の 29 行でのテストが失敗します。 --watch オプションを利用すると、 vue.test.ts で '4 x 4 = 18' を '4 x 4 = 16' に置き換え、 Ctrl+S で変更を保存するか、WebStorm からフォーカスを移動した後で、テストが再実行されます。

    Rerun updated test in the --watch mode

スナップショットテスト

WebStorm は Vitest スナップショットテストもサポートしています。 WebStorm が初めて toMatchSnapshot() メソッドでテストを実行すると、スナップショットファイルが作成され、 toMatchSnapshot () の横のガターに スナップショット アイコンが表示されます。 スナップショット アイコン をクリックして、生成されたスナップショットを開きます。

スナップショット

コードカバレッジを監視する

WebStorm を使うと、コードがどの程度 Vitest テストでカバーされているかも確認できます。 WebStorm は、この統計情報を専用の カバレッジ ツールウィンドウに表示し、エディターおよび プロジェクト ツールウィンドウ(Alt+1 )でカバー済みと未カバーの行を視覚的にマークします。

Vitest カバレッジレポート

Vitest のコードカバレッジを有効にする

@vitest/ カバレッジ v8(英語) または istanbul(英語) をインストールします。 これを行うには、組み込みの ターミナル Alt+F12 を開き、次のいずれかを入力します。

  • npm install --save-dev @vitest/coverage-v8

  • npm install --save-dev @vitest/coverage-istanbul。

Vitest 公式 Web サイトで カバレッジ(英語)の詳細を参照してください。

カバレッジでテストを実行する

  1. エディターからカバレッジ付きで特定のスイートまたはテストを実行します。ガターで Run ボタン または 再実行ボタン をクリックし、リストから カバレッジで <test_name> を実行する を選択します。

    エディターからのカバレッジで Vitest テストを実行する

    あるいは:

    上記の説明に従って、Vitest 実行 / デバッグ構成を作成します。 メインツールバーのリストから Vitest 実行 / デバッグ構成を選択し、リストの右側にある Run with Coverage アイコン をクリックします。

  2. カバレッジツールウィンドウでコードカバレッジを監視します。 このレポートには、テストでカバーされたファイルの数と、その中にカバーされている行の割合が表示されます。 レポートから、ファイルに移動して、どの行が覆われていたか（緑色にマーキングされているか、どの行が覆われていないか）、赤色に表示されているかを確認できます。

トラブルシューティング

クイックトラブルシューティングチェックリスト

  1. コマンドラインシェルまたは組み込み ターミナル （Alt+F12 ）を開き、 npm test または npx vitest run が正常に実行されるか確認してください。

  2. Vitest 実行/デバッグ構成で、 作業ディレクトリ フィールドにプロジェクトルートが指定されていることを確認してください。

  3. カスタム Vitest 構成を使用している場合は、 vitest .config.ts または vite.config.ts 構成ファイルへのパスが正しく指定されていることを確認してください。

  4. コマンドラインオプションを確認してください。 デバッグ用に、 --test-timeout=0 --no-file-parallelism を Vitest オプション フィールドに追加してください。

    コマンドラインオプション​​

  5. Docker や WSL を使用している場合は、パスマッピングとソースマップを確認してください。

    Docker デバッグで最も一般的な根本原因は Vitest 自体ではなく、ローカル環境とコンテナ内環境の違いです。

以下は Vitest-in-WebStorm でよくある不満点です。

WebStorm で Vitest のテストが検出されません

典型的な症状：

  • テストの横に テストを実行 ガターアイコンが表示されません。

  • Test not found エラーが表示されます。

  1. プロジェクトに Vitest がインストールされていることを確認してください。 コマンドラインシェルまたは組み込み ターミナル (Alt+F12) を開き、 npm vitest --v と入力します。 現在インストールされている Vitest のバージョンが表示されるはずです。 表示されない場合は、 npm install --save-dev vitest を入力して現在のプロジェクトに Vitest をインストールしてください。

  2. テストファイル名が Vitest の命名規則 に従っていることを確認してください。

ブレークポイントに到達しません

これには次のような理由が考えられます：

  • ソースマップの不一致によって、WebStorm が生成された JavaScript をデバッグしているが、ソースマップが誤った TypeScript/TSX のソース位置を指していることを意味します。

  • 作業ディレクトリが間違っています。 その結果、Vitest が誤った package.json を見つけたり、正しい vitest.config.ts を見つけられなかったり、エイリアスを誤って解決する場合があります。

  • テストはワーカースレッドで実行されるため、複数のテストファイルを並列で実行できます。 速度向上には良いですが、デバッグ時に問題が発生することがあります。

  • Docker や WSL でパスが一致しないことで、デバッガーが見るファイルパスと、WebStorm が持つソースコードのパスが異なる場合があります。

  1. --test-timeout=0 と --no-file-parallelism の Vitest デバッグ向けフラグを Vitest オプション フィールドの Vitest 実行/デバッグ構成に追加してください。

    これによりタイムアウトや並列テスト実行の問題を回避できます。詳しくは Vitest 公式サイト をご覧ください。

  2. Ctrl+Alt+S を押して設定を開き、 ビルド、実行、デプロイ | Docker を選択します。 Docker または WSL のマッピングを確認し、実行/デバッグ構成のパスマッピングと比較してください。

コマンドラインシェルではテストが合格しますが、WebStorm UI から起動すると失敗します。

これは、WebStorm のテスト環境がコマンドラインシェルのものと異なるために発生する場合があります。 WebStorm が異なる設定で Vitest を起動し、テストの動作が変わる場合があります。

  1. Vitest 実行/デバッグ構成を開きます。

    • 指定した Node.js ランタイムのバージョンが、コマンドラインで使用しているものと同じであることを確認してください。

    • 作業ディレクトリがコマンドラインで使用しているものと同じであることを確認してください。

    • 環境変数に違いがないか比較してください。

    • 同じ Vitest 構成と Vitest オプション が使用されていることを確認してください。

  2. WebStorm からデバッグせずにテストを実行してください。 テストが合格した場合、問題はデバッガーに関連している可能性が高いです。

  3. テストをデバッグする場合は、 Vitest オプション フィールドに次の内容を追加して、一時的に並列実行を無効化してください：

    --test-timeout=0--no-file-parallelism

  4. Docker または WSL を使用している場合は、WebStorm のパスマッピングが Docker または WSL のパスと一致しているか確認してください。

パスエイリアスが機能しない

import { foo } from '@/foo' 形式の import 文を含むテストファイルが失敗します。

  1. 以下の構成ファイルでエイリアスが一貫して設定されていることを確認してください：

    • tsconfig.json

    • vite.config.ts

    • vitest.config.ts

  2. テスト構成を vite.config.ts または vitest.config.ts に配置してみてください。 これは Vitest がデフォルトで Vite の設定ファイルを読み込むため、役立つ場合があります。

DOM API が見つかりません

エラーの例：

  • document が定義されていません

  • window が定義されていません

  • HTMLElement が定義されていません

ブラウザーライクなテスト環境を利用してください。

  1. jsdome をインストールします。 そのためには、コマンドラインシェルまたは組み込み ターミナル （Alt+F12 ）を開き、次のように入力してください：

    npm install --d jsdom

  2. vitest.config.ts 構成ファイルを開き、次のコードを追加してください：

    import { defineConfig } from 'vitest/config' export default defineConfig({ test: { environment: 'jsdom' } })

環境変数が見つかりません

フロントエンド型の環境変数には VITE_ プレフィックスが付いていることを確認してください。例：

VITE_API_URL=http://localhost:3000

さらにコード内でも：

import.meta.env.VITE_API_URL

ウォッチモードが予期せぬ動作をする

Docker、WSL、またはマウントボリュームでファイル監視は難しいことがあります。

コマンドラインシェルまたは組み込み ターミナル （Alt+F12 ）で、 vitest run を入力してください。

コマンドが正常に実行できる場合、問題は watch モードまたはファイルシステム通知にある可能性が高いです。

    2026 年 7 月 14 日
    実行 / デバッグ構成: ProtractorTypeScript