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

Bun vem com um executor de testes rápido integrado e compatível com Jest. Os testes são executados com o runtime do Bun e oferecem suporte aos seguintes recursos.

• TypeScript e JSX
• Hooks de lifecycle
• Teste de snapshot
• Teste de UI e DOM
• Modo watch com --watch
• Pré-carregamento de scripts com --preload

NOTE

O Bun visa compatibilidade com Jest, mas nem tudo está implementado. Para acompanhar a compatibilidade, veja [esta issue de rastreamento](https://github.com/oven-sh/bun/issues/1825).

Executar testes

bun test

Os testes são escritos em JavaScript ou TypeScript com uma API semelhante ao Jest. Consulte Escrevendo testes para documentação completa.

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

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

O executor pesquisa recursivamente o diretório de trabalho por arquivos que correspondem aos seguintes padrões:

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

Você pode filtrar o conjunto de arquivos de teste a serem executados passando argumentos posicionais adicionais para bun test. Qualquer arquivo de teste com um caminho que corresponda a um dos filtros será executado. Comumente, esses filtros serão nomes de arquivos ou diretórios; padrões glob ainda não são suportados.

bun test <filtro> <filtro> ...

Para filtrar por nome de teste, use a flag -t/--test-name-pattern.

# executar todos os testes ou suítes de teste com "adição" no nome
bun test --test-name-pattern adicao

Para executar um arquivo específico no executor de teste, certifique-se de que o caminho começa com ./ ou / para distingui-lo de um nome de filtro.

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

O executor de testes executa todos os testes em um único processo. Ele carrega todos os scripts --preload (veja Lifecycle para detalhes), depois executa todos os testes. Se um teste falhar, o executor de testes sairá com um código de saída diferente de zero.

Integração CI/CD

bun test oferece suporte a uma variedade de integrações CI/CD.

GitHub Actions

bun test detecta automaticamente se está sendo executado dentro do GitHub Actions e emitirá anotações do GitHub Actions diretamente no console.

Nenhuma configuração é necessária, além de instalar bun no workflow e executar bun test.

Como instalar bun em um workflow do GitHub Actions

Para usar bun test em um workflow do GitHub Actions, adicione a seguinte etapa:

.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: Instalar dependências # (supondo que seu projeto tenha dependências)
        run: bun install # Você pode usar npm/yarn/pnpm se preferir
      - name: Executar testes
        run: bun test

A partir daí, você receberá anotações do GitHub Actions.

Relatórios XML JUnit (GitLab, etc.)

Para usar bun test com um reporter XML JUnit, você pode usar --reporter=junit em combinação com --reporter-outfile.

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

Isso continuará a produzir saída para stdout/stderr como de costume e também escreverá um relatório XML JUnit para o caminho fornecido no final da execução do teste.

XML JUnit é um formato popular para relatar resultados de testes em pipelines CI/CD.

Timeouts

Use a flag --timeout para especificar um timeout por teste em milissegundos. Se um teste exceder o tempo limite, será marcado como falho. O valor padrão é 5000.

# valor padrão é 5000
bun test --timeout 20

Execução de teste concorrente

Por padrão, o Bun executa todos os testes sequencialmente dentro de cada arquivo de teste. Você pode habilitar a execução concorrente para executar testes assíncronos em paralelo, acelerando significativamente suítes de teste com testes independentes.

Flag --concurrent

Use a flag --concurrent para executar todos os testes concorrentemente dentro de seus respectivos arquivos:

bun test --concurrent

Quando esta flag está habilitada, todos os testes serão executados em paralelo, a menos que sejam explicitamente marcados com test.serial.

Flag --max-concurrency

Controle o número máximo de testes executando simultaneamente com a flag --max-concurrency:

# Limitar a 4 testes concorrentes
bun test --concurrent --max-concurrency 4

# Padrão: 20
bun test --concurrent

Isso ajuda a prevenir exaustão de recursos ao executar muitos testes concorrentes. O valor padrão é 20.

test.concurrent

Marque testes individuais para serem executados concorrentemente, mesmo quando a flag --concurrent não for usada:

math.test.ts

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

// Estes testes são executados em paralelo uns com os outros
test.concurrent("teste concorrente 1", async () => {
  await fetch("/api/endpoint1");
  expect(true).toBe(true);
});

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

// Este teste é executado sequencialmente
test("teste sequencial", () => {
  expect(1 + 1).toBe(2);
});

test.serial

Force testes a serem executados sequencialmente, mesmo quando a flag --concurrent estiver habilitada:

math.test.ts

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

let sharedState = 0;

// Estes testes devem ser executados em ordem
test.serial("primeiro teste serial", () => {
  sharedState = 1;
  expect(sharedState).toBe(1);
});

test.serial("segundo teste serial", () => {
  // Depende do teste anterior
  expect(sharedState).toBe(1);
  sharedState = 2;
});

// Este teste pode ser executado concorrentemente se --concurrent estiver habilitado
test("teste independente", () => {
  expect(true).toBe(true);
});

// Encadeando qualificadores de teste
test.failing.each([1, 2, 3])("qualificadores encadeados %d", input => {
  expect(input).toBe(0); // Este teste deve falhar para cada entrada
});

Re-executar testes

Use a flag --rerun-each para executar cada teste múltiplas vezes. Isso é útil para detectar testes instáveis ou falhas não determinísticas.

bun test --rerun-each 100

Randomizar ordem de execução de testes

Use a flag --randomize para executar testes em ordem aleatória. Isso ajuda a detectar testes que dependem de estado compartilhado ou ordem de execução.

bun test --randomize

Ao usar --randomize, a seed usada para randomização será exibida no resumo do teste:

bun test --randomize

# ... saída do teste ...
 --seed=12345
 2 aprovações
 8 falhas
Executados 10 testes em 2 arquivos. [50.00ms]

Ordem aleatória reproduzível com --seed

Use a flag --seed para especificar uma seed para a randomização. Isso permite que você reproduza a mesma ordem de teste ao depurar falhas dependentes de ordem.

# Reproduzir uma execução aleatória anterior
bun test --seed 123456

A flag --seed implica --randomize, então você não precisa especificar ambas. Usar o mesmo valor de seed sempre produzirá a mesma ordem de execução de teste, facilitando a depuração de falhas intermitentes causadas por interdependências de teste.

Interromper com --bail

Use a flag --bail para abortar a execução do teste antecipadamente após um número predeterminado de falhas de teste. Por padrão, o Bun executará todos os testes e relatará todas as falhas, mas às vezes em ambientes CI é preferível terminar mais cedo para reduzir o uso de CPU.

# interromper após 1 falha
bun test --bail

# interromper após 10 falhas
bun test --bail=10

Modo watch

Semelhante ao bun run, você pode passar a flag --watch para bun test para observar alterações e re-executar testes.

bun test --watch

Hooks de lifecycle

O Bun oferece suporte aos seguintes hooks de lifecycle:

Hook	Descrição
beforeAll	Executa uma vez antes de todos testes.
beforeEach	Executa antes de cada teste.
afterEach	Executa após cada teste.
afterAll	Executa uma vez após todos testes.

Estes hooks podem ser definidos dentro de arquivos de teste ou em um arquivo separado que é pré-carregado com a flag --preload.

bun test --preload ./setup.ts

Veja Teste > Lifecycle para documentação completa.

Mocks

Crie funções mock com a função 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, você pode usar jest.fn(), que se comporta identicamente.

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()); 

