ブラウザ設定リファレンス

ブラウザ設定は、設定ファイルの test.browser フィールドを更新することで変更可能です。シンプルな設定ファイルの例は次の通りです。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [
        {
          browser: 'chromium',
          setupFile: './chromium-setup.js',
        },
      ],
    },
  },
});

さまざまな設定例については、「設定リファレンス」の記事をご参照ください。

WARNING

このページに記載されている_すべてのオプション_は、設定の test プロパティ内に記述します。

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

browser.enabled

• 型: boolean
• デフォルト: false
• CLI: --browser, --browser.enabled=false

デフォルトで全てのテストをブラウザ内で実行します。--browser は、少なくとも1つの browser.instances エントリがある場合にのみ機能することに注意してください。

browser.instances

• 型: BrowserConfig
• デフォルト: [{ browser: name }]

複数のブラウザ設定を定義できます。各設定には、少なくとも browser フィールドが必須です。この設定は、プロバイダーごとの設定に対応しています。

• Playwright の設定
• WebdriverIO の設定

TIP

組み込みプロバイダーを使用する際に型安全性を高めるには、設定ファイルで以下のいずれかの型（使用しているプロバイダー用）を参照する必要があります。

/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

さらに、プロジェクトオプションのほとんど（* アイコンが付いていないもの）と、browser.testerHtmlPath のような一部の browser オプションも指定できます。

WARNING

各ブラウザ設定は、ルート設定からオプションを継承します。

export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // ルートとブラウザ、両方のセットアップファイルが適用されます
          setupFile: ['./browser-setup-file.js'],
          // ルート設定の "testerHtmlPath" が暗黙的に適用されます
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

開発中、Vitest はヘッドレスではない設定を1つのみサポートしています。headless: false を設定で指定するか、--browser.headless=false フラグを指定するか、--project=chromium フラグでプロジェクトをフィルタリングすることで、ヘッドレスモードではないプロジェクトを制限できます。

詳細な例については、「複数のセットアップ」ガイドを参照してください。

利用可能な browser オプションのリスト：

• browser.headless
• browser.locators
• browser.viewport
• browser.testerHtmlPath
• browser.screenshotDirectory
• browser.screenshotFailures

デフォルトでは、Vitest は browser.name フィールドを browser として使用する単一の要素を持つ配列を生成します。この動作は Vitest 4 で廃止される予定です。

内部的には、Vitest はこれらのインスタンスを個別のテストプロジェクトに変換し、単一の Vite サーバーを共有することでキャッシュパフォーマンスを向上させます。

browser.name 非推奨

• 型: string
• CLI: --browser=safari

廃止予定

この API は非推奨であり、Vitest 4 で廃止されます。代わりに browser.instances オプションを使用してください。

特定のブラウザで全てのテストを実行します。異なるプロバイダーでの利用可能なオプションは以下の通りです。

• webdriverio: firefox, chrome, edge, safari
• playwright: firefox, webkit, chromium
• カスタム: プロバイダーに渡される任意の文字列です。

browser.headless

• 型: boolean
• デフォルト: process.env.CI
• CLI: --browser.headless, --browser.headless=false

ブラウザを headless モードで実行します。CI 環境で Vitest を実行している場合、デフォルトで有効になります。

browser.isolate

• 型: boolean
• デフォルト: true
• CLI: --browser.isolate, --browser.isolate=false

各テストを個別の iframe で実行します。

browser.testerHtmlPath

• 型: string

HTML エントリポイントへのパスです。プロジェクトのルートからの相対パスで指定できます。このファイルは transformIndexHtml フックによって処理されます。

browser.api

• 型: number | { port?, strictPort?, host? }
• デフォルト: 63315
• CLI: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

ブラウザでコードを提供する Vite サーバーのオプションを設定します。test.api オプションには影響しません。デフォルトでは、Vitest は開発サーバーとの競合を避けるため、ポート 63315 を割り当て、両方を並行して実行できるようにします。

browser.provider

• 型: 'webdriverio' | 'playwright' | 'preview' | string
• デフォルト: 'preview'
• CLI: --browser.provider=playwright

ブラウザテストの実行時に使用されるプロバイダーへのパスです。Vitest は、preview (デフォルト)、webdriverio、playwright の3つのプロバイダーを提供しています。カスタムプロバイダーは default エクスポートを使用してエクスポートし、以下の形式である必要があります。

