Referencja konfiguracji przeglądarki

Możesz zmienić konfigurację przeglądarki, aktualizując pole test.browser w swoim pliku konfiguracyjnym. Przykład prostego pliku konfiguracyjnego:

import { defineConfig } from 'vitest/config';

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

Zachęcam do zapoznania się z artykułem "Referencja konfiguracji" dla różnych przykładów konfiguracji.

WARNING

Wszystkie wymienione opcje na tej stronie znajdują się wewnątrz właściwości test.browser w konfiguracji:

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

browser.enabled

• Typ: boolean
• Domyślnie: false
• CLI: --browser, --browser.enabled=false

Domyślnie wszystkie testy są uruchamiane w przeglądarce. Należy pamiętać, że --browser działa tylko, jeśli masz co najmniej jeden element browser.instances.

browser.instances

• Typ: BrowserConfig
• Domyślnie: [{ browser: name }]

Definiuje wiele konfiguracji przeglądarek. Każda konfiguracja musi mieć co najmniej właściwość browser. Konfiguracja wspiera ustawienia twoich dostawców:

• Konfiguracja Playwright
• Konfiguracja WebdriverIO

TIP

Aby uzyskać lepsze bezpieczeństwo typów podczas korzystania z wbudowanych dostawców, powinieneś odwołać się do jednego z tych typów (dla używanego dostawcy) w swoim pliku konfiguracyjnym:

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

Dodatkowo, możesz również określić większość opcji projektu (nieoznaczonych ikoną *) oraz niektóre opcje browser takie jak browser.testerHtmlPath.

WARNING

Każda konfiguracja przeglądarki dziedziczy opcje z konfiguracji głównej:

export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // będzie miał oba pliki ustawień: "root" i "browser"
          setupFiles: ['./browser-setup-file.js'],
          // domyślnie ma "testerHtmlPath" z konfiguracji głównej
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

Podczas rozwoju aplikacji, Vitest wspiera tylko jedną konfigurację z widocznym interfejsem. Możesz samodzielnie uruchomić projekt w trybie graficznym, określając headless: false w konfiguracji, lub podając flagę --browser.headless=false, lub filtrując projekty flagą --project=chromium.

Więcej przykładów znajdziesz w przewodniku "Wiele konfiguracji".

Lista dostępnych opcji browser:

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

Domyślnie Vitest tworzy tablicę z pojedynczym elementem, który używa pola browser.name jako browser. Zauważ, że to zachowanie zostanie usunięte w wersji Vitest 4.

Wewnętrznie, Vitest przekształca te instancje w oddzielne projekty testowe współdzielące jeden serwer Vite dla lepszej wydajności buforowania.

browser.name przestarzałe

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

PRZESTARZAŁE

To API jest przestarzałe i zostanie usunięte w Vitest 4. Zamiast tego użyj opcji browser.instances.

Uruchom wszystkie testy w określonej przeglądarce. Możliwe opcje w różnych dostawcach:

• webdriverio: firefox, chrome, edge, safari
• playwright: firefox, webkit, chromium
• niestandardowe: dowolny ciąg znaków, który zostanie przekazany do dostawcy

browser.headless

• Typ: boolean
• Domyślnie: process.env.CI
• CLI: --browser.headless, --browser.headless=false

Uruchom przeglądarkę w trybie headless (bez interfejsu graficznego). Jeśli uruchamiasz Vitest w CI, będzie on domyślnie włączony.

browser.isolate

• Typ: boolean
• Domyślnie: true
• CLI: --browser.isolate, --browser.isolate=false

Uruchom każdy test w oddzielnej ramce iframe.

browser.testerHtmlPath

• Typ: string

Ścieżka do punktu wejścia HTML. Może być względna względem katalogu głównego projektu. Ten plik zostanie przetworzony za pomocą haka transformIndexHtml.

browser.api

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

Skonfiguruj opcje dla serwera Vite, który serwuje kod w przeglądarce. Nie wpływa na opcję test.api. Domyślnie Vitest przypisuje port 63315, aby uniknąć konfliktów z serwerem deweloperskim, umożliwiając równoległe uruchamianie obu.

browser.provider

• Typ: 'webdriverio' | 'playwright' | 'preview' | string
• Domyślnie: 'preview'
• CLI: --browser.provider=playwright

Ścieżka do dostawcy, który zostanie użyty podczas uruchamiania testów przeglądarkowych. Vitest udostępnia trzech dostawców: preview (domyślny), webdriverio i playwright. Niestandardowi dostawcy powinni być eksportowani za pomocą eksportu default i mieć następującą strukturę:

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

