Configure bun test via arquivo bunfig.toml e opções de linha de comando. Esta página documenta as opções de configuração disponíveis para bun test.

Arquivo de Configuração

Você pode configurar o comportamento do bun test adicionando uma seção [test] ao seu arquivo bunfig.toml:

bunfig.toml

[test]
# As opções vão aqui

Descoberta de Testes

root

A opção root especifica um diretório raiz para descoberta de testes, substituindo o comportamento padrão de varrer a partir da raiz do projeto.

bunfig.toml

[test]
root = "src"  # Apenas varrer por testes no diretório src

Isso é útil quando você deseja:

• Limitar a descoberta de testes a diretórios específicos
• Excluir certas partes do seu projeto da varredura de testes
• Organizar testes em uma estrutura de subdiretório específica

Exemplos

bunfig.toml

[test]
# Apenas executar testes no diretório src
root = "src"

# Executar testes em um diretório de teste específico
root = "tests"

# Executar testes em múltiplos diretórios específicos (atualmente não suportado - use padrões em vez disso)
# root = ["src", "lib"]  # Esta sintaxe não é suportada

Scripts de Preload

Carregue scripts antes de executar testes usando a opção preload:

bunfig.toml

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

Isso é equivalente a usar --preload na linha de comando:

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

Casos de Uso Comuns de Preload

test-setup.ts

// Configuração global de teste
import { beforeAll, afterAll } from "bun:test";

beforeAll(() => {
  // Configurar banco de dados de teste
  setupTestDatabase();
});

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

global-mocks.ts

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

// Mock de variáveis de ambiente
process.env.NODE_ENV = "test";
process.env.API_URL = "http://localhost:3001";

// Mock de dependências externas
mock.module("./external-api", () => ({
  fetchData: mock(() => Promise.resolve({ data: "test" })),
}));

Timeouts

Timeout Padrão

Defina o timeout padrão para todos os testes:

bunfig.toml

[test]
timeout = 10000  # 10 segundos (o padrão é 5000ms)

Isso se aplica a todos os testes, a menos que seja substituído por timeouts de teste individuais:

test.ts

// Este teste usará o timeout padrão do bunfig.toml
test("usa timeout padrão", () => {
  // implementação do teste
});

// Este teste substitui o timeout padrão
test("timeout personalizado", () => {
  // implementação do teste
}, 30000); // 30 segundos

Reporters

Reporter JUnit

Configure o caminho de arquivo de saída do reporter JUnit diretamente no arquivo de configuração:

bunfig.toml

[test.reporter]
junit = "path/to/junit.xml"  # Caminho de saída para relatório XML JUnit

Isso complementa as flags de CLI --reporter=junit e --reporter-outfile:

# Uso equivalente na linha de comando
bun test --reporter=junit --reporter-outfile=./junit.xml

Múltiplos Reporters

Você pode usar múltiplos reporters simultaneamente:

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

# Abordagem via arquivo de configuração

bunfig.toml

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

[test]
# Também habilitar relatório de cobertura
coverage = true
coverageReporter = ["text", "lcov"]

Uso de Memória

Modo smol

Habilite o modo de economia de memória --smol especificamente para o executor de testes:

bunfig.toml

[test]
smol = true  # Reduzir uso de memória durante execuções de teste

Isso é equivalente a usar a flag --smol na linha de comando:

bun test --smol

O modo smol reduz o uso de memória ao:

• Usar menos memória para o heap JavaScript
• Ser mais agressivo com garbage collection
• Reduzir tamanhos de buffer onde possível

Isso é útil para:

• Ambientes de CI com memória limitada
• Grandes suítes de teste que consomem memória significativa
• Ambientes de desenvolvimento com restrições de memória

Execução de testes

concurrentTestGlob

Execute automaticamente arquivos de teste que correspondem a um padrão glob com execução de teste concorrente habilitada. Isso é útil para migrar gradualmente suítes de teste para execução concorrente ou para executar tipos específicos de testes concorrentemente.

bunfig.toml

[test]
concurrentTestGlob = "**/concurrent-*.test.ts"  # Executar arquivos que correspondem a este padrão concorrentemente

Arquivos de teste que correspondem a este padrão se comportarão como se a flag --concurrent tivesse sido passada, executando todos os testes dentro desses arquivos concorrentemente. Isso permite que você:

• Migre gradualmente sua suíte de teste para execução concorrente
• Execute testes de integração concorrentemente enquanto mantém testes unitários sequenciais
• Separe testes concorrentes rápidos de testes que exigem execução sequencial

A flag de CLI --concurrent substituirá esta configuração quando especificada, forçando todos os testes a serem executados concorrentemente, independentemente do padrão glob.

randomize

Execute testes em ordem aleatória para identificar testes com dependências ocultas:

bunfig.toml

[test]
randomize = true

seed

Especifique uma seed para ordem de teste aleatória reproduzível. Requer randomize = true:

bunfig.toml

[test]
randomize = true
seed = 2444615283

rerunEach

Re-executar cada arquivo de teste múltiplas vezes para identificar testes instáveis:

bunfig.toml

[test]
rerunEach = 3

Opções de Cobertura

Configurações Básicas de Cobertura

bunfig.toml

[test]
# Habilitar cobertura por padrão
coverage = true

# Definir reporter de cobertura
coverageReporter = ["text", "lcov"]

# Definir diretório de saída de cobertura
coverageDir = "./coverage"

Pular Arquivos de Teste da Cobertura

Exclua arquivos que correspondem a padrões de teste (por exemplo, *.test.ts) do relatório de cobertura:

