Configura bun test tramite il file bunfig.toml e le opzioni da riga di comando. Questa pagina documenta le opzioni di configurazione disponibili per bun test.

File di Configurazione

Puoi configurare il comportamento di bun test aggiungendo una sezione [test] al tuo file bunfig.toml:

bunfig.toml

[test]
# Le opzioni vanno qui

Scoperta dei Test

root

L'opzione root specifica una directory root per la scoperta dei test, sovrascrivendo il comportamento predefinito di scansione dalla root del progetto.

bunfig.toml

[test]
root = "src"  # Scansiona solo i test nella directory src

Questo e utile quando vuoi:

• Limitare la scoperta dei test a directory specifiche
• Escludere alcune parti del tuo progetto dalla scansione dei test
• Organizzare i test in una struttura di sottodirectory specifica

Esempi

bunfig.toml

[test]
# Esegui solo i test nella directory src
root = "src"

# Esegui i test in una directory di test specifica
root = "tests"

# Esegui i test in piu directory specifiche (non attualmente supportato - usa i pattern invece)
# root = ["src", "lib"]  # Questa sintassi non e supportata

Script di Preload

Carica gli script prima di eseguire i test usando l'opzione preload:

bunfig.toml

[test]
preload = ["./test-setup.ts", "./global-mocks.ts"]

Questo e equivalente all'uso di --preload sulla riga di comando:

bun test --preload ./test-setup.ts --preload ./global-mocks.ts

Casi d'Uso Comuni del Preload

test-setup.ts

// Setup globale dei test
import { beforeAll, afterAll } from "bun:test";

beforeAll(() => {
  // Configura il database di test
  setupTestDatabase();
});

afterAll(() => {
  // Pulizia
  cleanupTestDatabase();
});

global-mocks.ts

// Mock globali
import { mock } from "bun:test";

// Mock delle variabili di ambiente
process.env.NODE_ENV = "test";
process.env.API_URL = "http://localhost:3001";

// Mock delle dipendenze esterne
mock.module("./external-api", () => ({
  fetchData: mock(() => Promise.resolve({ data: "test" })),
}));

Timeout

Timeout Predefinito

Imposta il timeout predefinito per tutti i test:

bunfig.toml

[test]
timeout = 10000  # 10 secondi (il default e 5000ms)

Questo si applica a tutti i test a meno che non venga sovrascritto dai timeout individuali dei test:

test.ts

// Questo test usera il timeout predefinito da bunfig.toml
test("usa il timeout predefinito", () => {
  // implementazione del test
});

// Questo test sovrascrive il timeout predefinito
test("timeout personalizzato", () => {
  // implementazione del test
}, 30000); // 30 secondi

Reporters

Reporter JUnit

Configura il percorso del file di output del reporter JUnit direttamente nel file di configurazione:

bunfig.toml

[test.reporter]
junit = "path/to/junit.xml"  # Percorso di output per il report JUnit XML

Questo complementa i flag CLI --reporter=junit e --reporter-outfile:

# Uso equivalente da riga di comando
bun test --reporter=junit --reporter-outfile=./junit.xml

Multipli Reporters

Puoi usare piu reporters simultaneamente:

# Approccio CLI
bun test --reporter=junit --reporter-outfile=./junit.xml

# Approccio con file di configurazione

bunfig.toml

[test.reporter]
junit = "./reports/junit.xml"

[test]
# Abilita anche il reporting della coverage
coverage = true
coverageReporter = ["text", "lcov"]

Utilizzo della Memoria

Modalita smol

Abilita la modalita di risparmio memoria --smol specificamente per il test runner:

bunfig.toml

[test]
smol = true  # Riduci l'utilizzo della memoria durante i test

Questo e equivalente all'uso del flag --smol sulla riga di comando:

bun test --smol

La modalita smol riduce l'utilizzo della memoria:

• Usando meno memoria per l'heap JavaScript
• Essendo piu aggressivi sulla garbage collection
• Riducendo le dimensioni dei buffer dove possibile

Questo e utile per:

