Mode Navigateur Expérimental
Cette page fournit des informations sur la fonctionnalité expérimentale du mode navigateur dans Vitest, qui vous permet d'exécuter vos tests nativement dans un navigateur, donnant accès aux objets globaux du navigateur comme window et document. Cette fonctionnalité est actuellement en développement et ses API pourraient évoluer à l'avenir.
TIP
Si vous cherchez de la documentation pour expect, vi ou toute API générale comme les projets de test ou le test de type, consultez le guide "Premiers pas".
Installation
Pour faciliter la configuration, vous pouvez utiliser la commande vitest init browser pour installer les dépendances requises et créer la configuration du navigateur.
npx vitest init browseryarn exec vitest init browserpnpx vitest init browserbunx vitest init browserInstallation Manuelle
Vous pouvez également installer les paquets manuellement. Par défaut, le mode navigateur ne nécessite aucun outil E2E supplémentaire pour exécuter les tests localement, car il réutilise votre navigateur existant.
npm install -D vitest @vitest/browseryarn add -D vitest @vitest/browserpnpm add -D vitest @vitest/browserbun add -D vitest @vitest/browserWARNING
Cependant, pour exécuter des tests en CI, vous devez installer l'un des deux outils suivants : playwright ou webdriverio. Nous recommandons également de passer à l'un de ces deux outils pour les tests locaux au lieu d'utiliser le fournisseur preview par défaut, car il simule les événements plutôt que d'utiliser le protocole Chrome DevTools.
Si vous n'utilisez pas déjà l'un de ces outils, nous vous recommandons de commencer par Playwright, car il prend en charge l'exécution parallèle, ce qui accélère vos tests. De plus, Playwright utilise le Protocole Chrome DevTools qui est généralement plus rapide que WebDriver.
::: tabs key:provider == Playwright Playwright est un framework pour le test et l'automatisation web.
npm install -D vitest @vitest/browser playwrightyarn add -D vitest @vitest/browser playwrightpnpm add -D vitest @vitest/browser playwrightbun add -D vitest @vitest/browser playwright== WebdriverIO
WebdriverIO vous permet d'exécuter des tests localement en utilisant le protocole WebDriver.
npm install -D vitest @vitest/browser webdriverioyarn add -D vitest @vitest/browser webdriveriopnpm add -D vitest @vitest/browser webdriveriobun add -D vitest @vitest/browser webdriverioConfiguration
Pour activer le mode navigateur dans votre configuration Vitest, définissez le champ browser.enabled à true dans votre fichier de configuration Vitest. Voici un exemple de configuration utilisant le champ browser :
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
browser: {
provider: 'playwright', // ou 'webdriverio'
enabled: true,
// au moins une instance est nécessaire
instances: [{ browser: 'chromium' }],
},
},
});INFO
Vitest attribue le port 63315 pour éviter les conflits avec le serveur de développement, vous permettant d'exécuter les deux en parallèle. Vous pouvez modifier cela 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" lorsque vous êtes en mode surveillance pour afficher l'URL.
Si vous n'avez jamais utilisé Vite auparavant, assurez-vous que le plugin de votre framework est installé et déclaré dans la configuration. Certains frameworks peuvent nécessiter une configuration supplémentaire pour fonctionner - vérifiez leur documentation relative à Vite pour en être sûr.
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
test: {
browser: {
enabled: true,
provider: 'playwright',
instances: [{ browser: 'chromium' }],
},
},
});import { defineConfig } from 'vitest/config';
import vue from '@vitejs/plugin-vue';
export default defineConfig({
plugins: [vue()],
test: {
browser: {
enabled: true,
provider: 'playwright',
instances: [{ browser: 'chromium' }],
},
},
});import { defineConfig } from 'vitest/config';
import { svelte } from '@sveltejs/vite-plugin-svelte';
export default defineConfig({
plugins: [svelte()],
test: {
browser: {
enabled: true,
provider: 'playwright',
instances: [{ browser: 'chromium' }],
},
},
});import { defineConfig } from 'vitest/config';
import solidPlugin from 'vite-plugin-solid';
export default defineConfig({
plugins: [solidPlugin()],
test: {
browser: {
enabled: true,
provider: 'playwright',
instances: [{ browser: 'chromium' }],
},
},
});import { defineConfig } from 'vitest/config';
import marko from '@marko/vite';
export default defineConfig({
plugins: [marko()],
test: {
browser: {
enabled: true,
provider: 'playwright',
instances: [{ browser: 'chromium' }],
},
},
});Si vous devez exécuter certains tests à l'aide d'un exécuteur basé sur Node, vous pouvez définir une option projects avec des configurations distinctes pour chaque stratégie de test :
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
projects: [
{
test: {
// un exemple de convention basée sur les fichiers,
// vous n'êtes pas obligé de la 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,
// vous n'êtes pas obligé de la suivre
include: [
'tests/browser/**/*.{test,spec}.ts',
'tests/**/*.browser.{test,spec}.ts',
],
name: 'browser',
browser: {
enabled: true,
instances: [{ browser: 'chromium' }],
},
},
},
],
},
});Types d'options de navigateur
L'option browser dans Vitest dépend du fournisseur. Vitest échouera si vous utilisez l'option --browser et ne spécifiez pas son nom dans le fichier de configuration. Options disponibles :
webdriverioprend en charge ces navigateurs :firefoxchromeedgesafari
playwrightprend en charge ces navigateurs :firefoxwebkitchromium
TypeScript
Par défaut, TypeScript ne reconnaît pas les options des fournisseurs et les propriétés additionnelles de expect. Si vous n'utilisez aucun fournisseur, assurez-vous que @vitest/browser/matchers est référencé quelque part dans vos tests, fichier de configuration ou un fichier de configuration pour prendre en compte les définitions expect supplémentaires. Si vous utilisez des fournisseurs personnalisés, assurez-vous d'ajouter @vitest/browser/providers/playwright ou @vitest/browser/providers/webdriverio au même fichier afin que TypeScript puisse prendre en compte les définitions pour les options personnalisées :
/// <reference types="@vitest/browser/matchers" />/// <reference types="@vitest/browser/providers/playwright" />/// <reference types="@vitest/browser/providers/webdriverio" />Alternativement, vous pouvez également les ajouter au champ compilerOptions.types dans votre fichier tsconfig.json. Notez que la spécification de quoi que ce soit dans ce champ désactivera le chargement automatique des packages @types/*.
{
"compilerOptions": {
"types": ["@vitest/browser/matchers"]
}
}{
"compilerOptions": {
"types": ["@vitest/browser/providers/playwright"]
}
}{
"compilerOptions": {
"types": ["@vitest/browser/providers/webdriverio"]
}
}Compatibilité des navigateurs
Vitest utilise le serveur de développement Vite pour exécuter vos tests, nous ne prenons donc 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'importation dynamique ESM native 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 indiqué en utilisant preview par défaut, puis y exécutera les tests. Si vous ne voulez pas utiliser preview, vous pouvez configurer le fournisseur de navigateur personnalisé en utilisant l'option browser.provider.
Pour spécifier un navigateur en utilisant la CLI, utilisez le drapeau --browser suivi du nom du navigateur, comme ceci :
npx vitest --browser=chromiumOu vous pouvez fournir des options de navigateur à la CLI avec la notation par points :
npx vitest --browser.headlessWARNING
Depuis Vitest 3.2, si vous n'avez pas l'option browser dans votre configuration mais que vous spécifiez le drapeau --browser, Vitest échouera car il ne peut pas déduire que la configuration est pour le navigateur et non pour les tests Node.js.
Par défaut, Vitest ouvrira automatiquement l'interface utilisateur du navigateur pour le développement. Vos tests s'exécuteront à l'intérieur d'un iframe dans la partie centrale. Vous pouvez configurer la fenêtre d'affichage en sélectionnant les dimensions préférées, en utilisant page.viewport à l'intérieur du test, ou en définissant des valeurs par défaut dans la configuration.
Mode sans interface (Headless)
Le mode sans interface est une option supplémentaire disponible dans le mode navigateur. En mode sans interface, le navigateur s'exécute en arrière-plan sans interface utilisateur, ce qui le rend utile pour exécuter des tests automatisés. L'option headless dans Vitest peut être définie sur une valeur booléenne pour activer ou désactiver le mode sans interface.
Lorsque vous utilisez le mode sans interface, Vitest n'ouvrira pas automatiquement l'interface utilisateur. Si vous souhaitez continuer à utiliser l'interface utilisateur mais que les tests s'exécutent en mode sans interface, vous pouvez installer le paquet @vitest/ui et passer le drapeau --ui lors de l'exécution de Vitest.
Voici un exemple de configuration activant le mode sans interface :
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
browser: {
provider: 'playwright',
enabled: true,
headless: true,
},
},
});Vous pouvez également définir le mode sans interface en utilisant le drapeau --browser.headless dans la CLI, comme ceci :
npx vitest --browser.headlessDans ce cas, Vitest s'exécutera en mode sans interface en utilisant le navigateur Chrome.
WARNING
Le mode sans interface n'est pas disponible par défaut. Vous devez utiliser les fournisseurs playwright ou webdriverio pour activer cette fonctionnalité.
Exemples
Par défaut, vous n'avez besoin d'aucun paquet externe pour utiliser le mode navigateur :
import { expect, test } from 'vitest';
import { page } from '@vitest/browser/context';
import { render } from './my-render-function.js';
test('properly handles form inputs', async () => {
render(); // afficher les éléments DOM
// Affirme l'état initial.
await expect
.element(page.getByText('Hi, my name is Alice'))
.toBeInTheDocument();
// Récupérer le nœud DOM de l'entrée en recherchant l'étiquette associée.
const usernameInput = page.getByLabelText(/username/i);
// Saisir le nom dans l'entrée. Cela valide déjà que l'entrée
// est correctement remplie, il n'est donc pas nécessaire de vérifier la valeur manuellement.
await usernameInput.fill('Bob');
await expect
.element(page.getByText('Hi, my name is Bob'))
.toBeInTheDocument();
});Cependant, Vitest fournit également des paquets pour rendre des composants pour plusieurs frameworks populaires directement utilisables :
vitest-browser-vuepour rendre les composants vuevitest-browser-sveltepour rendre les composants sveltevitest-browser-reactpour rendre les composants react
Des paquets communautaires sont disponibles pour d'autres frameworks :
vitest-browser-litpour rendre les composants litvitest-browser-preactpour rendre les composants preact
Si votre framework n'est pas représenté, n'hésitez pas à créer votre propre paquet - c'est une simple enveloppe autour du moteur de rendu du framework et de l'API page.elementLocator. Nous ajouterons un lien vers celui-ci sur cette page. Assurez-vous qu'il a un nom commençant par vitest-browser-.
En plus de rendre les composants et de localiser les éléments, vous devrez également faire des assertions. Vitest a créé un fork de la bibliothèque @testing-library/jest-dom pour fournir une large gamme d'assertions DOM prêtes à l'emploi. Pour 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 petit ensemble d'utilitaires qui sont utiles dans les tests. Par exemple, si vous avez besoin d'effectuer une interaction, comme cliquer sur un élément ou taper du texte dans une entrée, 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');import { render } from 'vitest-browser-vue';
import Component from './Component.vue';
test('properly handles v-model', async () => {
const screen = render(Component);
// Affirme l'état initial.
await expect
.element(screen.getByText('Hi, my name is Alice'))
.toBeInTheDocument();
// Récupérer le nœud DOM de l'entrée en recherchant l'étiquette associée.
const usernameInput = screen.getByLabelText(/username/i);
// Saisir le nom dans l'entrée. Cela valide déjà que l'entrée
// est correctement remplie, il n'est donc pas nécessaire de vérifier la valeur manuellement.
await usernameInput.fill('Bob');
await expect
.element(screen.getByText('Hi, my name is Bob'))
.toBeInTheDocument();
});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();
});import { render } from 'vitest-browser-react';
import Fetch from './fetch';
test('loads and displays greeting', async () => {
// Rendre 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 si un élément ne peut pas être trouvé
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();
});import { render } from 'vitest-browser-lit';
import { html } from 'lit';
import './greeter-button';
test('greeting appears on click', async () => {
const screen = render(html`<greeter-button name="World"></greeter-button>`);
const button = screen.getByRole('button');
await button.click();
const greeting = screen.getByText(/hello world/iu);
await expect.element(greeting).toBeInTheDocument();
});import { render } from 'vitest-browser-preact';
import { createElement } from 'preact';
import Greeting from '.Greeting';
test('greeting appears on click', async () => {
const screen = render(<Greeting />);
const button = screen.getByRole('button');
await button.click();
const greeting = screen.getByText(/hello world/iu);
await expect.element(greeting).toBeInTheDocument();
});Vitest ne prend pas en charge tous les frameworks prêts à l'emploi, 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 :
@solidjs/testing-librarypour rendre les composants solid@marko/testing-librarypour rendre les composants marko
Vous pouvez également voir plus d'exemples dans le dépôt browser-examples.
WARNING
testing-library fournit un paquet @testing-library/user-event. Nous ne recommandons pas de l'utiliser directement car il simule les é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.
// 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();
});// 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();
expect(container.firstChild).toMatchInlineSnapshot(`
<h1>Hello, Marko!</h1>
`);
});Limitations
Boîtes de dialogue bloquantes pour le thread
Lorsque vous utilisez Vitest Browser, il est important de noter que les boîtes de dialogue bloquantes pour le thread comme alert ou confirm ne peuvent pas être utilisées nativement. En effet, elles bloquent la page web, ce qui signifie que Vitest ne peut plus communiquer avec la page, entraînant ainsi un blocage de l'exécution.
Dans de telles situations, Vitest fournit des simulacres par défaut avec des valeurs de retour par défaut pour ces API. Cela garantit que si l'utilisateur utilise accidentellement des API web de fenêtre contextuelle synchrones, l'exécution ne se bloquera pas. Cependant, il est toujours recommandé à l'utilisateur de simuler ces API web afin d'assurer un fonctionnement optimal. En savoir plus dans Mocking.