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

Bun includes a fast, built-in, Jest-compatible test runner. I test vengono eseguiti con il runtime Bun, e supportano le seguenti funzionalita.

• TypeScript e JSX
• Hook del ciclo di vita
• Test snapshot
• Test UI e DOM
• Modalita watch con --watch
• Preloading degli script con --preload

NOTE

Bun mira alla compatibilita con Jest, ma non tutto e implementato. Per tracciare la compatibilita, vedi [questo issue di tracking](https://github.com/oven-sh/bun/issues/1825).

Esegui i test

bun test

I test sono scritti in JavaScript o TypeScript con un'API simile a Jest. Consulta Scrivere test per la documentazione completa.

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

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

Il runner cerca ricorsivamente nella directory di lavoro i file che corrispondono ai seguenti pattern:

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

Puoi filtrare l'insieme di file di test da eseguire passando argomenti posizionali aggiuntivi a bun test. Qualsiasi file di test con un percorso che corrisponde a uno dei filtri sara eseguito. Comunemente, questi filtri saranno nomi di file o directory; i pattern glob non sono ancora supportati.

bun test <filtro> <filtro> ...

Per filtrare per nome del test, usa il flag -t/--test-name-pattern.

# esegui tutti i test o suite di test con "addition" nel nome
bun test --test-name-pattern addition

Per eseguire un file specifico nel test runner, assicurati che il percorso inizi con ./ o / per distinguerlo da un nome di filtro.

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

Il test runner esegue tutti i test in un singolo processo. Carica tutti gli script --preload (vedi Ciclo di vita per i dettagli), poi esegue tutti i test. Se un test fallisce, il test runner uscira con un codice di uscita non-zero.

Integrazione CI/CD

bun test supporta una varieta di integrazioni CI/CD.

GitHub Actions

bun test rileva automaticamente se sta funzionando all'interno di GitHub Actions e emettera annotazioni di GitHub Actions direttamente sulla console.

Non e necessaria alcuna configurazione, oltre a installare bun nel workflow ed eseguire bun test.

Come installare bun in un workflow GitHub Actions

Per usare bun test in un workflow GitHub Actions, aggiungi il seguente step:

.github/workflows/test.yml

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 # (presupponendo che il tuo progetto abbia dipendenze)
        run: bun install # Puoi usare npm/yarn/pnpm invece se preferisci
      - name: Run tests
        run: bun test

Da li, riceverai le annotazioni di GitHub Actions.

Report XML JUnit (GitLab, ecc.)

Per usare bun test con un reporter XML JUnit, puoi usare --reporter=junit in combinazione con --reporter-outfile.

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

Questo continuera a emettere output su stdout/stderr come al solito, e scrivera anche un report XML JUnit nel percorso dato alla fine dell'esecuzione dei test.

JUnit XML e un formato popolare per il report dei risultati dei test nelle pipeline CI/CD.

Timeout

Usa il flag --timeout per specificare un timeout per test in millisecondi. Se un test va in timeout, sara marcato come fallito. Il valore predefinito e 5000.

# il valore predefinito e 5000
bun test --timeout 20

Esecuzione dei test concorrente

Di default, Bun esegue tutti i test sequenzialmente all'interno di ogni file di test. Puoi abilitare l'esecuzione concorrente per eseguire i test asincroni in parallelo, accelerando significativamente le suite di test con test indipendenti.

Flag --concurrent

Usa il flag --concurrent per eseguire tutti i test in modo concorrente all'interno dei rispettivi file:

bun test --concurrent

Quando questo flag e abilitato, tutti i test verranno eseguiti in parallelo a meno che non siano esplicitamente marcati con test.serial.

Flag --max-concurrency

Controlla il numero massimo di test in esecuzione simultanea con il flag --max-concurrency:

# Limita a 4 test concorrenti
bun test --concurrent --max-concurrency 4

# Default: 20
bun test --concurrent

Questo aiuta a prevenire l'esaurimento delle risorse quando si eseguono molti test concorrenti. Il valore predefinito e 20.

test.concurrent

Marca test individuali per essere eseguiti in modo concorrente, anche quando il flag --concurrent non e usato:

math.test.ts

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

// Questi test vengono eseguiti in parallelo tra loro
test.concurrent("test concorrente 1", async () => {
  await fetch("/api/endpoint1");
  expect(true).toBe(true);
});

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

// Questo test viene eseguito sequenzialmente
test("test sequenziale", () => {
  expect(1 + 1).toBe(2);
});

test.serial

Forza i test a essere eseguiti sequenzialmente, anche quando il flag --concurrent e abilitato:

math.test.ts

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

let sharedState = 0;

// Questi test devono essere eseguiti in ordine
test.serial("primo test seriale", () => {
  sharedState = 1;
  expect(sharedState).toBe(1);
});

test.serial("secondo test seriale", () => {
  // Dipende dal test precedente
  expect(sharedState).toBe(1);
  sharedState = 2;
});

// Questo test puo essere eseguito in modo concorrente se --concurrent e abilitato
test("test indipendente", () => {
  expect(true).toBe(true);
});

// Concatenazione di qualificatori del test
test.failing.each([1, 2, 3])("qualificatori concatenati %d", input => {
  expect(input).toBe(0); // Questo test e previsto fallire per ogni input
});

Riesegui i test

Usa il flag --rerun-each per eseguire ogni test piu volte. Questo e utile per rilevare test flaky o fallimenti non deterministici.

bun test --rerun-each 100

Randomizzare l'ordine di esecuzione dei test

Usa il flag --randomize per eseguire i test in ordine casuale. Questo aiuta a rilevare test che dipendono da stato condiviso o dall'ordine di esecuzione.

bun test --randomize

Quando usi --randomize, il seed usato per la randomizzazione sara visualizzato nel sommario dei test:

bun test --randomize

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

Ordine casuale riproducibile con --seed

Usa il flag --seed per specificare un seed per la randomizzazione. Questo ti permette di riprodurre lo stesso ordine dei test durante il debug di fallimenti dipendenti dall'ordine.

# Riproduci una run randomizzata precedente
bun test --seed 123456

Il flag --seed implica --randomize, quindi non devi specificare entrambi. Usare lo stesso valore del seed produrra sempre lo stesso ordine di esecuzione dei test, facilitando il debug di fallimenti intermittenti causati da interazioni tra test.

Uscire prima con --bail

Usa il flag --bail per abortire l'esecuzione dei test presto dopo un numero predeterminato di fallimenti dei test. Di default Bun eseguira tutti i test e riportera tutti i fallimenti, ma a volte negli ambienti CI e preferibile terminare prima per ridurre l'utilizzo della CPU.

# bail dopo 1 fallimento
bun test --bail

# bail dopo 10 fallimenti
bun test --bail=10

Modalita watch

Simile a bun run, puoi passare il flag --watch a bun test per.watchare i cambiamenti e rieseguire i test.

bun test --watch

Hook del ciclo di vita

Bun supporta i seguenti hook del ciclo di vita:

Hook	Descrizione
beforeAll	Esegue una volta prima di tutti i test.
beforeEach	Esegue prima di ogni test.
afterEach	Esegue dopo ogni test.
afterAll	Esegue una volta dopo tutti i test.

Questi hook possono essere definiti all'interno dei file di test, o in un file separato che viene preloaded con il flag --preload.

bun test --preload ./setup.ts```

Vedi [Test > Ciclo di vita](/it/test/lifecycle) per la documentazione completa.

## Mock

Crea funzioni mock con la funzione `mock`.

```ts [math.test.ts]
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);
});

