Il test runner di Bun ora supporta il reporting della code coverage integrata. Questo ti permette di vedere quanto del codice e coperto dai test e trovare aree che non sono attualmente ben testate.

Abilitazione della Coverage

bun:test supporta la visualizzazione delle righe di codice coperte dai test. Per utilizzare questa funzionalita, passa --coverage alla CLI. Stampa un report della coverage sulla console:

bun test --coverage

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   38.89 |   42.11 |
 index-0.ts  |   33.33 |   36.84 | 10-15,19-24
 index-1.ts  |   33.33 |   36.84 | 10-15,19-24
 index-10.ts |   33.33 |   36.84 | 10-15,19-24
 index-2.ts  |   33.33 |   36.84 | 10-15,19-24
 index-3.ts  |   33.33 |   36.84 | 10-15,19-24
 index-4.ts  |   33.33 |   36.84 | 10-15,19-24
 index-5.ts  |   33.33 |   36.84 | 10-15,19-24
 index-6.ts  |   33.33 |   36.84 | 10-15,19-24
 index-7.ts  |   33.33 |   36.84 | 10-15,19-24
 index-8.ts  |   33.33 |   36.84 | 10-15,19-24
 index-9.ts  |   33.33 |   36.84 | 10-15,19-24
 index.ts    |  100.00 |  100.00 |
-------------|---------|---------|-------------------

Abilitare di Default

Per abilitare sempre il reporting della coverage per default, aggiungi la seguente riga al tuo bunfig.toml:

bunfig.toml

[test]
# Abilita sempre la coverage
coverage = true

Di default, i report della coverage includono i file di test ed escludono le sourcemap. Questo e generalmente quello che vuoi, ma puo essere configurato diversamente in bunfig.toml.

bunfig.toml

[test]
coverageSkipTestFiles = true  # default false

Soglie di Coverage

E possibile specificare una soglia di coverage in bunfig.toml. Se la tua suite di test non raggiunge o supera questa soglia, bun test uscira con un codice di uscita non-zero per indicare il fallimento.

Soglia Semplice

bunfig.toml

[test]
# Per richiedere il 90% di coverage a livello di linee e funzioni
coverageThreshold = 0.9

Soglie Dettagliate

bunfig.toml

[test]
# Per impostare soglie diverse per linee e funzioni
coverageThreshold = { lines = 0.9, functions = 0.9, statements = 0.9 }

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

Reporters della Coverage

Di default, i report della coverage vengono stampati sulla console.

Per report persistenti della code coverage in ambienti CI e per altri strumenti, puoi passare l'opzione CLI --coverage-reporter=lcov o l'opzione coverageReporter in bunfig.toml.

bunfig.toml

[test]
coverageReporter = ["text", "lcov"]  # default ["text"]
coverageDir = "path/to/somewhere"    # default "coverage"

Reporters Disponibili

Reporter	Description
text	Stampa un sommario testuale della coverage sulla console
lcov	Salva la coverage in formato lcov

Reporter LCOV Coverage

Per generare un report lcov, puoi usare il reporter lcov. Questo generera un file lcov.info nella directory della coverage.

bunfig.toml

[test]
coverageReporter = "lcov"

# O via CLI
bun test --coverage --coverage-reporter=lcov

Il formato LCOV e ampiamente supportato da vari strumenti e servizi:

• Code editor: Le estensioni VS Code possono mostrare la coverage inline
• Servizi CI/CD: GitHub Actions, GitLab CI, CircleCI
• Servizi di coverage: Codecov, Coveralls
• IDE: WebStorm, IntelliJ IDEA

Usare LCOV con GitHub Actions

.github/workflows/test.yml

name: Test with Coverage
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test --coverage --coverage-reporter=lcov
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

Escludere File dalla Coverage

Saltare i File di Test

Di default, i file di test stessi sono inclusi nei report della coverage. Puoi escluderli con:

bunfig.toml

[test]
coverageSkipTestFiles = true  # default false

Questo escludera i file che corrispondono ai pattern dei test (es. *.test.ts, *.spec.js) dal report della coverage.

Ignorare Percorsi e Pattern Specifici

Puoi escludere file specifici o pattern di file dai report della coverage usando coveragePathIgnorePatterns:

bunfig.toml

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

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

Questa opzione accetta pattern glob e funziona in modo simile ai pattern di ignore di Jest's collectCoverageFrom. I file che corrispondono a uno qualsiasi di questi pattern saranno esclusi dal calcolo e reporting della coverage sia negli output text che LCOV.

Casi d'Uso Comuni

bunfig.toml

[test]
coveragePathIgnorePatterns = [
  # Escludi file utility
  "src/utils/**",

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

  # Escludi pattern di test specifici
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # Escludi artefatti di build
  "dist/**",
  "build/**",

  # Escludi file generati
  "src/generated/**",
  "**/*.generated.ts",

  # Escludi codice vendor/third-party
  "vendor/**",
  "third-party/**"
]

Sourcemap

Internamente, Bun transpila tutti i file per default, quindi Bun genera automaticamente una sourcemap interna che mappa le righe del tuo codice sorgente originale sulla rappresentazione interna di Bun. Se per qualsiasi motivo vuoi disabilitare questo, imposta test.coverageIgnoreSourcemaps a true; questo raramente sara desiderabile al di fuori di casi d'uso avanzati.