• Ambienti CI con memoria limitata
• Grandi suite di test che consumano molta memoria
• Ambienti di sviluppo con vincoli di memoria

Esecuzione dei Test

concurrentTestGlob

Esegui automaticamente i file di test che corrispondono a un pattern glob con l'esecuzione dei test concorrente abilitata. Questo e utile per migrare gradualmente le suite di test all'esecuzione concorrente o per eseguire tipi specifici di test in modo concorrente.

bunfig.toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"  # Esegui i file che corrispondono a questo pattern in modo concorrente

I file di test che corrispondono a questo pattern si comporteranno come se il flag --concurrent fosse stato passato, eseguendo tutti i test all'interno di quei file in modo concorrente. Questo ti permette di:

• Migrare gradualmente la tua suite di test all'esecuzione concorrente
• Eseguire i test di integrazione in modo concorrente mantenendo quelli unitari sequenziali
• Separare i test concurrenti veloci da quelli che richiedono esecuzione sequenziale

Il flag CLI --concurrent sovrascrivera questa impostazione quando specificato, forzando tutti i test a essere eseguiti in modo concorrente indipendentemente dal pattern glob.

randomize

Esegui i test in ordine casuale per identificare test con dipendenze nascoste:

bunfig.toml

[test]
randomize = true

seed

Specifica un seed per l'ordine casuale riproducibile dei test. Richiede randomize = true:

bunfig.toml

[test]
randomize = true
seed = 2444615283

rerunEach

Riesegui ogni file di test piu volte per identificare test instabili:

bunfig.toml

[test]
rerunEach = 3

Opzioni di Coverage

Impostazioni Base della Coverage

bunfig.toml

[test]
# Abilita la coverage per default
coverage = true

# Imposta il reporter della coverage
coverageReporter = ["text", "lcov"]

# Imposta la directory di output della coverage
coverageDir = "./coverage"

Saltare i File di Test dalla Coverage

Escludi i file che corrispondono ai pattern dei test (es. *.test.ts) dal report della coverage:

bunfig.toml

[test]
coverageSkipTestFiles = true  # Escludi i file di test dai report della coverage

Soglie di Coverage

La soglia di coverage puo essere specificata come numero o come oggetto con soglie specifiche:

bunfig.toml

[test]
# Soglia semplice - si applica a linee, funzioni e statement
coverageThreshold = 0.8

# Soglie dettagliate
coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }

L'impostazione di una qualsiasi di queste abilita fail_on_low_coverage, facendo fallire l'esecuzione dei test se la coverage e inferiore alla soglia.

Esempi di Soglie

bunfig.toml

[test]
# Richiedi il 90% di coverage in generale
coverageThreshold = 0.9

# Requisiti diversi per metriche diverse
coverageThreshold = {
  lines = 0.85,      # 85% di coverage delle linee
  functions = 0.90,  # 90% di coverage delle funzioni
  statements = 0.80  # 80% di coverage degli statement
}

Pattern di Ignorazione dei Percorsi della Coverage

Escludi file specifici o pattern di file dai report della coverage usando pattern glob:

bunfig.toml

[test]
# Singolo pattern
coveragePathIgnorePatterns = "**/*.spec.ts"

# Multipli pattern
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**",
  "vendor/**"
]

I file che corrispondono a uno qualsiasi di questi pattern saranno esclusi dal calcolo e reporting della coverage. Vedi la documentazione della coverage per piu dettagli ed esempi.

Pattern di Ignorazione Comuni

bunfig.toml

[test]
coveragePathIgnorePatterns = [
  # File di test
  "**/*.test.ts",
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # File di configurazione
  "*.config.js",
  "*.config.ts",
  "webpack.config.*",
  "vite.config.*",

  # Output della build
  "dist/**",
  "build/**",
  ".next/**",

  # Codice generato
  "generated/**",
  "**/*.generated.ts",

  # Vendor/third-party
  "vendor/**",
  "third-party/**",

  # Utility che non necessitano di test
  "src/utils/constants.ts",
  "src/types/**"
]

Gestione delle Sourcemap

