ブラウザモード 実験的

このページでは、Vitest API の実験的なブラウザモード機能について説明します。この機能を使用すると、window や document などのブラウザのグローバルオブジェクトにアクセスし、ブラウザ上でネイティブにテストを実行できます。この機能は現在開発中であり、API は将来変更される可能性があります。

ブラウザの互換性

Vitest は、テストを実行するために Vite dev server を使用するため、esbuild.target オプション（デフォルトでは esnext）で指定された機能のみをサポートします。

デフォルトでは、Vite は、ネイティブ ES Modules、ネイティブ ESM 動的インポート、および import.meta をサポートするブラウザを対象としています。さらに、iframe 間で通信するために BroadcastChannel を利用しています。

• Chrome >= 87
• Firefox >= 78
• Safari >= 15.4
• Edge >= 88

目的

Vitest のブラウザモード機能は、テストワークフローを改善し、より正確で信頼性の高いテスト結果を得るために開発されました。このテスト API に実験的に追加された機能により、開発者はネイティブなブラウザ環境でテストを実行できます。このセクションでは、この機能の背後にある目的と、テストにおける利点について説明します。

テスト方法の比較

JavaScript コードをテストする方法はいくつか存在します。一部のテストフレームワークは Node.js でブラウザ環境をシミュレートしますが、実際のブラウザでテストを実行するものもあります。例として、jsdom は、Jest や Vitest などのテストランナーで使用され、ブラウザ環境をシミュレートする仕様の実装です。WebdriverIO や Cypress などのテストツールを使用すると、開発者は実際のブラウザでアプリケーションをテストできます。また、Playwright は、独自のブラウザエンジンを提供します。

シミュレーション環境に関する注意点

jsdom や happy-dom などのシミュレートされた環境で JavaScript プログラムをテストすると、テストのセットアップが簡素化され、使いやすい API が提供されるため、多くのプロジェクトに適しており、テスト結果の信頼性向上に貢献します。ただし、これらのツールはブラウザ環境をシミュレートするだけであり、実際のブラウザではないことを理解しておくことが重要です。これにより、シミュレーション環境と実際の環境の間に差異が生じる可能性があり、テスト結果に誤検出が発生する可能性があります。

より高い信頼性を得るためには、実際のブラウザ環境でテストすることが重要です。これが、Vitest でブラウザモード機能を開発した理由であり、開発者はブラウザ上でネイティブにテストを実行し、より正確で信頼性の高いテスト結果を得ることができます。ブラウザレベルのテストを使用することで、開発者はアプリケーションが実際のシナリオで意図したとおりに動作することをより確信できます。

欠点

Vitest ブラウザを使用する際には、以下の欠点を考慮する必要があります。

開発初期段階であること

Vitest のブラウザモード機能は、まだ開発の初期段階にあります。そのため、完全に最適化されていない可能性があります。WebdriverIO、Cypress、Playwright などのスタンドアロンのブラウザ側テストランナーで Vitest ブラウザの機能を補完することを推奨します。

初期化に時間がかかること

Vitest ブラウザでは、初期化プロセス中にプロバイダーとブラウザを起動する必要があるため、時間がかかる場合があります。そのため、他のテスト方法よりも初期化に時間がかかる場合があります。

設定

Vitest 設定でブラウザモードを有効にするには、--browser フラグを使用するか、Vitest 設定ファイルで browser.enabled フィールドを true に設定します。以下に、ブラウザフィールドを使用した設定例を示します。

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      name: 'chrome', // ブラウザ名は必須
    },
  },
});

ブラウザオプションの型

Vitest のブラウザオプションはプロバイダーによって異なります。--browser を指定し、設定ファイルで name を指定しない場合、Vitest はエラーになります。利用可能なオプションは以下のとおりです。

• webdriverio (デフォルト) は、次のブラウザをサポートしています。
  • firefox
  • chrome
  • edge
  • safari
• playwright は、次のブラウザをサポートしています。
  • firefox
  • webkit
  • chromium

クロスブラウザテスト

ブラウザオプションでブラウザ名を指定すると、Vitest はデフォルトで WebdriverIO を使用して指定されたブラウザを起動し、そこでテストを実行します。この機能により、CI 環境でクロスブラウザテストを簡単に行うことができます。WebdriverIO を使用したくない場合は、browser.provider オプションを使用してカスタムブラウザプロバイダーを設定できます。

CLI を使用してブラウザを指定するには、--browser フラグの後にブラウザ名を指定します。次に例を示します。

npx vitest --browser=chrome

または、ドット表記でブラウザオプションを CLI に指定することもできます。

npx vitest --browser.name=chrome --browser.headless

NOTE

WebdriverIO で Safari ブラウザオプションを使用する場合は、デバイスで sudo safaridriver --enable を実行して safaridriver を有効にする必要があります。

さらに、テストを実行すると、Vitest は safaridriver との互換性のために必要なドライバーをインストールしようとします。

ヘッドレスモード

ヘッドレスモードは、ブラウザモードで使用できるオプションの 1 つです。ヘッドレスモードでは、ブラウザはユーザーインターフェイスなしでバックグラウンドで実行されるため、自動テストの実行に役立ちます。Vitest の headless オプションは、真偽値で設定可能で、ヘッドレスモードを有効または無効にできます。

ヘッドレスモードを有効にする設定例を次に示します。

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      headless: true,
    },
  },
});

CLI で --browser.headless フラグを使用して、ヘッドレスモードを設定することもできます。次に例を示します。

npx vitest --browser.name=chrome --browser.headless

この場合、Vitest は Chrome ブラウザでヘッドレスモードを実行します。

制限事項

スレッドブロッキングダイアログ

Vitest ブラウザを使用する場合、alert や confirm などのスレッドブロッキングダイアログはネイティブには使用できないことに注意してください。これは、これらのダイアログが Web ページをブロックするため、Vitest がページとの通信を継続できなくなり、実行が停止するためです。

このような状況では、Vitest はこれらの API のデフォルト値を持つモックを提供します。これにより、ユーザーが誤って同期ポップアップ Web API を使用した場合でも、実行が停止することを防ぎます。ただし、より良いエクスペリエンスのために、これらの Web API をモックすることを推奨します。詳細については、モックを参照してください。