Fonctionnalités

• Configuration, transformateurs, résolveurs et plugins de Vite
• Utilisation de la même configuration que votre application pour l'exécution des tests
• Mode de surveillance intelligent et instantané, similaire au HMR pour les tests
• Test de composants pour Vue, React, Svelte, Lit, Marko et autres
• Prise en charge native de TypeScript et JSX
• Priorité à l'ESM, top level await
• Multi-threading des workers via Tinypool
• Prise en charge du benchmarking avec Tinybench
• Filtrage, délais d'attente et exécution concurrente pour les suites et les tests
• Prise en charge des projets
• Snapshots compatibles avec Jest
• Chai intégré pour les assertions + API compatibles Jest expect
• Tinyspy intégré pour la simulation (mocking)
• happy-dom ou jsdom pour la simulation du DOM
• Mode navigateur pour exécuter les tests de composants dans le navigateur
• Couverture de code via v8 ou istanbul
• Tests en source de style Rust
• Test de type via expect-type
• Prise en charge du sharding
• Signalement des erreurs non interceptées

Apprenez à écrire votre premier test en vidéo

Configuration partagée pour les tests, le développement et la compilation

Vitest utilise la configuration, les transformateurs, les résolveurs et les plugins de Vite. Vous pouvez ainsi utiliser la même configuration que votre application pour exécuter les tests.

En savoir plus sur la Configuration de Vitest.

Mode de surveillance

$ vitest

Lorsque vous modifiez votre code source ou vos fichiers de test, Vitest analyse intelligemment le graphe des modules et ne réexécute que les tests pertinents, à l'instar du fonctionnement du HMR dans Vite !

Par défaut, vitest démarre en mode de surveillance dans l'environnement de développement et en mode d'exécution dans l'environnement CI (lorsque process.env.CI est défini). Vous pouvez utiliser vitest watch ou vitest run pour spécifier explicitement le mode souhaité.

Démarrez Vitest avec l'option --standalone pour le maintenir en arrière-plan. Il n'exécutera aucun test tant qu'ils ne sont pas modifiés. Vitest n'exécutera pas les tests si le code source est modifié tant que le test qui importe la source n'a pas été exécuté.

Idiomes web courants prêts à l'emploi

Prise en charge native des modules ES, TypeScript, JSX et PostCSS.

Threads

Par défaut, Vitest exécute les fichiers de test dans plusieurs processus en utilisant node:child_process via Tinypool (un fork léger de Piscina), permettant aux tests de s'exécuter simultanément. Si vous souhaitez accélérer davantage votre suite de tests, envisagez d'activer --pool=threads pour exécuter les tests en utilisant node:worker_threads (attention, certains packages pourraient ne pas fonctionner avec cette configuration).

Pour exécuter les tests dans un seul thread ou processus, consultez poolOptions.

Vitest isole également l'environnement de chaque fichier de test afin que les modifications d'environnement dans un fichier n'affectent pas les autres. L'isolation peut être désactivée en passant --no-isolate à la CLI (en sacrifiant la précision au profit des performances d'exécution).

Filtrage des tests

Vitest offre de nombreuses façons d'affiner la sélection des tests à exécuter afin d'accélérer les tests et de vous permettre de vous concentrer sur le développement.

En savoir plus sur le Filtrage des tests.

Exécution de tests concurrents

Utilisez .concurrent sur les tests pour les démarrer en parallèle.

import { describe, it } from 'vitest';

// Les deux tests marqués avec concurrent seront démarrés en parallèle
describe('suite', () => {
  it('serial test', async () => {
    /* ... */
  });
  it.concurrent('concurrent test 1', async ({ expect }) => {
    /* ... */
  });
  it.concurrent('concurrent test 2', async ({ expect }) => {
    /* ... */
  });
});

Si vous utilisez .concurrent sur une suite, tous les tests de cette suite seront démarrés en parallèle.

import { describe, it } from 'vitest';

// Tous les tests de cette suite seront démarrés en parallèle
describe.concurrent('suite', () => {
  it('concurrent test 1', async ({ expect }) => {
    /* ... */
  });
  it('concurrent test 2', async ({ expect }) => {
    /* ... */
  });
  it.concurrent('concurrent test 3', async ({ expect }) => {
    /* ... */
  });
});

Vous pouvez également utiliser .skip, .only et .todo avec des suites et des tests concurrents. Pour en savoir plus, consultez la Référence de l'API.

WARNING

Lors de l'exécution de tests concurrents, les Snapshots et les Assertions doivent utiliser expect du Contexte de test local pour s'assurer que le test correct est identifié.

Snapshot

Prise en charge des snapshots compatibles avec Jest.

import { expect, it } from 'vitest';

it('renders correctly', () => {
  const result = render();
  expect(result).toMatchSnapshot();
});

En savoir plus sur Snapshot.

Compatibilité Chai et Jest expect

Chai est intégré pour effectuer des assertions avec les API compatibles Jest expect.

Notez que si vous utilisez des bibliothèques tierces qui ajoutent des comparateurs, définir test.globals à true offrira une meilleure compatibilité.

Mocking

Tinyspy est intégré pour la simulation (mocking) avec des API compatibles jest sur l'objet vi.

import { expect, vi } from 'vitest';

const fn = vi.fn();

fn('hello', 1);

expect(vi.isMockFunction(fn)).toBe(true);
expect(fn.mock.calls[0]).toEqual(['hello', 1]);

fn.mockImplementation((arg: string) => arg);

fn('world', 2);

expect(fn.mock.results[1].value).toBe('world');

Vitest prend en charge soit happy-dom soit jsdom pour la simulation du DOM et des API du navigateur. Ils ne sont pas fournis avec Vitest, vous devrez les installer séparément :

happy-dom

$ npm i -D happy-dom

jsdom

$ npm i -D jsdom

Après cela, modifiez l'option environment dans votre fichier de configuration :

import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'happy-dom', // ou 'jsdom', 'node'
  },
});

