Référence de configuration du navigateur

Vous pouvez modifier la configuration du navigateur en mettant à jour le champ test.browser dans votre fichier de configuration. Voici un exemple de fichier de configuration simple :

import { defineConfig } from 'vitest/config';

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

Veuillez consulter l'article "Référence de configuration" pour des exemples de configuration variés.

WARNING

Toutes les options listées sur cette page se trouvent dans une propriété test à l'intérieur de la configuration :

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

browser.enabled

• Type : boolean
• Par défaut : false
• CLI : --browser, --browser.enabled=false

Exécute par défaut tous les tests dans un navigateur. Notez que --browser ne fonctionne que si vous avez au moins un élément browser.instances configuré.

browser.instances

• Type : BrowserConfig[]
• Par défaut : [{ browser: name }]

Définit plusieurs configurations de navigateurs. Chaque configuration doit comporter au moins un champ browser. La configuration prend en charge les configurations spécifiques à vos fournisseurs :

• Configuration de Playwright
• Configuration de WebdriverIO

TIP

Pour une meilleure vérification des types lors de l'utilisation des fournisseurs intégrés, vous devez référencer l'un de ces types (pour le fournisseur que vous utilisez) dans votre fichier de configuration :

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

De plus, vous pouvez également spécifier la plupart des options de projet (non marquées d'une icône *) et certaines des options browser comme browser.testerHtmlPath.

WARNING

Chaque configuration de navigateur hérite des options de la configuration racine :

export default defineConfig({
  test: {
    setupFile: ['./root-setup-file.js'],
    browser: {
      enabled: true,
      testerHtmlPath: './custom-path.html',
      instances: [
        {
          // aura les deux fichiers de configuration : "root" et "browser"
          setupFile: ['./browser-setup-file.js'],
          // hérite implicitement de "testerHtmlPath" depuis la configuration racine
          // testerHtmlPath: './custom-path.html',
        },
      ],
    },
  },
})

Pendant le développement, Vitest ne prend en charge qu'une seule configuration non-headless. Vous pouvez limiter l'utilisation du mode visible (non-headless) pour un projet en spécifiant headless: false dans la configuration, ou en fournissant le drapeau --browser.headless=false, ou en filtrant les projets avec le drapeau --project=chromium.

Pour plus d'exemples, consultez le guide "Configurations multiples" (Multiple Setups).

Liste des options browser disponibles :

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

Par défaut, Vitest crée un tableau avec un seul élément qui utilise le champ browser.name comme browser. Notez que ce comportement sera supprimé à partir de Vitest 4.

Sous le capot, Vitest transforme ces instances en projets de test distincts partageant un seul serveur Vite pour de meilleures performances de mise en cache.

browser.name déprécié

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

DÉPRÉCIÉ

Cette API est dépréciée et sera retirée dans Vitest 4. Veuillez utiliser l'option browser.instances à la place.

Permet d'exécuter tous les tests dans un navigateur spécifique. Valeurs possibles selon les fournisseurs :

• webdriverio : firefox, chrome, edge, safari
• playwright : firefox, webkit, chromium
• personnalisé : toute chaîne qui sera passée au fournisseur

browser.headless

• Type : boolean
• Par défaut : process.env.CI
• CLI : --browser.headless, --browser.headless=false

Exécute le navigateur en mode headless (sans interface graphique). Si vous exécutez Vitest en CI, ce mode sera activé par défaut.

browser.isolate

• Type : boolean
• Par défaut : true
• CLI : --browser.isolate, --browser.isolate=false

Exécute chaque test dans un iframe séparé.

browser.testerHtmlPath

• Type : string

Le chemin d'accès au point d'entrée HTML. Peut être relatif à la racine du projet. Ce fichier sera traité avec le hook transformIndexHtml.

browser.api

• Type : number | { port?, strictPort?, host? }
• Par défaut : 63315
• CLI : --browser.api=63315, --browser.api.port=1234, --browser.api.host=example.com

Configure les options du serveur Vite qui sert le code au navigateur. N'affecte pas l'option test.api. Par défaut, Vitest attribue le port 63315 pour éviter les conflits avec le serveur de développement, vous permettant de les exécuter en parallèle.

browser.provider

• Type : 'webdriverio' | 'playwright' | 'preview' | string
• Par défaut : 'preview'
• CLI : --browser.provider=playwright

Le chemin d'accès à un fournisseur qui sera utilisé lors de l'exécution des tests de navigateur. Vitest fournit trois fournisseurs intégrés : preview (par défaut), webdriverio et playwright. Les fournisseurs personnalisés doivent être exportés en utilisant l'exportation default et doivent respecter la forme suivante :

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 AVANCÉE

L'API du fournisseur personnalisé est hautement expérimentale et peut changer d'une version corrective à l'autre. Si vous avez juste besoin d'exécuter des tests dans un navigateur, utilisez plutôt l'option browser.instances.

browser.providerOptions déprécié

• Type : BrowserProviderOptions

DÉPRÉCIÉ

Cette API est dépréciée et sera retirée dans Vitest 4. Veuillez utiliser l'option browser.instances à la place.

Options à transmettre au fournisseur lors de l'appel de provider.initialize.

import { defineConfig } from 'vitest/config';

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

TIP

Pour une meilleure vérification des types lors de l'utilisation des fournisseurs intégrés, vous devez référencer l'un de ces types (pour le fournisseur que vous utilisez) dans votre fichier de configuration :

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

browser.ui

• Type : boolean
• Par défaut : !isCI
• CLI : --browser.ui=false

Indique si l'interface utilisateur de Vitest doit être injectée dans la page. Par défaut, l'iframe de l'interface utilisateur est injectée pendant le développement.

browser.viewport

• Type : { width, height }
• Par défaut : 414x896

La fenêtre d'affichage par défaut de l'iframe.

browser.locators

Options des localisateurs de navigateur intégrés.

browser.locators.testIdAttribute

• Type : string
• Par défaut : data-testid

Attribut servant à trouver des éléments avec le localisateur getByTestId.

browser.screenshotDirectory

• Type : string
• Par défaut : __screenshots__ dans le répertoire du fichier de test

Le chemin d'accès au répertoire des captures d'écran, relatif à la root du projet.

browser.screenshotFailures

• Type : boolean
• Par défaut : !browser.ui

Indique si Vitest doit prendre des captures d'écran en cas d'échec du test.

browser.orchestratorScripts

• Type : BrowserScript[]
• Par défaut : []

Scripts personnalisés à injecter dans le HTML de l'orchestrateur avant l'initialisation des iframes de test. Ce document HTML ne configure que les iframes et n'inclut pas réellement votre code.

Le src et le content des scripts seront traités par les plugins Vite. Le script doit être fourni sous la forme suivante :

export interface BrowserScript {
  /**
   * Si "content" est fourni et que le type est "module", il servira d'identifiant.
   *
   * Si vous utilisez TypeScript, vous pouvez par exemple ajouter l'extension `.ts` ici.
   * @default `injected-${index}.js`
   */
  id?: string;
  /**
   * Contenu JavaScript à injecter. Les plugins Vite traitent cette chaîne si le type est "module".
   *
   * Vous pouvez utiliser `id` pour fournir à Vite une indication sur l'extension du fichier.
   */
  content?: string;
  /**
   * Le chemin d'accès au script. Cette valeur est résolue par Vite et peut donc pointer vers un module Node ou un fichier local.
   */
  src?: string;
  /**
   * Indique si le script doit être chargé de manière asynchrone.
   */
  async?: boolean;
  /**
   * Type de script.
   * @default 'module'
   */
  type?: string;
}

browser.testerScripts

• Type : BrowserScript[]
• Par défaut : []

DÉPRÉCIÉ

Cette API est dépréciée et sera retirée dans Vitest 4. Veuillez utiliser le champ browser.testerHtmlPath à la place.

Scripts personnalisés à injecter dans le HTML du testeur avant l'initialisation de l'environnement de test. Ceci est utile pour injecter des polyfills nécessaires à l'implémentation du navigateur Vitest. Il est recommandé d'utiliser setupFiles dans presque tous les cas, plutôt que cette option.

Le src et le content des scripts seront traités par les plugins Vite.

browser.commands

• Type : Record<string, BrowserCommand>
• Par défaut : { readFile, writeFile, ... }

Commandes personnalisées importables pendant les tests de navigateur depuis @vitest/browser/commands.

browser.connectTimeout

• Type : number
• Par défaut : 60_000

Le délai d'attente, en millisecondes. Si la connexion au navigateur prend plus de temps, la suite de tests échouera.

INFO

Il s'agit du temps nécessaire au navigateur pour établir la connexion WebSocket avec le serveur Vitest. Dans des circonstances normales, ce délai ne devrait jamais être dépassé.