bunfig.toml

[test]
coverageSkipTestFiles = true  # Excluir arquivos de teste dos relatórios de cobertura

Limites de Cobertura

O limite de cobertura pode ser especificado como um número ou como um objeto com limites específicos:

bunfig.toml

[test]
# Limite simples - aplica-se a linhas, funções e declarações
coverageThreshold = 0.8

# Limites detalhados
coverageThreshold = { lines = 0.9, functions = 0.8, statements = 0.85 }

Definir qualquer um desses habilita fail_on_low_coverage, fazendo com que a execução do teste falhe se a cobertura estiver abaixo do limite.

Exemplos de Limite

bunfig.toml

[test]
# Exigir 90% de cobertura em toda a linha
coverageThreshold = 0.9

# Requisitos diferentes para diferentes métricas
coverageThreshold = {
  lines = 0.85,      # 85% de cobertura de linha
  functions = 0.90,  # 90% de cobertura de função
  statements = 0.80  # 80% de cobertura de declaração
}

Padrões de Ignorar Caminho de Cobertura

Exclua arquivos específicos ou padrões de arquivo dos relatórios de cobertura usando padrões glob:

bunfig.toml

[test]
# Padrão único
coveragePathIgnorePatterns = "**/*.spec.ts"

# Múltiplos padrões
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js",
  "generated/**",
  "vendor/**"
]

Arquivos que correspondem a qualquer um desses padrões serão excluídos do cálculo e relatório de cobertura. Veja a documentação de cobertura para mais detalhes e exemplos.

Padrões de Ignorar Comuns

bunfig.toml

[test]
coveragePathIgnorePatterns = [
  # Arquivos de teste
  "**/*.test.ts",
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # Arquivos de configuração
  "*.config.js",
  "*.config.ts",
  "webpack.config.*",
  "vite.config.*",

  # Saída de build
  "dist/**",
  "build/**",
  ".next/**",

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

  # Fornecedor/terceiros
  "vendor/**",
  "third-party/**",

  # Utilitários que não precisam de teste
  "src/utils/constants.ts",
  "src/types/**"
]

Manipulação de Sourcemap

Internamente, o Bun transpila todos os arquivos. Isso significa que a cobertura de código também deve passar por sourcemaps antes de poder ser relatada. Expomos isso como uma flag para permitir que você opte por sair deste comportamento, mas será confuso porque durante o processo de transpilação, o Bun pode mover código e alterar nomes de variáveis. Esta opção é mais útil para depurar problemas de cobertura.

bunfig.toml

[test]
coverageIgnoreSourcemaps = true  # Não usar sourcemaps para análise de cobertura

Herança de Configurações de Instalação

O comando bun test herda configurações relevantes de rede e instalação (registry, cafile, prefer, exact, etc.) da seção [install] do bunfig.toml. Isso é importante se os testes precisarem interagir com registries privados ou exigirem comportamentos de instalação específicos acionados durante a execução do teste.

bunfig.toml

[install]
# Estas configurações são herdadas pelo bun test
registry = "https://npm.company.com/"
exact = true
prefer = "offline"

[test]
# Configuração específica de teste
coverage = true
timeout = 10000

Variáveis de Ambiente

Você também pode definir variáveis de ambiente em sua configuração que afetam o comportamento do teste:

bunfig.toml

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

[test]
coverage = true

Exemplo de Configuração Completa

Aqui está um exemplo abrangente mostrando todas as opções de configuração de teste disponíveis:

bunfig.toml

[install]
# Configurações de instalação herdadas pelos testes
registry = "https://registry.npmjs.org/"
exact = true

[env]
# Variáveis de ambiente para testes
NODE_ENV = "test"
DATABASE_URL = "postgresql://localhost:5432/test_db"
API_URL = "http://localhost:3001"
LOG_LEVEL = "error"

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

# Configurações de execução
timeout = 10000
smol = true

# Configuração 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/**"
]

# Configurações avançadas de cobertura
coverageIgnoreSourcemaps = false

# Configuração do reporter
[test.reporter]
junit = "./reports/junit.xml"

Comportamento de Substituição via CLI

Opções de linha de comando sempre substituem configurações de arquivo de configuração:

bunfig.toml

[test]
timeout = 5000
coverage = false

# Estas flags de CLI substituem o arquivo de configuração
bun test --timeout 10000 --coverage
# timeout será 10000ms e cobertura será habilitada

Configuração Condicional

Você pode usar configurações diferentes para ambientes diferentes:

bunfig.toml

[test]
# Configuração padrão de teste
coverage = false
timeout = 5000

# Substituição para ambiente CI
[test.ci]
coverage = true
coverageThreshold = 0.8
timeout = 30000

Então no CI:

# Usar configurações específicas de CI
bun test --config=ci

Validação e Solução de Problemas

Configuração Inválida

O Bun avisará sobre opções de configuração inválidas:

bunfig.toml

[test]
invalidOption = true  # Isso gerará um aviso

Problemas Comuns de Configuração

1. Resolução de Caminho: Caminhos relativos na configuração são resolvidos em relação ao local do arquivo de configuração
2. Correspondência de Padrão: Padrões glob usam sintaxe glob padrão
3. Incompatibilidades de Tipo: Certifique-se de que valores numéricos não estejam entre aspas, a menos que devam ser strings

bunfig.toml

[test]
# Correto
timeout = 10000

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

Depurando Configuração

Para ver qual configuração está sendo usada:

# Mostrar configuração efetiva
bun test --dry-run

# Saída detalhada para ver carregamento de configuração
bun test --verbose