Referenz für Browserkonfiguration

Sie können die Browserkonfiguration ändern, indem Sie das Feld test.browser in Ihrer Konfigurationsdatei aktualisieren. Ein Beispiel für eine einfache Konfigurationsdatei:

import { defineConfig } from 'vitest/config';

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

Bitte konsultieren Sie den Artikel "Konfigurationsreferenz" für verschiedene Konfigurationsbeispiele.

WARNING

Alle aufgeführten Optionen auf dieser Seite befinden sich innerhalb der test-Eigenschaft der Konfiguration:

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

browser.enabled

Typ: boolean
Standard: false
CLI: --browser, --browser.enabled=false

Führt standardmäßig alle Tests in der Browser-Umgebung aus. Beachten Sie, dass --browser nur funktioniert, wenn Sie mindestens einen Eintrag unter browser.instances definiert haben.

browser.instances

Typ: BrowserConfig
Standard: [{ browser: name }]

Definiert mehrere Browser-Setups. Jede Konfiguration muss mindestens das Feld browser enthalten. Die Konfiguration unterstützt die Provider-Konfigurationen:

TIP

Um eine bessere Typsicherheit bei der Verwendung integrierter Provider zu gewährleisten, sollten Sie einen dieser Typen (für den von Ihnen verwendeten Provider) in Ihrer Konfigurationsdatei referenzieren:

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

Zusätzlich können Sie auch die meisten der Projektoptionen (nicht mit einem *-Symbol gekennzeichnet) sowie einige der browser-Optionen wie browser.testerHtmlPath festlegen.

WARNING

Jede Browser-Konfiguration erbt Optionen von der Root-Konfiguration:

export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // wird beide Setup-Dateien haben: "root" und "browser"
          setupFile: ['./browser-setup-file.js'],
          // erbt implizit "testerHtmlPath" aus der Root-Konfiguration
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

Während der Entwicklung unterstützt Vitest nur eine Konfiguration, die nicht im Headless-Modus läuft. Sie können das Headed-Projekt selbst einschränken, indem Sie headless: false in der Konfiguration angeben, das Flag --browser.headless=false verwenden oder Projekte mit dem Flag --project=chromium filtern.

Weitere Beispiele finden Sie im Leitfaden "Mehrere Setups".

Liste der verfügbaren browser-Optionen:

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

Standardmäßig erstellt Vitest ein Array mit einem einzelnen Element, das das Feld browser.name als Browser-Namen verwendet. Beachten Sie, dass dieses Verhalten ab Vitest 4 entfernt wird.

Im Hintergrund transformiert Vitest diese Instanzen in separate Testprojekte, die einen einzigen Vite-Server für eine bessere Caching-Leistung nutzen.

browser.name veraltet

Typ: string
CLI: --browser=safari

VERALTET

Diese API ist veraltet und wird in Vitest 4 entfernt. Bitte verwenden Sie stattdessen die Option browser.instances.

Führt alle Tests in einem bestimmten Browser aus. Mögliche Optionen für verschiedene Provider:

webdriverio: firefox, chrome, edge, safari
playwright: firefox, webkit, chromium
benutzerdefiniert: beliebiger String, der an den Provider übergeben wird

browser.headless

Typ: boolean
Standard: process.env.CI
CLI: --browser.headless, --browser.headless=false

Startet den Browser im headless-Modus. Wenn Sie Vitest in CI ausführen, wird der Headless-Modus standardmäßig aktiviert.

browser.isolate

Typ: boolean
Standard: true
CLI: --browser.isolate, --browser.isolate=false

Führt jeden Test in einem eigenen Iframe aus.

browser.testerHtmlPath

Typ: string

Ein Pfad zum HTML-Einstiegspunkt. Kann relativ zum Root-Verzeichnis des Projekts sein. Diese Datei wird mit dem Hook transformIndexHtml verarbeitet.

browser.api

Typ: number | { port?, strictPort?, host? }
Standard: 63315
CLI: --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

Konfiguriert Optionen für den Vite-Server, der Code im Browser ausliefert. Hat keinen Einfluss auf die Option test.api. Standardmäßig verwendet Vitest den Port 63315, um Konflikte mit dem Entwicklungsserver zu vermeiden, sodass Sie beide parallel ausführen können.

browser.provider

Typ: 'webdriverio' | 'playwright' | 'preview' | string
Standard: 'preview'
CLI: --browser.provider=playwright

Pfad zum Provider, der beim Ausführen von Browser-Tests verwendet wird. Vitest bietet drei Provider: preview (Standard), webdriverio und playwright. Benutzerdefinierte Provider müssen als default-Export bereitgestellt werden und diese Form haben:

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>;
}

ERWEITERTE API

Die benutzerdefinierte Provider-API ist stark experimentell und kann sich mit Patches ändern. Wenn Sie Tests nur in einem Browser ausführen müssen, verwenden Sie stattdessen die Option browser.instances.

