Mode Navigateur Expérimental

Cette page fournit des informations sur la fonctionnalité expérimentale du mode navigateur dans Vitest. Elle vous permet d'exécuter vos tests directement dans un navigateur, donnant ainsi accès aux objets globaux du navigateur tels que window et document. Cette fonctionnalité est actuellement en développement, et ses API sont susceptibles d'évoluer.

Installation

Pour faciliter la configuration, vous pouvez utiliser la commande vitest init browser afin d'installer les dépendances requises et de générer la configuration du navigateur.

npm

npx vitest init browser

yarn

yarn exec vitest init browser

pnpm

pnpx vitest init browser

bun

bunx vitest init browser

Installation Manuelle

Vous pouvez également installer les paquets manuellement. Par défaut, le mode Navigateur ne nécessite aucun fournisseur E2E supplémentaire pour exécuter les tests localement, car il utilise votre navigateur existant.

npm

npm install -D vitest @vitest/browser

yarn

yarn add -D vitest @vitest/browser

pnpm

pnpm add -D vitest @vitest/browser

bun

bun add -D vitest @vitest/browser

WARNING

Cependant, pour exécuter des tests en intégration continue (CI), vous devez installer soit playwright soit webdriverio. Nous recommandons également de passer à l'un de ces fournisseurs pour les tests locaux, plutôt que d'utiliser le fournisseur preview par défaut, car ce dernier repose sur la simulation d'événements au lieu d'utiliser le protocole Chrome DevTools.

Si vous n'utilisez pas déjà l'un de ces outils, nous vous conseillons de commencer par Playwright, qui prend en charge l'exécution parallèle et accélère vos tests. De plus, le protocole Chrome DevTools utilisé par Playwright est généralement plus rapide que WebDriver.

::: tabs key:provider == Playwright Playwright est un framework pour les tests et l'automatisation web.

npm

npm install -D vitest @vitest/browser playwright

yarn

yarn add -D vitest @vitest/browser playwright

pnpm

pnpm add -D vitest @vitest/browser playwright

bun

bun add -D vitest @vitest/browser playwright

== WebdriverIO

WebdriverIO vous permet d'exécuter des tests localement en utilisant le protocole WebDriver.

npm

npm

npm install -D vitest @vitest/browser webdriverio

yarn

yarn add -D vitest @vitest/browser webdriverio

pnpm

pnpm add -D vitest @vitest/browser webdriverio

bun

bun add -D vitest @vitest/browser webdriverio

Configuration

Pour activer le mode navigateur dans votre configuration Vitest, vous pouvez utiliser l'option --browser ou définir le champ browser.enabled sur true dans votre fichier de configuration Vitest. Voici un exemple de configuration utilisant le champ browser :

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright', // ou 'webdriverio'
      enabled: true,
      name: 'chromium', // le nom du navigateur est requis
    },
  },
});

INFO

Vitest attribue le port 63315 pour éviter les conflits avec le serveur de développement, ce qui vous permet d'exécuter les deux en parallèle. Vous pouvez modifier ce port avec l'option browser.api.

Depuis Vitest 2.1.5, la CLI n'affiche plus automatiquement l'URL de Vite. Vous pouvez appuyer sur "b" pour afficher l'URL lorsque vous êtes en mode surveillance.

Si vous n'avez jamais utilisé Vite auparavant, assurez-vous d'avoir le plugin de votre framework installé et spécifié dans la configuration. Certains frameworks peuvent nécessiter une configuration supplémentaire pour fonctionner – vérifiez leur documentation liée à Vite pour vous en assurer.

vue

import { defineConfig } from 'vitest/config';
import vue from '@vitejs/plugin-vue';

export default defineConfig({
  plugins: [vue()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium',
    },
  },
});

svelte

import { defineConfig } from 'vitest/config';
import { svelte } from '@sveltejs/vite-plugin-svelte';

export default defineConfig({
  plugins: [svelte()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium',
    },
  },
});

solid

import { defineConfig } from 'vitest/config';
import solidPlugin from 'vite-plugin-solid';

export default defineConfig({
  plugins: [solidPlugin()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium',
    },
  },
});

marko

import { defineConfig } from 'vitest/config';
import marko from '@marko/vite';