ZAAWANSOWANE API

API niestandardowego dostawcy jest wysoce eksperymentalne i może ulec zmianie między poprawkami. Jeśli potrzebujesz tylko uruchomić testy w przeglądarce, użyj zamiast tego opcji browser.instances.

browser.providerOptions przestarzałe

• Typ: BrowserProviderOptions

PRZESTARZAŁE

To API jest przestarzałe i zostanie usunięte w Vitest 4. Zamiast tego użyj opcji browser.instances.

Opcje, które zostaną przekazane do dostawcy podczas wywoływania provider.initialize.

import { defineConfig } from 'vitest/config';

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

TIP

Aby uzyskać lepsze bezpieczeństwo typów podczas korzystania z wbudowanych dostawców, powinieneś odwołać się do jednego z tych typów (dla używanego dostawcy) w swoim pliku konfiguracyjnym:

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

browser.ui

• Typ: boolean
• Domyślnie: !isCI
• CLI: --browser.ui=false

Czy interfejs użytkownika Vitest powinien być dodawany na stronę? Domyślnie dodaje ramkę iframe interfejsu użytkownika podczas rozwoju.

browser.viewport

• Typ: { width, height }
• Domyślnie: 414x896

Domyślny obszar widoku ramki iframe.

browser.locators

Opcje dla wbudowanych lokatorów przeglądarki.

browser.locators.testIdAttribute

• Typ: string
• Domyślnie: data-testid

Atrybut używany do znajdowania elementów za pomocą lokatora getByTestId.

browser.screenshotDirectory

• Typ: string
• Domyślnie: __screenshots__ w katalogu pliku testowego

Ścieżka do katalogu zrzutów ekranu względem root.

browser.screenshotFailures

• Typ: boolean
• Domyślnie: !browser.ui

Czy Vitest powinien robić zrzuty ekranu, jeśli test się nie powiedzie.

browser.orchestratorScripts

• Typ: BrowserScript[]
• Domyślnie: []

Niestandardowe skrypty, które powinny zostać wstrzyknięte do HTML orkiestratora przed zainicjowaniem ramek iframe testowych. Ten dokument HTML tylko konfiguruje ramki iframe i nie importuje bezpośrednio twojego kodu.

src i content skryptu zostaną przetworzone przez wtyczki Vite. Skrypt powinien być dostarczony w następującej formie:

export interface BrowserScript {
  /**
   * Jeśli podano "content" i typ jest "module", będzie to jego identyfikator.
   *
   * Jeśli używasz TypeScript, możesz tutaj dodać rozszerzenie `.ts` na przykład.
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * Zawartość JavaScript do wstrzyknięcia. Ten ciąg jest przetwarzany przez wtyczki Vite, jeśli typ jest "module".
   *
   * Możesz użyć `id`, aby dać Vite wskazówkę dotyczącą rozszerzenia pliku.
   */
  content?: string;
  /**
   * Ścieżka do skryptu. Ta wartość jest rozwiązywana przez Vite, więc może to być moduł Node.js lub ścieżka pliku.
   */
  src?: string;
  /**
   * Czy skrypt powinien być ładowany asynchronicznie.
   */
  async?: boolean;
  /**
   * Typ skryptu.
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

• Typ: BrowserScript[]
• Domyślnie: []

PRZESTARZAŁE

To API jest przestarzałe i zostanie usunięte w Vitest 4. Zamiast tego użyj pola browser.testerHtmlPath.

Niestandardowe skrypty, które powinny zostać wstrzyknięte do HTML testera przed zainicjowaniem środowiska testowego. Jest to przydatne do wstrzykiwania polyfilli wymaganych do działania Vitest w przeglądarce. Zaleca się używanie setupFiles w większości przypadkach zamiast tej opcji.

src i content skryptu zostaną przetworzone przez wtyczki Vite.

browser.commands

• Typ: Record<string, BrowserCommand>
• Domyślnie: { readFile, writeFile, ... }

Niestandardowe polecenia, które można importować podczas testów przeglądarkowych z @vitest/browser/commands.

browser.connectTimeout

• Typ: number
• Domyślnie: 60_000

Limit czasu w milisekundach. Jeśli połączenie z przeglądarką trwa dłużej, zestaw testów zakończy się niepowodzeniem.

INFO

To jest czas potrzebny przeglądarce na nawiązanie połączenia WebSocket z serwerem Vitest. W normalnych okolicznościach ten limit czasu nigdy nie powinien zostać osiągnięty.