bunfig.toml

[test]
coverageIgnoreSourcemaps = true  # default false

Valori Default della Coverage

Di default, i report della coverage:

• Escludono le directory node_modules
• Escludono i file caricati tramite loader non-JS/TS (es. .css, .txt) a meno che non sia specificato un loader JS personalizzato
• Includono i file di test stessi (può essere disabilitato con coverageSkipTestFiles = true)
• Possono escludere file aggiuntivi con coveragePathIgnorePatterns

Configurazione Avanzata

Directory della Coverage Personalizzata

bunfig.toml

[test]
coverageDir = "coverage-reports"  # default "coverage"

Multipli Reporters

bunfig.toml

[test]
coverageReporter = ["text", "lcov"]

Coverage con Pattern di Test Specifici

# Esegui la coverage solo su file di test specifici
bun test --coverage src/components/*.test.ts

# Esegui la coverage con il pattern del nome
bun test --coverage --test-name-pattern="API"

Integrazione CI/CD

Esempio GitHub Actions

.github/workflows/coverage.yml

name: Coverage Report
on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Install dependencies
        run: bun install

      - name: Run tests with coverage
        run: bun test --coverage --coverage-reporter=lcov

      - name: Upload to Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info
          fail_ci_if_error: true

Esempio GitLab CI

.gitlab-ci.yml

test:coverage:
  stage: test
  script:
    - bun install
    - bun test --coverage --coverage-reporter=lcov
  coverage: '/Lines\s*:\s*(\d+.\d+)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/lcov.info

Interpretare i Report della Coverage

Spiegazione dell'Output Testuale

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   85.71 |   90.48 |
 src/        |   85.71 |   90.48 |
  utils.ts   |  100.00 |  100.00 |
  api.ts     |   75.00 |   85.71 | 15-18,25
  main.ts    |   80.00 |   88.89 | 42,50-52
-------------|---------|---------|-------------------

• % Funcs: Percentuale di funzioni che sono state chiamate durante i test
• % Lines: Percentuale di righe eseguibili che sono state eseguite durante i test
• Uncovered Line #s: Numeri di riga specifici che non sono stati eseguiti

Cosa Puntare

• Coverage totale dell'80%+: Generalmente considerata buona
• Coverage del 90%+ per i percorsi critici: La logica di business importante dovrebbe essere ben testata
• Coverage del 100% per le funzioni utility: Le funzioni pure e le utility sono facili da testare completamente
• Coverage inferiore per i componenti UI: Spesso accettabile poiche potrebbero richiedere test di integrazione

Best Practices

Concentrati sulla Qualita, Non Solo sulla Quantita

test.ts

// Buono: Testa la funzionalita effettiva
test("calculateTax dovrebbe gestire diverse aliquote fiscali", () => {
  expect(calculateTax(100, 0.08)).toBe(8);
  expect(calculateTax(100, 0.1)).toBe(10);
  expect(calculateTax(0, 0.08)).toBe(0);
});

// Evita: Solo toccare le righe per la coverage
test("calculateTax esiste", () => {
  calculateTax(100, 0.08); // Nessuna asserzione!
});

Testa i Casi Limite

test.ts

test("validazione input utente", () => {
  // Testa il caso normale
  expect(validateEmail("user@example.com")).toBe(true);

  // Testa i casi limite che migliorano la coverage in modo significativo
  expect(validateEmail("")).toBe(false);
  expect(validateEmail("invalid")).toBe(false);
  expect(validateEmail(null)).toBe(false);
});

Usa la Coverage per Trovare Test Mancanti

# Esegui la coverage per identificare il codice non testato
bun test --coverage

# Guarda i file specifici che necessitano attenzione
bun test --coverage src/critical-module.ts

Combina con Altre Metriche di Qualita

La coverage e solo una metrica. Considera anche:

• Qualita della code review
• Coverage dei test di integrazione
• Test della gestione degli errori
• Test delle performance
• Type safety

Risoluzione dei Problemi

la Coverage Non Viene Mostrata per Alcuni File

Se i file non appaiono nei report della coverage, potrebbero non essere importati dai tuoi test. La coverage traccia solo i file che vengono effettivamente caricati.

test.ts

// Assicurati di importare i moduli che vuoi testare
import { myFunction } from "../src/my-module";

test("la mia funzione funziona", () => {
  expect(myFunction()).toBeDefined();
});

Report della Coverage Falsi

Se vedi report della coverage che non corrispondono alle tue aspettative:

1. Controlla se le sourcemap funzionano correttamente
2. Verifica i pattern dei file in coveragePathIgnorePatterns
3. Assicurati che i file di test stiano effettivamente importando il codice da testare

Problemi di Performance con Codebase Grandi

Per progetti grandi, la raccolta della coverage puo rallentare i test:

bunfig.toml

[test]
# Escludi le directory grandi per cui non ti serve la coverage
coveragePathIgnorePatterns = [
  "node_modules/**",
  "vendor/**",
  "generated/**"
]

Considera di eseguire la coverage solo su CI o rami specifici piuttosto che su ogni esecuzione di test durante lo sviluppo.