Internamente, Bun transpila ogni file. Questo significa che la coverage del codice deve anche passare per le sourcemap prima di poter essere riportata. Esponiamo questo come un flag per permetterti di uscire da questo comportamento, ma sara confuso perche durante il processo di transpilazione, Bun potrebbe spostare il codice e cambiare i nomi delle variabili. Questa opzione e principalmente utile per il debug dei problemi di coverage.

bunfig.toml

[test]
coverageIgnoreSourcemaps = true  # Non usare le sourcemap per l'analisi della coverage

Ereditarieta delle Impostazioni di Installazione

Il comando bun test eredita la configurazione di rete e installazione rilevante (registry, cafile, prefer, exact, ecc.) dalla sezione [install] di bunfig.toml. Questo e importante se i test devono interagire con registry privati o richiedono comportamenti di installazione specifici attivati durante l'esecuzione dei test.

bunfig.toml

[install]
# Queste impostazioni sono ereditate da bun test
registry = "https://npm.company.com/"
exact = true
prefer = "offline"

[test]
# Configurazione specifica per i test
coverage = true
timeout = 10000

Variabili di Ambiente

Puoi anche impostare variabili di ambiente nella tua configurazione che influenzano il comportamento dei test:

bunfig.toml

[env]
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
LOG_LEVEL = "error"

[test]
coverage = true

Esempio di Configurazione Completo

Ecco un esempio completo che mostra tutte le opzioni di configurazione dei test disponibili:

bunfig.toml

[install]
# Impostazioni di installazione ereditate dai test
registry = "https://registry.npmjs.org/"
exact = true

[env]
# Variabili di ambiente per i test
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
API_URL = "http://localhost:3001"
LOG_LEVEL = "error"

[test]
# Scoperta dei test
root = "src"
preload = ["./test-setup.ts", "./global-mocks.ts"]

# Impostazioni di esecuzione
timeout = 10000
smol = true

# Configurazione della coverage
coverage = true
coverageReporter = ["text", "lcov"]
coverageDir = "./coverage"
coverageThreshold = { lines = 0.85, functions = 0.90, statements = 0.80 }
coverageSkipTestFiles = true
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**"
]

# Impostazioni avanzate della coverage
coverageIgnoreSourcemaps = false

# Configurazione del reporter
[test.reporter]
junit = "./reports/junit.xml"

Comportamento di Override della CLI

Le opzioni da riga di comando sovrascrivono sempre le impostazioni del file di configurazione:

bunfig.toml

[test]
timeout = 5000
coverage = false

# Questi flag CLI sovrascrivono il file di configurazione
bun test --timeout 10000 --coverage
# timeout sara 10000ms e la coverage sara abilitata

Configurazione Condizionale

Puoi usare configurazioni diverse per ambienti diversi:

bunfig.toml

[test]
# Configurazione predefinita dei test
coverage = false
timeout = 5000

# Override per l'ambiente CI
[test.ci]
coverage = true
coverageThreshold = 0.8
timeout = 30000

Poi in CI:

# Usa le impostazioni specifiche per CI
bun test --config=ci

Validazione e Risoluzione dei Problemi

Configurazione Non Valida

Bun avvisera delle opzioni di configurazione non valide:

bunfig.toml

[test]
invalidOption = true  # Questo generera un avviso

Problemi di Configurazione Comuni

1. Risoluzione dei Percorsi: I percorsi relativi nella configurazione sono risolti relativamente alla posizione del file di configurazione
2. Corrispondenza dei Pattern: I pattern glob usano la sintassi standard dei glob
3. Mismatch dei Tipi: Assicurati che i valori numerici non siano tra virgolette a meno che non debbano essere stringhe

bunfig.toml

[test]
# Corretto
timeout = 10000

# Sbagliato - sara trattato come stringa
timeout = "10000"

Debug della Configurazione

Per vedere quale configurazione viene utilizzata:

# Mostra la configurazione effettiva
bun test --dry-run

# Output dettagliato per vedere il caricamento della configurazione
bun test --verbose