bun test e profondamente integrato con il runtime di Bun. Questo e parte di cio che rende bun test veloce e semplice da usare.

Variabili di Ambiente

NODE_ENV

bun test imposta automaticamente $NODE_ENV a "test" a meno che non sia gia impostato nell'ambiente o tramite file .env. Questo e un comportamento standard per la maggior parte dei test runner e aiuta a garantire un comportamento coerente dei test.

test.ts

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

test("NODE_ENV e impostato a test", () => {
  expect(process.env.NODE_ENV).toBe("test");
});

Puoi sovrascriverlo impostando esplicitamente NODE_ENV:

NODE_ENV=development bun test

TZ (Fuso Orario)

Di default, tutte le esecuzioni di bun test usano UTC (Etc/UTC) come fuso orario a meno che non venga sovrascritto dalla variabile di ambiente TZ. Questo garantisce un comportamento coerente di date e orari tra diversi ambienti di sviluppo.

test.ts

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

test("il fuso orario e UTC di default", () => {
  const date = new Date();
  expect(date.getTimezoneOffset()).toBe(0);
});

Per testare con un fuso orario specifico:

TZ=America/New_York bun test

Timeout dei Test

Ogni test ha un timeout predefinito di 5000ms (5 secondi) se non viene esplicitamente sovrascritto. I test che superano questo timeout falliranno.

Timeout Globale

Cambia il timeout globalmente con il flag --timeout:

bun test --timeout 10000  # 10 secondi

Timeout per Test

Imposta il timeout per test come terzo parametro alla funzione di test:

test.ts

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

test("test veloce", () => {
  expect(1 + 1).toBe(2);
}, 1000); // 1 secondo di timeout

test("test lento", async () => {
  await new Promise(resolve => setTimeout(resolve, 8000));
}, 10000); // 10 secondi di timeout

Timeout Infinito

Usa 0 o Infinity per disabilitare il timeout:

test.ts

test("test senza timeout", async () => {
  // Questo test puo essere eseguito indefinitamente
  await someVeryLongOperation();
}, 0);

Gestione degli Errori

Errori Non Gestiti

bun test traccia i rifiuti di promise non gestiti e gli errori che si verificano tra i test. Se si verificano tali errori, il codice di uscita finale sara non-zero (specificamente, il conteggio di tali errori), anche se tutti i test passano.

Questo aiuta a catturare errori nel codice asincrono che altrimenti potrebbero passare inosservati:

test.ts

import { test } from "bun:test";

test("test 1", () => {
  // Questo test passa
  expect(true).toBe(true);
});

// Questo errore avviene fuori da qualsiasi test
setTimeout(() => {
  throw new Error("Errore non gestito");
}, 0);

test("test 2", () => {
  // Anche questo test passa
  expect(true).toBe(true);
});

// L'esecuzione dei test fallira comunque con un codice di uscita non-zero
// a causa dell'errore non gestito

Rifiuti di Promise

Anche i rifiuti di promise non gestiti vengono catturati:

test.ts

import { test } from "bun:test";

test("test che passa", () => {
  expect(1).toBe(1);
});

// Questo causera il fallimento dell'esecuzione dei test
Promise.reject(new Error("Rifiuto non gestito"));

Gestione Personalizzata degli Errori

Puoi impostare gestori di errori personalizzati nel tuo setup di test:

test-setup.ts

process.on("uncaughtException", error => {
  console.error("Eccezione non catturata:", error);
  process.exit(1);
});

process.on("unhandledRejection", (reason, promise) => {
  console.error("Rifiuto non gestito a:", promise, "motivo:", reason);
  process.exit(1);
});

Integrazione con i Flag CLI

Diversi flag CLI di Bun possono essere usati con bun test per modificarne il comportamento:

Utilizzo della Memoria

# Riduce l'utilizzo della memoria per la VM del test runner
bun test --smol

Debugging

# Collega il debugger al processo del test runner
bun test --inspect
bun test --inspect-brk

Caricamento dei Moduli

# Esegue script prima dei file di test (utile per setup globali/mock)
bun test --preload ./setup.ts

# Imposta costanti a tempo di compilazione
bun test --define "process.env.API_URL='http://localhost:3000'"