browser.providerOptions veraltet

Typ: BrowserProviderOptions

VERALTET

Diese API ist veraltet und wird in Vitest 4 entfernt. Bitte verwenden Sie stattdessen die Option browser.instances.

Optionen, die bei Aufruf von provider.initialize an den Provider übergeben werden.

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

Typ: boolean
Standard: !isCI
CLI: --browser.ui=false

Soll die Vitest-Benutzeroberfläche in die Seite injiziert werden? Standardmäßig wird das UI-Iframe während der Entwicklung injiziert.

browser.viewport

Typ: { width, height }
Standard: 414x896

Standard-Viewport für den Iframe.

browser.locators

Optionen für integrierte Browser-Locators.

browser.locators.testIdAttribute

Typ: string
Standard: data-testid

Attribut zur Identifizierung von Elementen mit dem getByTestId-Locator.

browser.screenshotDirectory

Typ: string
Standard: __screenshots__ im Testdateiverzeichnis

Pfad zum Screenshot-Verzeichnis relativ zum Root-Verzeichnis.

browser.screenshotFailures

Typ: boolean
Standard: !browser.ui

Soll Vitest bei Testfehlern Screenshots erstellen?

browser.orchestratorScripts

Typ: BrowserScript[]
Standard: []

Benutzerdefinierte Skripte, die vor der Initialisierung der Test-Iframes in das Orchestrator-HTML injiziert werden sollen. Dieses HTML-Dokument richtet nur Iframes ein und importiert Ihren Code nicht wirklich.

Die src- und content-Attribute des Skripts werden von Vite-Plugins verarbeitet. Das Skript sollte in der folgenden Form bereitgestellt werden:

export interface BrowserScript {
  /**
   * Wenn "content" bereitgestellt wird und der Typ "module" ist, ist dies seine Kennung.
   *
   * Wenn Sie TypeScript verwenden, können Sie hier beispielsweise die Erweiterung `.ts` hinzufügen.
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * JavaScript-Inhalt, der injiziert werden soll. Dieser String wird von Vite-Plugins verarbeitet, wenn der Typ "module" ist.
   *
   * Sie können "id" verwenden, um Vite einen Hinweis auf die Dateierweiterung zu geben.
   */
  content?: string;
  /**
   * Pfad zum Skript. Dieser Wert wird von Vite aufgelöst, sodass es sich um ein Node-Modul oder einen Dateipfad handeln kann.
   */
  src?: string;
  /**
   * Ob das Skript asynchron geladen werden soll.
   */
  async?: boolean;
  /**
   * Skripttyp.
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

Typ: BrowserScript[]
Standard: []

VERALTET

Diese API ist veraltet und wird in Vitest 4 entfernt. Bitte verwenden Sie stattdessen das Feld browser.testerHtmlPath.

Benutzerdefinierte Skripte, die vor der Initialisierung der Testumgebung in das Tester-HTML injiziert werden sollen. Dies ist nützlich, um Polyfills zu injizieren, die für die Vitest-Browser-Implementierung erforderlich sind. Es wird empfohlen, in fast allen Fällen setupFiles stattdessen zu verwenden.

Die src- und content-Attribute des Skripts werden von Vite-Plugins verarbeitet.

browser.commands

Typ: Record<string, BrowserCommand>
Standard: { readFile, writeFile, ... }

Benutzerdefinierte Befehle, die während Browser-Tests von @vitest/browser/commands importiert werden können.

browser.connectTimeout

Typ: number
Standard: 60_000

Das Timeout in Millisekunden. Wenn die Verbindung zum Browser länger dauert, schlägt die Testsuite fehl.

INFO

Dies ist die Zeit, die der Browser benötigt, um die WebSocket-Verbindung mit dem Vitest-Server herzustellen. Unter normalen Umständen sollte dieses Timeout niemals erreicht werden.

Referenz für Browserkonfiguration ​

browser.enabled ​

browser.instances ​

browser.name veraltet ​

browser.headless ​

browser.isolate ​

browser.testerHtmlPath ​

browser.api ​

browser.provider ​

browser.providerOptions veraltet ​

browser.ui ​

browser.viewport ​

browser.locators ​

browser.locators.testIdAttribute ​

browser.screenshotDirectory ​

browser.screenshotFailures ​

browser.orchestratorScripts ​

browser.testerScripts ​

browser.commands ​

browser.connectTimeout ​

Referenz für Browserkonfiguration

browser.enabled

browser.instances

browser.name veraltet

browser.headless

browser.isolate

browser.testerHtmlPath

browser.api

browser.provider

browser.providerOptions veraltet

browser.ui

browser.viewport

browser.locators

browser.locators.testIdAttribute

browser.screenshotDirectory

browser.screenshotFailures

browser.orchestratorScripts

browser.testerScripts

browser.commands

browser.connectTimeout