export interface BrowserProvider {
  name: string;
  supportsParallelism: boolean;
  getSupportedBrowsers: () => readonly string[];
  beforeCommand?: (command: string, args: unknown[]) => Awaitable<void>;
  afterCommand?: (command: string, args: unknown[]) => Awaitable<void>;
  getCommandsContext: (sessionId: string) => Record<string, unknown>;
  openPage: (
    sessionId: string,
    url: string,
    beforeNavigate?: () => Promise<void>
  ) => Promise<void>;
  getCDPSession?: (sessionId: string) => Promise<CDPSession>;
  close: () => Awaitable<void>;
  initialize(
    ctx: TestProject,
    options: BrowserProviderInitializationOptions
  ): Awaitable<void>;
}

高度な API

カスタムプロバイダー API は非常に実験的であり、パッチリリース間で変更される可能性があります。ブラウザでテストを実行するだけであれば、代わりに browser.instances オプションを使用してください。

browser.providerOptions 非推奨

• 型: BrowserProviderOptions

廃止予定

この API は非推奨であり、Vitest 4 で廃止されます。代わりに browser.instances オプションを使用してください。

provider.initialize を呼び出すときにプロバイダーに渡されるオプションです。

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
      },
    },
  },
});

TIP

組み込みプロバイダーを使用する際に型安全性を高めるには、設定ファイルで以下のいずれかの型（使用しているプロバイダー用）を参照する必要があります。

/// <reference types="@vitest/browser/providers/playwright" />
/// <reference types="@vitest/browser/providers/webdriverio" />

browser.ui

• 型: boolean
• デフォルト: !isCI
• CLI: --browser.ui=false

Vitest UI をページに注入するかどうかです。デフォルトでは、開発中に UI iframe が注入されます。

browser.viewport

• 型: { width, height }
• デフォルト: 414x896

デフォルトの iframe のビューポートです。

browser.locators

組み込みのブラウザロケータのオプション。

browser.locators.testIdAttribute

• 型: string
• デフォルト: data-testid

getByTestId ロケータで要素を見つけるために使用される属性です。

browser.screenshotDirectory

• 型: string
• デフォルト: テストファイルディレクトリ内の __screenshots__

root からの相対パスでスクリーンショットディレクトリへのパスです。

browser.screenshotFailures

• 型: boolean
• デフォルト: !browser.ui

テストが失敗した場合に Vitest がスクリーンショットを撮るべきかどうかです。

browser.orchestratorScripts

• 型: BrowserScript[]
• デフォルト: []

テスト iframe が初期化される前にオーケストレータ HTML に注入されるカスタムスクリプトです。この HTML ドキュメントは iframe をセットアップするだけであり、実際にはコードをインポートしません。

スクリプトの src と content は Vite プラグインによって処理されます。スクリプトは以下の形式で提供する必要があります。

export interface BrowserScript {
  /**
   * "content" が提供され、型が "module" の場合、これがその識別子となります。
   *
   * TypeScript を使用している場合、例えばここに `.ts` 拡張子を追加できます。
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * 注入される JavaScript コンテンツです。型が "module" の場合、この文字列は Vite プラグインによって処理されます。
   *
   * `id` を使用して、Vite にファイル拡張子に関するヒントを与えることが可能です。
   */
  content?: string;
  /**
   * スクリプトへのパスです。この値は Vite によって解決されるため、Node.js モジュールまたはファイルパスとして指定できます。
   */
  src?: string;
  /**
   * スクリプトを非同期でロードする必要があるかどうかです。
   */
  async?: boolean;
  /**
   * スクリプトの型です。
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

• 型: BrowserScript[]
• デフォルト: []

廃止予定

この API は非推奨であり、Vitest 4 で廃止されます。代わりに browser.testerHtmlPath フィールドを使用してください。

テスト環境が初期化される前にテスター HTML に注入されるカスタムスクリプトです。これは Vitest のブラウザ実装に必要なポリフィルを注入するのに役立ちます。ほとんどの場合、これの代わりに setupFiles を使用することが推奨されます。

スクリプトの src と content は Vite プラグインによって処理されます。

browser.commands

• 型: Record<string, BrowserCommand>
• デフォルト: { readFile, writeFile, ... }

ブラウザテスト中に @vitest/browser/commands からインポートできるカスタムコマンドです。

browser.connectTimeout

• 型: number
• デフォルト: 60000

タイムアウト（ミリ秒単位）です。ブラウザへの接続にこれより時間がかかる場合、テストスイートは失敗します。

INFO

これは、ブラウザが Vitest サーバーとの WebSocket 接続を確立するのにかかる時間です。通常の状況では、このタイムアウトに達することはありません。