bun test está profundamente integrado con el runtime de Bun. Esto es parte de lo que hace que bun test sea rápido y simple de usar.

Variables de entorno

NODE_ENV

bun test automáticamente establece $NODE_ENV en "test" a menos que ya esté establecido en el entorno o mediante archivos .env. Este es el comportamiento estándar para la mayoría de los ejecutores de pruebas y ayuda a asegurar un comportamiento consistente de las pruebas.

test.ts

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

test("NODE_ENV está establecido en test", () => {
  expect(process.env.NODE_ENV).toBe("test");
});

Puedes anular esto estableciendo NODE_ENV explícitamente:

NODE_ENV=development bun test

TZ (Zona horaria)

Por defecto, todas las ejecuciones de bun test usan UTC (Etc/UTC) como zona horaria a menos que sea anulado por la variable de entorno TZ. Esto asegura un comportamiento consistente de fecha y hora en diferentes entornos de desarrollo.

test.ts

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

test("la zona horaria es UTC por defecto", () => {
  const date = new Date();
  expect(date.getTimezoneOffset()).toBe(0);
});

Para probar con una zona horaria específica:

TZ=America/New_York bun test

Tiempos de espera de pruebas

Cada prueba tiene un tiempo de espera por defecto de 5000ms (5 segundos) si no se anula explícitamente. Las pruebas que exceden este tiempo de espera fallarán.

Tiempo de espera global

Cambia el tiempo de espera globalmente con la bandera --timeout:

bun test --timeout 10000  # 10 segundos

Tiempo de espera por prueba

Establece el tiempo de espera por prueba como el tercer parámetro de la función de prueba:

test.ts

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

test("prueba rápida", () => {
  expect(1 + 1).toBe(2);
}, 1000); // 1 segundo de tiempo de espera

test("prueba lenta", async () => {
  await new Promise(resolve => setTimeout(resolve, 8000));
}, 10000); // 10 segundos de tiempo de espera

Tiempo de espera infinito

Usa 0 o Infinity para deshabilitar el tiempo de espera:

test.ts

test("prueba sin tiempo de espera", async () => {
  // Esta prueba puede ejecutarse indefinidamente
  await someVeryLongOperation();
}, 0);

Manejo de errores

Errores no manejados

bun test rastrea rechazos de promesas no manejados y errores que ocurren entre pruebas. Si ocurren tales errores, el código de salida final será distinto de cero (específicamente, la cantidad de tales errores), incluso si todas las pruebas pasan.

Esto ayuda a detectar errores en código asíncrono que de otro modo podrían pasar desapercibidos:

test.ts

import { test } from "bun:test";

test("prueba 1", () => {
  // Esta prueba pasa
  expect(true).toBe(true);
});

// Este error ocurre fuera de cualquier prueba
setTimeout(() => {
  throw new Error("Error no manejado");
}, 0);

test("prueba 2", () => {
  // Esta prueba también pasa
  expect(true).toBe(true);
});

// La ejecución de pruebas aún fallará con un código de salida distinto de cero
// debido al error no manejado

Rechazos de promesas

Los rechazos de promesas no manejados también se capturan:

test.ts

import { test } from "bun:test";

test("prueba aprobada", () => {
  expect(1).toBe(1);
});

// Esto hará que la ejecución de pruebas falle
Promise.reject(new Error("Rechazo no manejado"));

Manejo de errores personalizado

Puedes configurar manejadores de errores personalizados en tu configuración de pruebas:

test-setup.ts

process.on("uncaughtException", error => {
  console.error("Excepción no capturada:", error);
  process.exit(1);
});

process.on("unhandledRejection", (reason, promise) => {
  console.error("Rechazo no manejado en:", promise, "razón:", reason);
  process.exit(1);
});

Integración de banderas CLI

Varias banderas CLI de Bun pueden usarse con bun test para modificar su comportamiento:

Uso de memoria

# Reduce el uso de memoria para la VM del ejecutor de pruebas
bun test --smol

Depuración

# Adjunta el depurador al proceso del ejecutor de pruebas
bun test --inspect
bun test --inspect-brk