export default defineConfig({
  plugins: [marko()],
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium',
    },
  },
});

TIP

React ne nécessite pas de plugin pour fonctionner, mais Preact requiert une configuration supplémentaire pour que les alias fonctionnent.

Si vous avez besoin d'exécuter certains tests en utilisant un runner basé sur Node, vous pouvez définir un fichier workspace avec des configurations séparées pour différentes stratégies de test :

// vitest.workspace.ts
import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  {
    test: {
      // un exemple de convention basée sur les fichiers,
      // que vous n'êtes pas obligé de suivre
      include: [
        'tests/unit/**/*.{test,spec}.ts',
        'tests/**/*.unit.{test,spec}.ts',
      ],
      name: 'unit',
      environment: 'node',
    },
  },
  {
    test: {
      // un exemple de convention basée sur les fichiers,
      // que vous n'êtes pas obligé de suivre
      include: [
        'tests/browser/**/*.{test,spec}.ts',
        'tests/**/*.browser.{test,spec}.ts',
      ],
      name: 'browser',
      browser: {
        enabled: true,
        name: 'chrome',
      },
    },
  },
]);

Configuration du Fournisseur

:::tabs key:provider == Playwright Vous pouvez configurer la manière dont Vitest lance le navigateur et crée le contexte de page via le champ providerOptions :

export default defineConfig({
  test: {
    browser: {
      providerOptions: {
        launch: {
          devtools: true,
        },
        context: {
          geolocation: {
            latitude: 45,
            longitude: -30,
          },
          reducedMotion: 'reduce',
        },
      },
    },
  },
});

Pour bénéficier de suggestions de type, ajoutez @vitest/browser/providers/playwright à compilerOptions.types dans votre fichier tsconfig.json. == WebdriverIO Vous pouvez configurer les options que Vitest doit utiliser lors du démarrage d'un navigateur via le champ providerOptions :

export default defineConfig({
  test: {
    browser: {
      browser: 'chrome',
      providerOptions: {
        region: 'eu',
        capabilities: {
          browserVersion: '27.0',
          platformName: 'Windows 10',
        },
      },
    },
  },
});

Pour bénéficier de suggestions de type, ajoutez @vitest/browser/providers/webdriverio à compilerOptions.types dans votre fichier tsconfig.json. :::

Types d'Options du Navigateur

L'option de navigateur dans Vitest dépend du fournisseur. Vitest échouera si vous passez --browser sans spécifier son nom dans le fichier de configuration. Options disponibles :

• webdriverio prend en charge les navigateurs suivants :
  • firefox
  • chrome
  • edge
  • safari
• playwright prend en charge les navigateurs suivants :
  • firefox
  • webkit
  • chromium

Compatibilité des Navigateurs

Vitest utilise le serveur de développement Vite pour exécuter vos tests. Par conséquent, nous ne prenons en charge que les fonctionnalités spécifiées dans l'option esbuild.target (esnext par défaut).

Par défaut, Vite cible les navigateurs qui prennent en charge les modules ES natifs, l'import dynamique ESM natif et import.meta. De plus, nous utilisons BroadcastChannel pour communiquer entre les iframes :

• Chrome >=87
• Firefox >=78
• Safari >=15.4
• Edge >=88

Exécution des Tests

Lorsque vous spécifiez un nom de navigateur dans l'option browser, Vitest tentera d'exécuter le navigateur spécifié en utilisant preview par défaut, puis y exécutera les tests. Si vous ne souhaitez pas utiliser preview, vous pouvez configurer un fournisseur de navigateur personnalisé en utilisant l'option browser.provider.

Pour spécifier un navigateur via la CLI, utilisez l'option --browser suivie du nom du navigateur, comme suit :

npx vitest --browser=chrome

Vous pouvez également fournir des options de navigateur à la CLI avec la notation pointée :

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

Par défaut, Vitest ouvrira automatiquement l'interface utilisateur du navigateur à des fins de développement. Vos tests s'exécuteront au centre, à l'intérieur d'un iframe. Vous pouvez configurer la zone visible en sélectionnant les dimensions préférées, en appelant page.viewport directement dans le test, ou en définissant des valeurs par défaut dans la configuration.

Mode sans affichage (Headless)

