Configura bun test mediante el archivo bunfig.toml y opciones de línea de comandos. Esta página documenta las opciones de configuración disponibles para bun test.

Archivo de configuración

Puedes configurar el comportamiento de bun test agregando una sección [test] a tu archivo bunfig.toml:

bunfig.toml

[test]
# Las opciones van aquí

Descubrimiento de pruebas

root

La opción root especifica un directorio raíz para el descubrimiento de pruebas, anulando el comportamiento por defecto de escanear desde la raíz del proyecto.

bunfig.toml

[test]
root = "src"  # Solo escanear pruebas en el directorio src

Esto es útil cuando quieres:

• Limitar el descubrimiento de pruebas a directorios específicos
• Excluir ciertas partes de tu proyecto del escaneo de pruebas
• Organizar pruebas en una estructura de subdirectorios específica

Ejemplos

bunfig.toml

[test]
# Solo ejecutar pruebas en el directorio src
root = "src"

# Ejecutar pruebas en un directorio de pruebas específico
root = "tests"

# Ejecutar pruebas en múltiples directorios específicos (actualmente no soportado - usa patrones en su lugar)
# root = ["src", "lib"]  # Esta sintaxis no está soportada

Scripts de precarga

Carga scripts antes de ejecutar pruebas usando la opción preload:

bunfig.toml

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

Esto es equivalente a usar --preload en la línea de comandos:

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

Casos de uso comunes de precarga

test-setup.ts

// Configuración global de pruebas
import { beforeAll, afterAll } from "bun:test";

beforeAll(() => {
  // Configurar base de datos de pruebas
  setupTestDatabase();
});

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

global-mocks.ts

// Mocks globales
import { mock } from "bun:test";

// Mockear variables de entorno
process.env.NODE_ENV = "test";
process.env.API_URL = "http://localhost:3001";

// Mockear dependencias externas
mock.module("./external-api", () => ({
  fetchData: mock(() => Promise.resolve({ data: "test" })),
}));

Tiempos de espera

Tiempo de espera por defecto

Establece el tiempo de espera por defecto para todas las pruebas:

bunfig.toml

[test]
timeout = 10000  # 10 segundos (por defecto es 5000ms)

Esto se aplica a todas las pruebas a menos que sea anulado por tiempos de espera individuales:

test.ts

// Esta prueba usará el tiempo de espera por defecto de bunfig.toml
test("usa tiempo de espera por defecto", () => {
  // implementación de prueba
});

// Esta prueba anula el tiempo de espera por defecto
test("tiempo de espera personalizado", () => {
  // implementación de prueba
}, 30000); // 30 segundos

Reporteros

Reportero JUnit

Configura la ruta de salida del reportero JUnit directamente en el archivo de configuración:

bunfig.toml

[test.reporter]
junit = "path/to/junit.xml"  # Ruta de salida para informe XML JUnit

Esto complementa las banderas CLI --reporter=junit y --reporter-outfile:

# Uso de línea de comandos equivalente
bun test --reporter=junit --reporter-outfile=./junit.xml

Múltiples reporteros

Puedes usar múltiples reporteros simultáneamente:

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

# Enfoque archivo de configuración

bunfig.toml

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

[test]
# También habilitar informe de cobertura
coverage = true
coverageReporter = ["text", "lcov"]

Uso de memoria

Modo smol

Habilita el modo de ahorro de memoria --smol específicamente para el ejecutor de pruebas:

bunfig.toml

[test]
smol = true  # Reducir uso de memoria durante ejecuciones de pruebas

Esto es equivalente a usar la bandera --smol en la línea de comandos:

bun test --smol

El modo smol reduce el uso de memoria mediante:

• Usar menos memoria para el heap de JavaScript
• Ser más agresivo con la recolección de basura
• Reducir tamaños de buffer donde sea posible

Esto es útil para:

• Entornos CI con memoria limitada
• Suites de pruebas grandes que consumen memoria significativa
• Entornos de desarrollo con restricciones de memoria

Ejecución de pruebas

concurrentTestGlob

Ejecuta automáticamente archivos de prueba que coincidan con un patrón glob con ejecución concurrente habilitada. Esto es útil para migrar gradualmente suites de pruebas a ejecución concurrente o para ejecutar tipos específicos de pruebas concurrentemente.

bunfig.toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"  # Ejecutar archivos que coincidan con este patrón concurrentemente

Los archivos de prueba que coincidan con este patrón se comportarán como si la bandera --concurrent fuera pasada, ejecutando todas las pruebas dentro de esos archivos concurrentemente. Esto te permite:

• Migrar gradualmente tu suite de pruebas a ejecución concurrente
• Ejecutar pruebas de integración concurrentemente mientras mantienes las pruebas unitarias secuenciales
• Separar pruebas concurrentes rápidas de pruebas que requieren ejecución secuencial

La bandera CLI --concurrent anulará esta configuración cuando se especifique, forzando a todas las pruebas a ejecutarse concurrentemente independientemente del patrón glob.

randomize

Ejecuta pruebas en orden aleatorio para identificar pruebas con dependencias ocultas:

bunfig.toml

[test]
randomize = true

seed

Especifica una semilla para orden de pruebas aleatorio reproducible. Requiere randomize = true:

bunfig.toml

[test]
randomize = true
seed = 2444615283

rerunEach

Vuelve a ejecutar cada archivo de prueba múltiples veces para identificar pruebas inestables:

bunfig.toml

[test]
rerunEach = 3

Opciones de cobertura

Configuración básica de cobertura

bunfig.toml

[test]
# Habilitar cobertura por defecto
coverage = true

# Establecer reportero de cobertura
coverageReporter = ["text", "lcov"]

# Establecer directorio de salida de cobertura
coverageDir = "./coverage"

