Angular CLIは、新しいプロジェクトのデフォルトのユニットテストランナーとしてVitestを使用します。このガイドでは、既存のプロジェクトをKarmaとJasmineからVitestに移行する手順を説明します。
IMPORTANT: 既存のプロジェクトをVitestに移行することは実験的なものとみなされます。このプロセスでは、applicationビルドシステムの使用も必要です。これは、すべての新規作成されたプロジェクトのデフォルトです。
手動での移行手順
自動リファクタリングschematicを使用する前に、プロジェクトを手動で更新してVitestテストランナーを使用するようにする必要があります。
1. 依存関係のインストール
vitestとDOMエミュレーションライブラリをインストールします。ブラウザテストも可能ですが（ステップ5を参照）、VitestはデフォルトでDOMエミュレーションライブラリを使用してNode.js内でブラウザ環境をシミュレートし、テスト実行を高速化します。CLIはhappy-domがインストールされていれば自動的に検出して使用し、そうでなければjsdomにフォールバックします。これらのパッケージのいずれかがインストールされている必要があります。
2. angular.jsonの更新
angular.jsonファイルで、プロジェクトのtestターゲットを見つけ、builderを@angular/build:unit-testに変更します。
{ "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test" } } } }}unit-testビルダーは、デフォルトで"tsConfig": "tsconfig.spec.json"と"buildTarget": "::development"になります。プロジェクトで異なる値が必要な場合は、これらのオプションを明示的に設定できます。たとえば、developmentビルド設定がない場合や、テスト用に異なるオプションが必要な場合は、testingなどの名前を付けたビルド設定を作成してbuildTargetに使用できます。
以前の@angular/build:karmaビルダーでは、ビルドオプション（polyfills、assets、stylesなど）をtestターゲット内で直接設定できました。新しい@angular/build:unit-testビルダーはこれをサポートしていません。テスト固有のビルドオプションが既存のdevelopmentビルド設定と異なる場合は、それらを専用のビルドターゲット設定に移動する必要があります。テストのビルドオプションがすでにdevelopmentビルド設定と一致している場合は、何もする必要はありません。
3. カスタムkarma.conf.js設定の処理
karma.conf.js内のカスタム設定は自動的に移行されません。karma.conf.jsファイルを削除する前に、移行が必要なカスタム設定がないか確認してください。
多くのKarmaオプションにはVitestでの同等の機能があり、カスタムのVitest設定ファイル（例: vitest.config.ts）で設定し、runnerConfigオプションを介してangular.jsonにリンクできます。
一般的な移行パスは次のとおりです:
- レポーター: Karmaレポーターは、Vitest互換のレポーターに置き換える必要があります。これらは多くの場合、
angular.jsonのtest.options.reportersプロパティで直接設定できます。より高度な設定には、カスタムのvitest.config.tsファイルを使用します。 - プラグイン: Karmaプラグインには、Vitestでの同等のものがあるかもしれません。それらを見つけてインストールする必要があります。コードカバレッジはAngular CLIの主要な機能であり、
ng test --coverageで有効にできることに注意してください。 - カスタムブラウザランチャー: これらは
angular.jsonのbrowsersオプションと、@vitest/browser-playwrightのようなブラウザプロバイダーのインストールに置き換えられます。
その他の設定については、公式のVitestドキュメントを参照してください。
4. Karmaとtest.tsファイルの削除
これで、プロジェクトからkarma.conf.jsとsrc/test.tsを削除し、Karma関連のパッケージをアンインストールできます。次のコマンドは、新しいAngular CLIプロジェクトにインストールされるパッケージに基づいています。あなたのプロジェクトには、他にも削除すべきKarma関連のパッケージがあるかもしれません。
5. ブラウザモードの設定（任意）
実際のブラウザでテストを実行する必要がある場合は、ブラウザプロバイダーをインストールし、angular.jsonを設定する必要があります。
ブラウザプロバイダーのインストール:
ニーズに応じて、次のブラウザプロバイダーのいずれかを選択してください:
- Playwright: Chromium、Firefox、WebKit用の
@vitest/browser-playwright。 - WebdriverIO: Chrome、Firefox、Safari、Edge用の
@vitest/browser-webdriverio。 - Preview: Webcontainer環境（StackBlitzなど）用の
@vitest/browser-preview。
ブラウザモード用にangular.jsonを更新:
testターゲットのオプションにbrowsersオプションを追加します。ブラウザ名は、インストールしたプロバイダーによって異なります（例: Playwrightの場合はchromium、WebdriverIOの場合はchrome）。
{ "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "browsers": ["chromium"] } } } } }}ヘッドレスモードは、CI環境変数が設定されている場合や、ブラウザ名に"Headless"が含まれている場合（例: ChromeHeadless）に自動的に有効になります。それ以外の場合、テストはヘッド付きブラウザで実行されます。
schematicsによる自動テストリファクタリング
IMPORTANT: refactor-jasmine-vitest schematicは実験的なものであり、すべての可能なテストパターンをカバーしているとは限りません。schematicによって行われた変更は必ずレビューしてください。
Angular CLIは、JasmineテストをVitestを使用するように自動的にリファクタリングするためのrefactor-jasmine-vitest schematicを提供します。
概要
このschematicは、テストファイル（.spec.ts）で以下の変換を自動化します:
fitとfdescribeをit.onlyとdescribe.onlyに変換します。xitとxdescribeをit.skipとdescribe.skipに変換します。spyOnの呼び出しを同等のvi.spyOnに変換します。jasmine.objectContainingをexpect.objectContainingに置き換えます。jasmine.anyをexpect.anyに置き換えます。jasmine.createSpyをvi.fnに置き換えます。beforeAll、beforeEach、afterAll、afterEachをVitestの同等のものに更新します。fail()をVitestのvi.fail()に変換します。- Vitest APIに一致するようにexpectationsを調整します
- 自動的に変換できないコードにTODOコメントを追加します
このschematicは、以下の操作をしません:
vitestやその他の関連する依存関係をインストールしません。- Vitestビルダーを使用するように
angular.jsonを変更したり、testターゲットからビルドオプション（polyfillsやstylesなど）を移行したりしません。 karma.conf.jsやtest.tsファイルを削除しません。- 複雑な、またはネストされたスパイシナリオは処理しません。これらは手動でのリファクタリングが必要になる場合があります。
schematicsの実行
プロジェクトがVitest用に設定されたら、schematicを実行してテストファイルをリファクタリングできます。
デフォルトプロジェクトのすべてのテストファイルをリファクタリングするには、次を実行します:
ng g @schematics/angular:refactor-jasmine-vitestオプション
以下のオプションを使用して、schematicの動作をカスタマイズできます:
| オプション | 説明 |
|---|---|
--project <name> |
マルチプロジェクトワークスペースでリファクタリングするプロジェクトを指定します。 例: --project=my-lib |
--include <path> |
特定のファイルまたはディレクトリのみをリファクタリングします。 例: --include=src/app/app.component.spec.ts |
--file-suffix <suffix> |
テストファイルに異なるファイルサフィックスを指定します。 例: --file-suffix=.test.ts |
--add-imports |
Vitestの設定でグローバルを無効にしている場合に、明示的なvitestのインポートを追加します。 |
--verbose |
適用されたすべての変換の詳細なロギングを表示します。 |
移行後
schematicが完了したら、次のことを行うことをお勧めします:
- テストの実行:
ng testを実行して、リファクタリング後もすべてのテストがパスすることを確認します。 - 変更のレビュー: schematicによって行われた変更を確認し、特に複雑なスパイやモックを持つテストに注意を払います。これらはさらなる手動での調整が必要になる場合があります。
ng testコマンドは、アプリケーションを_ウォッチモード_でビルドし、設定されたランナーを起動します。ウォッチモードは、インタラクティブターミナルを使用しており、CIで実行されていない場合にデフォルトで有効になります。
設定
Angular CLIがVitest設定を管理し、angular.jsonのオプションに基づいてメモリ上で完全な設定を構築します。
カスタムVitest設定
IMPORTANT: カスタム設定を使用すると高度なオプションが有効になりますが、Angularチームは設定ファイル固有の内容や、その中で使用されるサードパーティ製プラグインに対する直接的なサポートは提供しません。また、CLIは適切な動作を保証するために、特定のプロパティ（test.projects、test.include）を上書きします。
デフォルト設定を上書きするために、カスタムのVitest設定ファイルを提供できます。利用可能なオプションの完全なリストについては、公式のVitestドキュメントを参照してください。
1. 直接パス:
angular.jsonで、Vitest設定ファイルへの直接パスを指定します:
{ "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "runnerConfig": "vitest.config.ts" } } } } }}2. ベース設定の自動検索:
runnerConfigをtrueに設定すると、ビルダーはプロジェクトとワークスペースのルートで共有のvitest-base.config.*ファイルを自動的に検索します。
バグレポート
問題や機能のリクエストはGitHubで報告してください。
チームが問題に対処するのを助けるため、可能な限り最小限の再現手順を提供してください。