Le mode sans affichage (headless) est une autre option disponible en mode navigateur. En mode headless, le navigateur s'exécute en arrière-plan sans interface utilisateur, ce qui est particulièrement utile pour l'exécution de tests automatisés. L'option headless dans Vitest peut être définie sur une valeur booléenne pour activer ou désactiver ce mode.

Lorsque vous utilisez le mode headless, Vitest n'ouvrira pas automatiquement l'interface utilisateur. Si vous souhaitez continuer à utiliser l'interface utilisateur tout en exécutant les tests en mode headless, vous pouvez installer le paquet @vitest/ui et passer l'option --ui lors de l'exécution de Vitest.

Voici un exemple de configuration activant le mode headless :

export default defineConfig({
  test: {
    browser: {
      provider: 'playwright',
      enabled: true,
      headless: true,
    },
  },
});

Vous pouvez également définir le mode headless en utilisant l'option --browser.headless dans la CLI, comme suit :

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

Dans ce cas, Vitest s'exécutera en mode headless avec le navigateur Chrome.

WARNING

Le mode headless n'est pas disponible par défaut. Vous devez utiliser les fournisseurs playwright ou webdriverio pour activer cette fonctionnalité.

Exemples

Vitest fournit des paquets pour le rendu direct de composants pour plusieurs frameworks populaires :

• vitest-browser-vue pour le rendu des composants Vue
• vitest-browser-svelte pour le rendu des composants Svelte
• vitest-browser-react pour le rendu des composants React

Si votre framework n'est pas représenté, n'hésitez pas à créer votre propre paquet – il s'agit d'une simple enveloppe autour du moteur de rendu du framework et de l'API page.elementLocator. Nous ajouterons un lien vers ce paquet sur cette page. Assurez-vous que son nom commence par vitest-browser-.

En plus du rendu des composants et de la localisation des éléments, vous devrez également effectuer des assertions. Vitest intègre la bibliothèque @testing-library/jest-dom pour fournir une large gamme d'assertions DOM prêtes à l'emploi. En savoir plus sur l'API d'Assertions.

import { expect } from 'vitest';
import { page } from '@vitest/browser/context';
// l'élément est rendu correctement
await expect.element(page.getByText('Hello World')).toBeInTheDocument();

Vitest expose une API de Contexte avec un ensemble restreint d'utilitaires qui pourraient vous être utiles dans les tests. Par exemple, si vous avez besoin d'effectuer une interaction, comme cliquer sur un élément ou saisir du texte dans un champ de saisie, vous pouvez utiliser userEvent de @vitest/browser/context. En savoir plus sur l'API d'Interactivité.

import { page, userEvent } from '@vitest/browser/context';
await userEvent.fill(page.getByLabelText(/username/i), 'Alice');
// ou simplement locator.fill
await page.getByLabelText(/username/i).fill('Alice');

vue

import { render } from 'vitest-browser-vue';
import Component from './Component.vue';

test('properly handles v-model', async () => {
  const screen = render(Component);

  // Vérifie l'état initial.
  await expect
    .element(screen.getByText('Hi, my name is Alice'))
    .toBeInTheDocument();

  // Obtient le nœud DOM de l'entrée en interrogeant l'étiquette associée.
  const usernameInput = screen.getByLabelText(/username/i);

  // Saisissez le nom dans le champ de saisie. Cela valide déjà que le champ
  // est correctement rempli, il n'est pas nécessaire de vérifier la valeur manuellement.
  await usernameInput.fill('Bob');

  await expect
    .element(screen.getByText('Hi, my name is Bob'))
    .toBeInTheDocument();
});

svelte

import { render } from 'vitest-browser-svelte';
import { expect, test } from 'vitest';

import Greeter from './greeter.svelte';

test('greeting appears on click', async () => {
  const screen = render(Greeter, { name: 'World' });

  const button = screen.getByRole('button');
  await button.click();
  const greeting = screen.getByText(/hello world/iu);

  await expect.element(greeting).toBeInTheDocument();
});

react

import { render } from 'vitest-browser-react';
import Fetch from './fetch';

