import Test from "/snippets/cli/test.mdx";

Bun incluye un ejecutor de pruebas rápido, integrado y compatible con Jest. Las pruebas se ejecutan con el runtime de Bun y admiten las siguientes características.

• TypeScript y JSX
• Hooks de ciclo de vida
• Pruebas de snapshot
• Pruebas de UI y DOM
• Modo watch con --watch
• Precarga de scripts con --preload

NOTE

Bun apunta a la compatibilidad con Jest, pero no todo está implementado. Para rastrear la compatibilidad, consulta [este issue de seguimiento](https://github.com/oven-sh/bun/issues/1825).

Ejecutar pruebas

bun test

Las pruebas se escriben en JavaScript o TypeScript con una API similar a Jest. Consulta Escribir pruebas para documentación completa.

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

test("2 + 2", () => {
  expect(2 + 2).toBe(4);
});

El ejecutor busca recursivamente en el directorio de trabajo archivos que coincidan con los siguientes patrones:

• *.test.{js|jsx|ts|tsx}
• *_test.{js|jsx|ts|tsx}
• *.spec.{js|jsx|ts|tsx}
• *_spec.{js|jsx|ts|tsx}

Puedes filtrar el conjunto de archivos de prueba a ejecutar pasando argumentos de posición adicionales a bun test. Cualquier archivo de prueba con una ruta que coincida con uno de los filtros se ejecutará. Comúnmente, estos filtros serán nombres de archivos o directorios; los patrones glob aún no están soportados.

bun test <filtro> <filtro> ...

Para filtrar por nombre de prueba, usa la bandera -t/--test-name-pattern.

# ejecutar todas las pruebas o suites de pruebas con "adición" en el nombre
bun test --test-name-pattern adición

Para ejecutar un archivo específico en el ejecutor de pruebas, asegúrate de que la ruta comience con ./ o / para distinguirlo de un nombre de filtro.

bun test ./test/specific-file.test.ts

El ejecutor de pruebas ejecuta todas las pruebas en un solo proceso. Carga todos los scripts --preload (consulta Ciclo de vida para detalles), luego ejecuta todas las pruebas. Si una prueba falla, el ejecutor de pruebas saldrá con un código de salida distinto de cero.

Integración CI/CD

bun test admite una variedad de integraciones CI/CD.

GitHub Actions

bun test detecta automáticamente si se está ejecutando dentro de GitHub Actions y emitirá anotaciones de GitHub Actions directamente a la consola.

No se necesita configuración, más allá de instalar bun en el workflow y ejecutar bun test.

Cómo instalar bun en un workflow de GitHub Actions

Para usar bun test en un workflow de GitHub Actions, agrega el siguiente paso:

.github/workflows/test.yml

jobs:
  build:
    name: build-app
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Install bun
        uses: oven-sh/setup-bun@v2
      - name: Install dependencies # (asumiendo que tu proyecto tiene dependencias)
        run: bun install # Puedes usar npm/yarn/pnpm en su lugar si lo prefieres
      - name: Run tests
        run: bun test

Desde allí, obtendrás anotaciones de GitHub Actions.

Informes XML JUnit (GitLab, etc.)

Para usar bun test con un reportero JUnit XML, puedes usar --reporter=junit en combinación con --reporter-outfile.

bun test --reporter=junit --reporter-outfile=./bun.xml

Esto continuará generando salida a stdout/stderr como de costumbre, y también escribirá un informe XML JUnit a la ruta dada al final de la ejecución de pruebas.

JUnit XML es un formato popular para reportar resultados de pruebas en pipelines CI/CD.

Tiempos de espera

Usa la bandera --timeout para especificar un tiempo de espera por prueba en milisegundos. Si una prueba excede el tiempo de espera, se marcará como fallida. El valor por defecto es 5000.

# el valor por defecto es 5000
bun test --timeout 20

Ejecución concurrente de pruebas

Por defecto, Bun ejecuta todas las pruebas secuencialmente dentro de cada archivo de prueba. Puedes habilitar la ejecución concurrente para ejecutar pruebas async en paralelo, acelerando significativamente las suites de pruebas con pruebas independientes.

Bandera --concurrent

Usa la bandera --concurrent para ejecutar todas las pruebas concurrentemente dentro de sus respectivos archivos:

bun test --concurrent

Cuando esta bandera está habilitada, todas las pruebas se ejecutarán en paralelo a menos que estén explícitamente marcadas con test.serial.

Bandera --max-concurrency

Controla el número máximo de pruebas ejecutándose simultáneamente con la bandera --max-concurrency:

# Limitar a 4 pruebas concurrentes
bun test --concurrent --max-concurrency 4

# Por defecto: 20
bun test --concurrent

Esto ayuda a prevenir el agotamiento de recursos al ejecutar muchas pruebas concurrentes. El valor por defecto es 20.

test.concurrent

Marca pruebas individuales para ejecutarse concurrentemente, incluso cuando la bandera --concurrent no se usa:

math.test.ts

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

// Estas pruebas se ejecutan en paralelo entre sí
test.concurrent("prueba concurrente 1", async () => {
  await fetch("/api/endpoint1");
  expect(true).toBe(true);
});

test.concurrent("prueba concurrente 2", async () => {
  await fetch("/api/endpoint2");
  expect(true).toBe(true);
});

// Esta prueba se ejecuta secuencialmente
test("prueba secuencial", () => {
  expect(1 + 1).toBe(2);
});

test.serial

Forzar pruebas a ejecutarse secuencialmente, incluso cuando la bandera --concurrent está habilitada:

math.test.ts

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

let sharedState = 0;

// Estas pruebas deben ejecutarse en orden
test.serial("primera prueba serial", () => {
  sharedState = 1;
  expect(sharedState).toBe(1);
});

test.serial("segunda prueba serial", () => {
  // Depende de la prueba anterior
  expect(sharedState).toBe(1);
  sharedState = 2;
});

// Esta prueba puede ejecutarse concurrentemente si --concurrent está habilitado
test("prueba independiente", () => {
  expect(true).toBe(true);
});

// Encadenar calificadores de prueba
test.failing.each([1, 2, 3])("calificadores encadenados %d", input => {
  expect(input).toBe(0); // Se espera que esta prueba falle para cada entrada
});

Reejecutar pruebas

Usa la bandera --rerun-each para ejecutar cada prueba múltiples veces. Esto es útil para detectar fallos de pruebas inestables o no deterministas.

bun test --rerun-each 100

Aleatorizar orden de ejecución de pruebas

Usa la bandera --randomize para ejecutar pruebas en un orden aleatorio. Esto ayuda a detectar pruebas que dependen de estado compartido o orden de ejecución.

bun test --randomize

Cuando usas --randomize, la semilla usada para la aleatorización se mostrará en el resumen de pruebas:

bun test --randomize

# ... salida de pruebas ...
 --seed=12345
 2 pass
 8 fail
Ran 10 tests across 2 files. [50.00ms]

Orden aleatorio reproducible con --seed

Usa la bandera --seed para especificar una semilla para la aleatorización. Esto te permite reproducir el mismo orden de pruebas al depurar fallos dependientes del orden.

# Reproducir una ejecución aleatorizada anterior
bun test --seed 123456

La bandera --seed implica --randomize, así que no necesitas especificar ambas. Usar el mismo valor de semilla siempre producirá el mismo orden de ejecución de pruebas, facilitando depurar fallos intermitentes causados por interdependencias de pruebas.

Abortar con --bail

Usa la bandera --bail para abortar la ejecución de pruebas temprano después de un número predeterminado de fallos de pruebas. Por defecto Bun ejecutará todas las pruebas y reportará todos los fallos, pero a veces en entornos CI es preferible terminar antes para reducir el uso de CPU.

# abortar después de 1 fallo
bun test --bail

# abortar después de 10 fallos
bun test --bail=10

Modo watch

Similar a bun run, puedes pasar la bandera --watch a bun test para observar cambios y volver a ejecutar pruebas.

bun test --watch

Hooks de ciclo de vida

Bun admite los siguientes hooks de ciclo de vida:

Hook	Descripción
beforeAll	Se ejecuta una vez antes de todas las pruebas.
beforeEach	Se ejecuta antes de cada prueba.
afterEach	Se ejecuta después de cada prueba.
afterAll	Se ejecuta una vez después de todas las pruebas.

Estos hooks pueden definirse dentro de archivos de prueba, o en un archivo separado que se precarga con la bandera --preload.

bun test --preload ./setup.ts

Consulta Pruebas > Ciclo de vida para documentación completa.

Mocks

Crea funciones mock con la función mock.

math.test.ts

import { test, expect, mock } from "bun:test";
const random = mock(() => Math.random());

test("random", () => {
  const val = random();
  expect(val).toBeGreaterThan(0);
  expect(random).toHaveBeenCalled();
  expect(random).toHaveBeenCalledTimes(1);
});

Alternativamente, puedes usar jest.fn(), se comporta idénticamente.

math.test.ts

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

const random = mock(() => Math.random()); 
const random = jest.fn(() => Math.random()); 

Consulta Pruebas > Mocks para documentación completa.

Pruebas de snapshot

Los snapshots son soportados por bun test.

math.test.ts

// ejemplo de uso de toMatchSnapshot
import { test, expect } from "bun:test";

test("snapshot", () => {
  expect({ a: 1 }).toMatchSnapshot();
});

Para actualizar snapshots, usa la bandera --update-snapshots.

bun test --update-snapshots

Consulta Pruebas > Snapshots para documentación completa.

Pruebas de UI y DOM

Bun es compatible con bibliotecas populares de pruebas de UI:

• HappyDOM
• DOM Testing Library
• React Testing Library

Consulta Pruebas > Pruebas de DOM para documentación completa.

Rendimiento

El ejecutor de pruebas de Bun es rápido.

Integración con Agentes de IA

Cuando uses el ejecutor de pruebas de Bun con asistentes de codificación de IA, puedes habilitar una salida más silenciosa para mejorar la legibilidad y reducir el ruido de contexto. Esta función minimiza la verbosidad de la salida de pruebas mientras preserva la información esencial de fallos.

Variables de entorno

Establece cualquiera de las siguientes variables de entorno para habilitar la salida amigable para IA:

• CLAUDECODE=1 - Para Claude Code
• REPL_ID=1 - Para Replit
• AGENT=1 - Bandera genérica de agente de IA

Comportamiento

Cuando se detecta un entorno de agente de IA:

• Solo los fallos de pruebas se muestran en detalle
• Los indicadores de pruebas aprobadas, omitidas y todo se ocultan
• Las estadísticas de resumen permanecen intactas

# Ejemplo: Habilitar salida silenciosa para Claude Code
CLAUDECODE=1 bun test

# Aún muestra fallos y resumen, pero oculta salida verbosa de pruebas aprobadas

Esta función es particularmente útil en flujos de trabajo de desarrollo asistidos por IA donde la menor verbosidad de salida mejora la eficiencia del contexto mientras mantiene la visibilidad de los fallos de pruebas.