Veja Teste > Mocks para documentação completa.

Teste de snapshot

Snapshots são suportados pelo bun test.

math.test.ts

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

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

Para atualizar snapshots, use a flag --update-snapshots.

bun test --update-snapshots

Veja Teste > Snapshots para documentação completa.

Teste de UI e DOM

Bun é compatível com bibliotecas populares de teste de UI:

• HappyDOM
• DOM Testing Library
• React Testing Library

Veja Teste > Teste de DOM para documentação completa.

Desempenho

O executor de testes do Bun é rápido.

Integração com Agente de IA

Ao usar o executor de testes do Bun com assistentes de codificação de IA, você pode habilitar saída mais silenciosa para melhorar a legibilidade e reduzir ruído de contexto. Este recurso minimiza a verbosidade da saída de teste enquanto preserva informações essenciais de falha.

Variáveis de Ambiente

Defina qualquer uma das seguintes variáveis de ambiente para habilitar saída amigável para IA:

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

Comportamento

Quando um ambiente de agente de IA é detectado:

• Apenas falhas de teste são exibidas em detalhes
• Indicadores de teste aprovados, ignorados e todo estão ocultos
• Estatísticas de resumo permanecem intactas

# Exemplo: Habilitar saída silenciosa para Claude Code
CLAUDECODE=1 bun test

# Ainda mostra falhas e resumo, mas oculta saída verbosa de testes aprovados

Este recurso é particularmente útil em fluxos de trabalho de desenvolvimento assistido por IA, onde a verbosidade reduzida da saída melhora a eficiência do contexto enquanto mantém a visibilidade das falhas de teste.