test('loads and displays greeting', async () => {
  // Rend un élément React dans le DOM
  const screen = render(<Fetch url="/greeting" />);

  await screen.getByText('Load Greeting').click();
  // attend avant de lever une erreur s'il ne trouve pas un élément
  const heading = screen.getByRole('heading');

  // affirme que le message d'alerte est correct
  await expect.element(heading).toHaveTextContent('hello there');
  await expect.element(screen.getByRole('button')).toBeDisabled();
});

Vitest ne prend pas en charge tous les frameworks nativement, mais vous pouvez utiliser des outils externes pour exécuter des tests avec ces frameworks. Nous encourageons également la communauté à créer leurs propres enveloppes vitest-browser – si vous en avez une, n'hésitez pas à l'ajouter aux exemples ci-dessus.

Pour les frameworks non pris en charge, nous recommandons d'utiliser les paquets testing-library :

• @testing-library/preact pour le rendu des composants Preact
• @solidjs/testing-library pour le rendu des composants Solid
• @marko/testing-library pour le rendu des composants Marko

WARNING

Testing-library fournit un paquet @testing-library/user-event. Nous ne recommandons pas de l'utiliser directement car il simule des événements au lieu de les déclencher réellement – utilisez plutôt userEvent importé de @vitest/browser/context qui utilise le protocole Chrome DevTools ou Webdriver (selon le fournisseur) en coulisses.

preact

// adapté de l'exemple @testing-library/preact
// https://testing-library.com/docs/preact-testing-library/example

import { h } from 'preact';
import { page } from '@vitest/browser/context';
import { render } from '@testing-library/preact';

import HiddenMessage from '../hidden-message';

test('shows the children when the checkbox is checked', async () => {
  const testMessage = 'Test Message';

  const { baseElement } = render(<HiddenMessage>{testMessage}</HiddenMessage>);

  const screen = page.elementLocator(baseElement);

  // .query() renverra l'élément ou null s'il ne peut pas être trouvé.
  // .element() renverra l'élément ou générera une erreur s'il ne peut pas être trouvé.
  expect(screen.getByText(testMessage).query()).not.toBeInTheDocument();

  // Les requêtes peuvent accepter une regex pour rendre vos sélecteurs plus
  // tolérants aux modifications de contenu.
  await screen.getByLabelText(/show/i).click();

  await expect.element(screen.getByText(testMessage)).toBeInTheDocument();
});

solid

// basé sur l'API @testing-library/solid
// https://testing-library.com/docs/solid-testing-library/api

import { render } from '@testing-library/solid';

it('uses params', async () => {
  const App = () => (
    <>
      <Route
        path="/ids/:id"
        component={() => (
          <p>
            Id:
            {useParams()?.id}
          </p>
        )}
      />
      <Route path="/" component={() => <p>Start</p>} />
    </>
  );
  const { baseElement } = render(() => <App />, { location: 'ids/1234' });
  const screen = page.elementLocator(baseElement);

  await expect.screen(screen.getByText('Id: 1234')).toBeInTheDocument();
});

marko

// basé sur l'API @testing-library/marko
// https://testing-library.com/docs/marko-testing-library/api

import { render, screen } from '@marko/testing-library';
import Greeting from './greeting.marko';

test('renders a message', async () => {
  const { baseElement } = await render(Greeting, { name: 'Marko' });
  const screen = page.elementLocator(baseElement);
  await expect.element(screen.getByText(/Marko/)).toBeInTheDocument();
  await expect.element(container.firstChild).toMatchInlineSnapshot(`
    <h1>Hello, Marko!</h1>
  `);
});

Limitations

Boîtes de dialogue bloquant le thread

Lorsque vous utilisez le mode Navigateur de Vitest, il est important de noter que les boîtes de dialogue bloquant le thread, telles que alert ou confirm, ne peuvent pas être utilisées nativement. Cela est dû au fait qu'elles bloquent la page web, ce qui signifie que Vitest ne peut plus communiquer avec la page, entraînant un blocage de l'exécution.

Dans de telles situations, Vitest fournit des simulations par défaut avec des valeurs de retour prédéfinies pour ces API. Cela garantit que l'exécution ne se bloquera pas si l'utilisateur utilise accidentellement des API web de type pop-up synchrones. Cependant, il est toujours recommandé à l'utilisateur de simuler le comportement de ces API web pour une meilleure expérience de test. En savoir plus dans Mocking.