Omitir archivos de prueba de la cobertura

Excluye archivos que coincidan con patrones de prueba (por ejemplo, *.test.ts) del informe de cobertura:

bunfig.toml

[test]
coverageSkipTestFiles = true  # Excluir archivos de prueba de informes de cobertura

Umbrales de cobertura

El umbral de cobertura puede especificarse ya sea como un número o como un objeto con umbrales específicos:

bunfig.toml

[test]
# Umbral simple - se aplica a líneas, funciones y declaraciones
coverageThreshold = 0.8

# Umbrales detallados
coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }

Establecer cualquiera de estos habilita fail_on_low_coverage, haciendo que la ejecución de pruebas falle si la cobertura está por debajo del umbral.

Ejemplos de umbrales

bunfig.toml

[test]
# Requerir 90% de cobertura en general
coverageThreshold = 0.9

# Requisitos diferentes para diferentes métricas
coverageThreshold = {
  lines = 0.85,      # 85% de cobertura de líneas
  functions = 0.90,  # 90% de cobertura de funciones
  statements = 0.80  # 80% de cobertura de declaraciones
}

Patrones de omisión de ruta de cobertura

Excluye archivos específicos o patrones de archivos de informes de cobertura usando patrones glob:

bunfig.toml

[test]
# Patrón único
coveragePathIgnorePatterns = "**/*.spec.ts"

# Múltiples patrones
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**",
  "vendor/**"
]

Los archivos que coincidan con cualquiera de estos patrones se excluirán del cálculo e informe de cobertura. Consulta la documentación de cobertura para más detalles y ejemplos.

Patrones de omisión comunes

bunfig.toml

[test]
coveragePathIgnorePatterns = [
  # Archivos de prueba
  "**/*.test.ts",
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # Archivos de configuración
  "*.config.js",
  "*.config.ts",
  "webpack.config.*",
  "vite.config.*",

  # Salida de compilación
  "dist/**",
  "build/**",
  ".next/**",

  # Código generado
  "generated/**",
  "**/*.generated.ts",

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

  # Utilidades que no necesitan pruebas
  "src/utils/constants.ts",
  "src/types/**"
]

Manejo de sourcemap

Internamente, Bun transpila cada archivo. Eso significa que la cobertura de código también debe pasar por sourcemaps antes de poder ser reportada. Exponemos esto como una bandera para permitirte excluirte de este comportamiento, pero será confuso porque durante el proceso de transpilación, Bun puede mover código y cambiar nombres de variables. Esta opción es mayormente útil para depurar problemas de cobertura.

bunfig.toml

[test]
coverageIgnoreSourcemaps = true  # No usar sourcemaps para análisis de cobertura

Herencia de configuración de instalación

El comando bun test hereda configuración relevante de red e instalación (registry, cafile, prefer, exact, etc.) de la sección [install] de bunfig.toml. Esto es importante si las pruebas necesitan interactuar con registros privados o requieren comportamientos de instalación específicos activados durante la ejecución de pruebas.

bunfig.toml

[install]
# Estas configuraciones son heredadas por bun test
registry = "https://npm.company.com/"
exact = true
prefer = "offline"

[test]
# Configuración específica de pruebas
coverage = true
timeout = 10000

Variables de entorno

También puedes establecer variables de entorno en tu configuración que afectan el comportamiento de pruebas:

bunfig.toml

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

[test]
coverage = true

Ejemplo de configuración completa

Aquí hay un ejemplo completo mostrando todas las opciones de configuración de pruebas disponibles:

bunfig.toml

[install]
# Configuración de instalación heredada por pruebas
registry = "https://registry.npmjs.org/"
exact = true

[env]
# Variables de entorno para pruebas
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
API_URL = "http://localhost:3001"
LOG_LEVEL = "error"

[test]
# Descubrimiento de pruebas
root = "src"
preload = ["./test-setup.ts", "./global-mocks.ts"]

# Configuración de ejecución
timeout = 10000
smol = true

# Configuración de cobertura
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/**"
]

# Configuración avanzada de cobertura
coverageIgnoreSourcemaps = false

# Configuración de reporteros
[test.reporter]
junit = "./reports/junit.xml"

Comportamiento de anulación CLI

Las opciones de línea de comandos siempre anulan las configuraciones del archivo de configuración:

bunfig.toml

[test]
timeout = 5000
coverage = false

# Estas banderas CLI anulan el archivo de configuración
bun test --timeout 10000 --coverage
# timeout será 10000ms y coverage estará habilitado

Configuración condicional

Puedes usar diferentes configuraciones para diferentes entornos:

bunfig.toml

[test]
# Configuración de prueba por defecto
coverage = false
timeout = 5000

# Anular para entorno CI
[test.ci]
coverage = true
coverageThreshold = 0.8
timeout = 30000

Luego en CI:

# Usar configuración específica de CI
bun test --config=ci

Validación y solución de problemas

Configuración inválida

Bun advertirá sobre opciones de configuración inválidas:

bunfig.toml

[test]
invalidOption = true  # Esto generará una advertencia

Problemas comunes de configuración

1. Resolución de rutas: Las rutas relativas en la configuración se resuelven relativas a la ubicación del archivo de configuración
2. Coincidencia de patrones: Los patrones glob usan sintaxis glob estándar
3. Incoherencias de tipo: Asegúrate de que los valores numéricos no estén entre comillas a menos que deban ser strings

bunfig.toml

[test]
# Correcto
timeout = 10000

# Incorrecto - será tratado como string
timeout = "10000"

Depurar configuración

Para ver qué configuración se está usando:

# Mostrar configuración efectiva
bun test --dry-run

# Salida verbosa para ver carga de configuración
bun test --verbose