import Test from "/snippets/cli/test.mdx";

Bun est livré avec un runner de tests rapide, intégré et compatible Jest. Les tests sont exécutés avec le runtime Bun et prennent en charge les fonctionnalités suivantes :

• TypeScript et JSX
• Hooks de cycle de vie
• Tests de snapshot
• Tests UI et DOM
• Mode watch avec --watch
• Préchargement de scripts avec --preload

NOTE

Bun vise la compatibilité avec Jest, mais tout n'est pas implémenté. Pour suivre la compatibilité, consultez [ce ticket de suivi](https://github.com/oven-sh/bun/issues/1825).

Exécuter des tests

bun test

Les tests sont écrits en JavaScript ou TypeScript avec une API de type Jest. Consultez Écrire des tests pour la documentation complète.

import { expect, test } from "bun:test";

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

Le runner recherche récursivement dans le répertoire de travail les fichiers qui correspondent aux motifs suivants :

• *.test.{js|jsx|ts|tsx}
• *_test.{js|jsx|ts|tsx}
• *.spec.{js|jsx|ts|tsx}
• *_spec.{js|jsx|ts|tsx}

Vous pouvez filtrer l'ensemble des fichiers de test à exécuter en passant des arguments de position supplémentaires à bun test. Tout fichier de test dont le chemin correspond à l'un des filtres sera exécuté. Généralement, ces filtres seront des noms de fichiers ou de répertoires ; les motifs glob ne sont pas encore pris en charge.

bun test <filtre> <filtre> ...

Pour filtrer par nom de test, utilisez le drapeau -t/--test-name-pattern.

# exécuter tous les tests ou suites de tests avec "addition" dans le nom
bun test --test-name-pattern addition

Pour exécuter un fichier spécifique dans le runner de test, assurez-vous que le chemin commence par ./ ou / pour le distinguer d'un nom de filtre.

bun test ./test/specific-file.test.ts

Le runner de tests exécute tous les tests dans un seul processus. Il charge tous les scripts --preload (voir Cycle de vie pour plus de détails), puis exécute tous les tests. Si un test échoue, le runner de tests se terminera avec un code de sortie non nul.

Intégration CI/CD

bun test prend en charge une variété d'intégrations CI/CD.

GitHub Actions

bun test détecte automatiquement s'il s'exécute dans GitHub Actions et émettra des annotations GitHub Actions directement dans la console.

Aucune configuration n'est nécessaire, autre que l'installation de bun dans le workflow et l'exécution de bun test.

Comment installer bun dans un workflow GitHub Actions

Pour utiliser bun test dans un workflow GitHub Actions, ajoutez l'étape suivante :

jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies # (en supposant que votre projet ait des dépendances)
        run: bun install # Vous pouvez utiliser npm/yarn/pnpm à la place si vous préférez
      - name: Run tests
        run: bun test

À partir de là, vous obtiendrez des annotations GitHub Actions.

Rapports XML JUnit (GitLab, etc.)

Pour utiliser bun test avec un reporter XML JUnit, vous pouvez utiliser --reporter=junit en combinaison avec --reporter-outfile.

bun test --reporter=junit --reporter-outfile=./bun.xml

Cela continuera à sortir vers stdout/stderr comme d'habitude, et écrira également un rapport XML JUnit dans le chemin donné à la toute fin de l'exécution des tests.

XML JUnit est un format populaire pour reporter les résultats de tests dans les pipelines CI/CD.

Timeouts

Utilisez le drapeau --timeout pour spécifier un timeout par test en millisecondes. Si un test dépasse le timeout, il sera marqué comme échoué. La valeur par défaut est 5000.

# la valeur par défaut est 5000
bun test --timeout 20

Exécution concurrente des tests

Par défaut, Bun exécute tous les tests séquentiellement dans chaque fichier de test. Vous pouvez activer l'exécution concurrente pour exécuter des tests async en parallèle, accélérant considérablement les suites de tests avec des tests indépendants.

Drapeau --concurrent

Utilisez le drapeau --concurrent pour exécuter tous les tests de manière concurrente dans leurs fichiers respectifs :

bun test --concurrent

Lorsque ce drapeau est activé, tous les tests s'exécuteront en parallèle sauf s'ils sont explicitement marqués avec test.serial.

Drapeau --max-concurrency

Contrôlez le nombre maximum de tests s'exécutant simultanément avec le drapeau --max-concurrency :

# Limiter à 4 tests concurrents
bun test --concurrent --max-concurrency 4

# Par défaut : 20
bun test --concurrent

Cela aide à prévenir l'épuisement des ressources lors de l'exécution de nombreux tests concurrents. La valeur par défaut est 20.

test.concurrent

Marquez des tests individuels pour s'exécuter de manière concurrente, même lorsque le drapeau --concurrent n'est pas utilisé :

import { test, expect } from "bun:test";

// Ces tests s'exécutent en parallèle les uns avec les autres
test.concurrent("test concurrent 1", async () => {
  await fetch("/api/endpoint1");
  expect(true).toBe(true);
});

test.concurrent("test concurrent 2", async () => {
  await fetch("/api/endpoint2");
  expect(true).toBe(true);
});

// Ce test s'exécute séquentiellement
test("test séquentiel", () => {
  expect(1 + 1).toBe(2);
});

test.serial

Forcez les tests à s'exécuter séquentiellement, même lorsque le drapeau --concurrent est activé :

import { test, expect } from "bun:test";

let sharedState = 0;

