ブラウザモード 実験的

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

ブラウザの互換性

Vitestは、Vite開発サーバーを使用してテストを実行するため、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', // browser name is required
    },
  }
})

ブラウザオプションのタイプ

Vitestのbrowserオプションは、プロバイダーによって異なります。設定ファイルで名前を指定せずに`--browser`を渡すと、Vitestは失敗します。利用可能なオプション：

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

クロスブラウザテスト

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

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

npx vitest --browser=chrome

または、ドット表記を使用してCLIにブラウザオプションを提供できます。

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

注意

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

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

ヘッドレスモード

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

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

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をモックすることをお勧めします。詳細については、モッキングをご覧ください。