# Configura loader personalizzati
bun test --loader .special:special-loader

# Usa un tsconfig diverso
bun test --tsconfig-override ./test-tsconfig.json

# Imposta le condizioni di package.json per la risoluzione dei moduli
bun test --conditions development

# Carica variabili di ambiente per i test
bun test --env-file .env.test

Flag Relativi all'Installazione

# Influenza qualsiasi richiesta di rete o auto-install durante l'esecuzione dei test
bun test --prefer-offline
bun test --frozen-lockfile

Watch Mode e Hot Reloading

Modalita Watch

Quando esegui bun test con il flag --watch, il test runner guardera i cambiamenti dei file e rieseguira i test interessati.

bun test --watch

Il test runner e intelligente su quali test rieseguire:

math.test.ts

import { add } from "./math.js";
import { test, expect } from "bun:test";

test("addizione", () => {
  expect(add(2, 3)).toBe(5);
});

Se modifichi math.js, solo math.test.ts sara rieseguito, non tutti i test.

Hot Reloading

Il flag --hot fornisce funzionalita simile ma e piu aggressivo nel tentare di preservare lo stato tra le esecuzioni:

bun test --hot

Per la maggior parte degli scenari di test, --watch e l'opzione raccomandata in quanto fornisce un migliore isolamento tra le esecuzioni dei test.

Variabili Globali

Le seguenti variabili globali sono automaticamente disponibili nei file di test senza importazione (anche se possono essere importate da bun:test se preferito):

test.ts

// Tutte queste sono disponibili globalmente
test("funzione di test globale", () => {
  expect(true).toBe(true);
});

describe("describe globale", () => {
  beforeAll(() => {
    // beforeAll globale
  });

  it("funzione it globale", () => {
    // it e un alias per test
  });
});

// Compatibilita con Jest
jest.fn();

// Compatibilita con Vitest
vi.fn();

Puoi anche importarle esplicitamente se preferisci:

test.ts

import { test, it, describe, expect, beforeAll, beforeEach, afterAll, afterEach, jest, vi } from "bun:test";

Integrazione con il Processo

Codici di Uscita

bun test usa codici di uscita standard:

• 0: Tutti i test passano, nessun errore non gestito
• 1: Si sono verificati fallimenti dei test
• >1: Numero di errori non gestiti (anche se i test passano)

Gestione dei Segnali

Il test runner gestisce correttamente i segnali comuni:

# Ferma gracefully l'esecuzione dei test
kill -SIGTERM <test-process-pid>

# Ferma immediatamente l'esecuzione dei test
kill -SIGKILL <test-process-pid>

Rilevamento dell'Ambiente

Bun rileva automaticamente alcuni ambienti e modifica il comportamento:

test.ts

// Rilevamento GitHub Actions
if (process.env.GITHUB_ACTIONS) {
  // Bun emette automaticamente annotazioni GitHub Actions
}

// Rilevamento CI
if (process.env.CI) {
  // Alcuni comportamenti possono essere modificati per gli ambienti CI
}

Considerazioni sulle Performance

Singolo Processo

Il test runner esegue tutti i test in un singolo processo per default. Questo fornisce:

• Avvio piu veloce - Non c'e bisogno di spawnare piu processi
• Memoria condivisa - Utilizzo efficiente delle risorse
• Debugging semplice - Tutti i test in un processo

Pero, questo significa:

• I test condividono stato globale (usa gli hook del ciclo di vita per pulire)
• Un crash di un test puo influenzare gli altri
• Nessuna vera parallelizzazione dei singoli test

Gestione della Memoria

# Monitora l'utilizzo della memoria
bun test --smol  # Riduce l'impronta di memoria

# Per grandi suite di test, considera di dividere i file
bun test src/unit/
bun test src/integration/

Isolamento dei Test

Poiche i test vengono eseguiti nello stesso processo, assicurati una pulizia adeguata:

test.ts

import { afterEach } from "bun:test";

afterEach(() => {
  // Pulisci lo stato globale
  global.myGlobalVar = undefined;
  delete process.env.TEST_VAR;

  // Resetta i moduli se necessario
  jest.resetModules();
});