In alternativa, puoi usare jest.fn(), si comporta in modo identico.

math.test.ts

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()); 

Vedi Test > Mock per la documentazione completa.

Test snapshot

Gli snapshot sono supportati da bun test.

math.test.ts

// esempio di utilizzo di toMatchSnapshot
import { test, expect } from "bun:test";

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

Per aggiornare gli snapshot, usa il flag --update-snapshots.

bun test --update-snapshots

Vedi Test > Snapshots per la documentazione completa.

Test UI e DOM

Bun e compatibile con le librerie di test UI piu diffuse:

• HappyDOM
• DOM Testing Library
• React Testing Library

Vedi Test > Test DOM per la documentazione completa.

Performance

Il test runner di Bun e veloce.

Integrazione con Agent AI

Quando usi il test runner di Bun con assistenti di codifica AI, puoi abilitare un output piu silenzioso per migliorare la leggibilita e ridurre il rumore del contesto. Questa funzionalita minimizza la verbosita dell'output dei test preservando le informazioni essenziali sui fallimenti.

Variabili di Ambiente

Imposta una qualsiasi delle seguenti variabili di ambiente per abilitare l'output AI-friendly:

• CLAUDECODE=1 - Per Claude Code
• REPL_ID=1 - Per Replit
• AGENT=1 - Flag generico per agent AI

Comportamento

Quando viene rilevato un ambiente AI agent:

• Solo i fallimenti dei test vengono visualizzati in dettaglio
• Gli indicatori di test passati, saltati e todo sono nascosti
• Le statistiche di riepilogo rimangono intatte

# Esempio: Abilita output silenzioso per Claude Code
CLAUDECODE=1 bun test

# Mostra ancora i fallimenti e il riepilogo, ma nasconde l'output dettagliato dei test passati

Questa funzionalita e particolarmente utile nei workflow di sviluppo assistiti da AI dove la riduzione della verbosita dell'output migliora l'efficienza del contesto mantenendo la visibilita sui fallimenti dei test.

---