Carga de módulos

# Ejecuta scripts antes de los archivos de prueba (útil para configuración/mocks globales)
bun test --preload ./setup.ts

# Establece constantes en tiempo de compilación
bun test --define "process.env.API_URL='http://localhost:3000'"

# Configura loaders personalizados
bun test --loader .special:special-loader

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

# Establece condiciones de package.json para resolución de módulos
bun test --conditions development

# Carga variables de entorno para pruebas
bun test --env-file .env.test

Banderas relacionadas con instalación

# Afectan cualquier solicitud de red o auto-instalaciones durante la ejecución de pruebas
bun test --prefer-offline
bun test --frozen-lockfile

Watch y recarga en caliente

Modo watch

Al ejecutar bun test con la bandera --watch, el ejecutor de pruebas observará cambios en archivos y volverá a ejecutar las pruebas afectadas.

bun test --watch

El ejecutor de pruebas es inteligente sobre qué pruebas volver a ejecutar:

math.test.ts

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

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

Si modificas math.js, solo math.test.ts se volverá a ejecutar, no todas las pruebas.

Recarga en caliente

La bandera --hot proporciona funcionalidad similar pero es más agresiva al intentar preservar el estado entre ejecuciones:

bun test --hot

Para la mayoría de los escenarios de prueba, --watch es la opción recomendada ya que proporciona mejor aislamiento entre ejecuciones de pruebas.

Variables globales

Los siguientes globales están automáticamente disponibles en archivos de prueba sin importar (aunque pueden importarse de bun:test si se prefiere):

test.ts

// Todos estos están disponibles globalmente
test("función de prueba global", () => {
  expect(true).toBe(true);
});

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

  it("función it global", () => {
    // it es un alias de test
  });
});

// Compatibilidad con Jest
jest.fn();

// Compatibilidad con Vitest
vi.fn();

También puedes importarlos explícitamente si lo prefieres:

test.ts

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

Integración de procesos

Códigos de salida

bun test usa códigos de salida estándar:

• 0: Todas las pruebas pasaron, sin errores no manejados
• 1: Ocurrieron fallos en pruebas
• >1: Cantidad de errores no manejados (incluso si las pruebas pasaron)

Manejo de señales

El ejecutor de pruebas maneja apropiadamente señales comunes:

# Detiene gracefulmente la ejecución de pruebas
kill -SIGTERM <test-process-pid>

# Detiene inmediatamente la ejecución de pruebas
kill -SIGKILL <test-process-pid>

Detección de entorno

Bun detecta automáticamente ciertos entornos y ajusta el comportamiento:

test.ts

// Detección de GitHub Actions
if (process.env.GITHUB_ACTIONS) {
  // Bun automáticamente emite anotaciones de GitHub Actions
}

// Detección de CI
if (process.env.CI) {
  // Ciertos comportamientos pueden ajustarse para entornos CI
}

Consideraciones de rendimiento

Proceso único

El ejecutor de pruebas ejecuta todas las pruebas en un solo proceso por defecto. Esto proporciona:

• Inicio más rápido - No es necesario generar múltiples procesos
• Memoria compartida - Uso eficiente de recursos
• Depuración simple - Todas las pruebas en un proceso

Sin embargo, esto significa:

• Las pruebas comparten estado global (usa hooks de ciclo de vida para limpiar)
• Un fallo de prueba puede afectar a otras
• No hay paralelización real de pruebas individuales

Gestión de memoria

# Monitorear uso de memoria
bun test --smol  # Reduce la huella de memoria

# Para suites de pruebas grandes, considera dividir archivos
bun test src/unit/
bun test src/integration/

Aislamiento de pruebas

Dado que las pruebas se ejecutan en el mismo proceso, asegura una limpieza apropiada:

test.ts

import { afterEach } from "bun:test";

afterEach(() => {
  // Limpiar estado global
  global.myGlobalVar = undefined;
  delete process.env.TEST_VAR;

  // Restablecer módulos si es necesario
  jest.resetModules();
});