// Ces tests doivent s'exécuter dans l'ordre
test.serial("premier test serial", () => {
  sharedState = 1;
  expect(sharedState).toBe(1);
});

test.serial("deuxième test serial", () => {
  // Dépend du test précédent
  expect(sharedState).toBe(1);
  sharedState = 2;
});

// Ce test peut s'exécuter de manière concurrente si --concurrent est activé
test("test indépendant", () => {
  expect(true).toBe(true);
});

// Chaînage de qualificateurs de test
test.failing.each([1, 2, 3])("qualificateurs chaînés %d", input => {
  expect(input).toBe(0); // Ce test est censé échouer pour chaque input
});

Ré-exécuter des tests

Utilisez le drapeau --rerun-each pour exécuter chaque test plusieurs fois. Ceci est utile pour détecter les tests instables ou les échecs non déterministes.

bun test --rerun-each 100

Randomiser l'ordre d'exécution des tests

Utilisez le drapeau --randomize pour exécuter les tests dans un ordre aléatoire. Cela aide à détecter les tests qui dépendent d'un état partagé ou de l'ordre d'exécution.

bun test --randomize

Lors de l'utilisation de --randomize, la seed utilisée pour la randomisation sera affichée dans le résumé des tests :

bun test --randomize

# ... sortie des tests ...
 --seed=12345
 2 pass
 8 fail
Ran 10 tests across 2 files. [50.00ms]

Ordre aléatoire reproductible avec --seed

Utilisez le drapeau --seed pour spécifier une seed pour la randomisation. Cela vous permet de reproduire le même ordre de tests lors du débogage des échecs dépendant de l'ordre.

# Reproduire une exécution randomisée précédente
bun test --seed 123456

Le drapeau --seed implique --randomize, vous n'avez donc pas besoin de spécifier les deux. Utiliser la même valeur de seed produira toujours le même ordre d'exécution des tests, facilitant le débogage des échecs intermittents causés par les interdépendances des tests.

Abandonner avec --bail

Utilisez le drapeau --bail pour arrêter prématurément l'exécution des tests après un nombre prédéterminé d'échecs de tests. Par défaut, Bun exécutera tous les tests et signalera tous les échecs, mais parfois dans les environnements CI, il est préférable de terminer plus tôt pour réduire l'utilisation du CPU.

# abandonner après 1 échec
bun test --bail

# abandonner après 10 échecs
bun test --bail=10

Mode watch

Semblable à bun run, vous pouvez passer le drapeau --watch à bun test pour surveiller les changements et ré-exécuter les tests.

bun test --watch

Hooks de cycle de vie

Bun prend en charge les hooks de cycle de vie suivants :

Hook	Description
beforeAll	S'exécute une fois avant tous les tests.
beforeEach	S'exécute avant chaque test.
afterEach	S'exécute après chaque test.
afterAll	S'exécute une fois après tous les tests.

Ces hooks peuvent être définis dans les fichiers de test, ou dans un fichier séparé qui est préchargé avec le drapeau --preload.

bun test --preload ./setup.ts

Consultez Test > Cycle de vie pour la documentation complète.

Mocks

Créez des fonctions mock avec la fonction mock.

import { test, expect, mock } from "bun:test";
const random = mock(() => Math.random());

test("random", () => {
  const val = random();
  expect(val).toBeGreaterThan(0);
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

Alternativement, vous pouvez utiliser jest.fn(), cela se comporte de manière identique.

import { test, expect, mock } from "bun:test"; 
import { test, expect, jest } from "bun:test"; 

const random = mock(() => Math.random()); 
const random = jest.fn(() => Math.random()); 

Consultez Test > Mocks pour la documentation complète.

Tests de snapshot

Les snapshots sont pris en charge par bun test.

// exemple d'utilisation de toMatchSnapshot
import { test, expect } from "bun:test";

test("snapshot", () => {
  expect({ a: 1 }).toMatchSnapshot();
});

Pour mettre à jour les snapshots, utilisez le drapeau --update-snapshots.

bun test --update-snapshots

Consultez Test > Snapshots pour la documentation complète.

Tests UI et DOM

Bun est compatible avec les bibliothèques de test UI populaires :

• HappyDOM
• DOM Testing Library
• React Testing Library

Consultez Test > Tests DOM pour la documentation complète.

Performance

Le runner de tests de Bun est rapide.

Intégration avec les agents AI

Lors de l'utilisation du runner de tests de Bun avec des assistants de codage AI, vous pouvez activer une sortie plus silencieuse pour améliorer la lisibilité et réduire le bruit de contexte. Cette fonctionnalité minimise la verbosité de la sortie des tests tout en préservant les informations d'échec essentielles.

Variables d'environnement

Définissez l'une des variables d'environnement suivantes pour activer la sortie silencieuse :

• CLAUDECODE=1 - Pour Claude Code
• REPL_ID=1 - Pour Replit
• AGENT=1 - Drapeau générique pour agent AI

Comportement

Lorsqu'un environnement d'agent AI est détecté :

• Seuls les échecs de tests sont affichés en détail
• Les indicateurs de tests réussis, ignorés et todo sont masqués
• Les statistiques de résumé restent intactes

# Exemple : Activer la sortie silencieuse pour Claude Code
CLAUDECODE=1 bun test

# Affiche toujours les échecs et le résumé, mais masque la sortie verbose des tests réussis

Cette fonctionnalité est particulièrement utile dans les flux de travail de développement assistés par AI où une verbosité de sortie réduite améliore l'efficacité du contexte tout en maintenant la visibilité sur les échecs de tests.