En savoir plus sur la simulation.

Couverture

Vitest prend en charge la couverture de code native via v8 et la couverture de code instrumentée via istanbul.

{
  "scripts": {
    "test": "vitest",
    "coverage": "vitest run --coverage"
  }
}

En savoir plus sur la couverture.

Tests en source

Vitest offre également un moyen d'exécuter des tests au sein de votre code source, conjointement avec l'implémentation, similaire aux tests de modules de Rust.

Cela permet aux tests de partager la même fermeture que les implémentations et de tester les états privés sans les exporter. En même temps, cela rapproche le retour d'information pour le développement.

// l'implémentation
export function add(...args: number[]): number {
  return args.reduce((a, b) => a + b, 0);
}

// suites de tests en source
if (import.meta.vitest) {
  const { it, expect } = import.meta.vitest;
  it('add', () => {
    expect(add()).toBe(0);
    expect(add(1)).toBe(1);
    expect(add(1, 2, 3)).toBe(6);
  });
}

En savoir plus sur les tests en source.

Benchmarking Expérimental

Vous pouvez exécuter des tests de performance avec la fonction bench via Tinybench pour comparer les performances.

import { bench, describe } from 'vitest';

describe('sort', () => {
  bench('normal', () => {
    const x = [1, 5, 4, 2, 3];
    x.sort((a, b) => {
      return a - b;
    });
  });

  bench('reverse', () => {
    const x = [1, 5, 4, 2, 3];
    x.reverse().sort((a, b) => {
      return a - b;
    });
  });
});

Test de type Expérimental

Vous pouvez écrire des tests pour détecter les régressions de type. Vitest est livré avec le package expect-type pour vous offrir une API similaire et facile à utiliser.

import { assertType, expectTypeOf, test } from 'vitest';
import { mount } from './mount.js';

test('my types work properly', () => {
  expectTypeOf(mount).toBeFunction();
  expectTypeOf(mount).parameter(0).toMatchTypeOf<{ name: string }>();

  // @ts-expect-error name is a string
  assertType(mount({ name: 42 }));
});

Sharding

Exécutez des tests sur plusieurs machines en utilisant les options --shard et --reporter=blob. Tous les résultats des tests et de la couverture peuvent être fusionnés à la fin de votre pipeline CI en utilisant la commande --merge-reports :

vitest --shard=1/2 --reporter=blob --coverage
vitest --shard=2/2 --reporter=blob --coverage
vitest --merge-reports --reporter=junit --coverage

Voir Amélioration des performances | Sharding pour plus de détails.

Variables d'environnement

Vitest charge exclusivement les variables d'environnement préfixées par VITE_ à partir des fichiers .env pour garantir la compatibilité avec les tests front-end, en adhérant à la convention établie de Vite. Pour charger néanmoins toutes les variables d'environnement à partir des fichiers .env, vous pouvez utiliser la méthode loadEnv importée de vite :

import { loadEnv } from 'vite';
import { defineConfig } from 'vitest/config';

export default defineConfig(({ mode }) => ({
  test: {
    // le mode définit quel fichier ".env.{mode}" choisir s'il existe
    env: loadEnv(mode, process.cwd(), ''),
  },
}));

Erreurs non gérées

Par défaut, Vitest intercepte et signale toutes les promesses rejetées non gérées, les exceptions non interceptées (dans Node.js) et les événements error (dans le navigateur).

Vous pouvez désactiver ce comportement en les interceptant manuellement. Vitest suppose que vous gérez le rappel et ne signalera pas l'erreur.

setup.node.js

// dans Node.js
process.on('unhandledRejection', () => {
  // votre propre gestionnaire
});

process.on('uncaughtException', () => {
  // votre propre gestionnaire
});

setup.browser.js

// dans le navigateur
window.addEventListener('error', () => {
  // votre propre gestionnaire
});

window.addEventListener('unhandledrejection', () => {
  // votre propre gestionnaire
});

Alternativement, vous pouvez également ignorer les erreurs signalées avec l'option dangerouslyIgnoreUnhandledErrors. Vitest les signalera toujours, mais elles n'affecteront pas le résultat du test (le code de sortie ne sera pas modifié).

Si vous avez besoin de tester qu'une erreur n'a pas été interceptée, vous pouvez créer un test qui ressemble à ceci :

test('my function throws uncaught error', async ({ onTestFinished }) => {
  onTestFinished(() => {
    // si l'événement n'a pas été déclenché pendant le test,
    // assurez-vous de le supprimer avant le début du test suivant
    process.removeAllListeners('unhandledrejection');
  });

  return new Promise((resolve, reject) => {
    process.once('unhandledrejection', error => {
      try {
        expect(error.message).toBe('my error');
        resolve();
      } catch (error) {
        reject(error);
      }
    });

    callMyFunctionThatRejectsError();
  });
});