O executor de testes do Bun agora oferece suporte a relatórios de cobertura de código integrados. Isso facilita ver quanto da base de código é coberto por testes e encontrar áreas que atualmente não estão bem testadas.

Habilitando a Cobertura

bun:test oferece suporte para ver quais linhas de código são cobertas por testes. Para usar este recurso, passe --coverage para a CLI. Ele imprimirá um relatório de cobertura no console:

bun test --coverage

-------------|---------|---------|-------------------
Arquivo      | % Funcs | % Lines | Linhas não cobertas
-------------|---------|---------|-------------------
Todos arquivos|  38.89 |   42.11 |
 index-0.ts  |   33.33 |   36.84 | 10-15,19-24
 index-1.ts  |   33.33 |   36.84 | 10-15,19-24
 index-10.ts |   33.33 |   36.84 | 10-15,19-24
 index-2.ts  |   33.33 |   36.84 | 10-15,19-24
 index-3.ts  |   33.33 |   36.84 | 10-15,19-24
 index-4.ts  |   33.33 |   36.84 | 10-15,19-24
 index-5.ts  |   33.33 |   36.84 | 10-15,19-24
 index-6.ts  |   33.33 |   36.84 | 10-15,19-24
 index-7.ts  |   33.33 |   36.84 | 10-15,19-24
 index-8.ts  |   33.33 |   36.84 | 10-15,19-24
 index-9.ts  |   33.33 |   36.84 | 10-15,19-24
 index.ts    |  100.00 |  100.00 |
-------------|---------|---------|-------------------

Habilitar por Padrão

Para sempre habilitar o relatório de cobertura por padrão, adicione a seguinte linha ao seu bunfig.toml:

bunfig.toml

[test]
# Sempre habilitar cobertura
coverage = true

Por padrão, os relatórios de cobertura incluirão arquivos de teste e excluirão sourcemaps. Isso geralmente é o que você deseja, mas pode ser configurado de outra forma no bunfig.toml.

bunfig.toml

[test]
coverageSkipTestFiles = true  # padrão false

Limites de Cobertura

É possível especificar um limite de cobertura no bunfig.toml. Se sua suíte de testes não atingir ou exceder este limite, bun test sairá com um código de saída diferente de zero para indicar a falha.

Limite Simples

bunfig.toml

[test]
# Para exigir 90% de cobertura em nível de linha e função
coverageThreshold = 0.9

Limites Detalhados

bunfig.toml

[test]
# Para definir limites diferentes para linhas e funções
coverageThreshold = { lines = 0.9, functions = 0.9, statements = 0.9 }

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

Relatórios de Cobertura

Por padrão, os relatórios de cobertura serão impressos no console.

Para relatórios de cobertura persistentes em ambientes de CI e para outras ferramentas, você pode passar a opção de CLI --coverage-reporter=lcov ou a opção coverageReporter no bunfig.toml.

bunfig.toml

[test]
coverageReporter = ["text", "lcov"]  # padrão ["text"]
coverageDir = "path/to/somewhere"    # padrão "coverage"

Relatórios Disponíveis

Relatório	Descrição
text	Imprime um resumo textual da cobertura no console
lcov	Salva cobertura no formato lcov

Relatório de Cobertura LCOV

Para gerar um relatório lcov, você pode usar o relatório lcov. Isso gerará um arquivo lcov.info no diretório de cobertura.

bunfig.toml

[test]
coverageReporter = "lcov"

# Ou via CLI
bun test --coverage --coverage-reporter=lcov

O formato LCOV é amplamente suportado por várias ferramentas e serviços:

• Editores de código: Extensões do VS Code podem mostrar cobertura inline
• Serviços de CI/CD: GitHub Actions, GitLab CI, CircleCI
• Serviços de cobertura: Codecov, Coveralls
• IDEs: WebStorm, IntelliJ IDEA

Usando LCOV com GitHub Actions

.github/workflows/test.yml

name: Teste com Cobertura
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: oven-sh/setup-bun@v2
      - run: bun install
      - run: bun test --coverage --coverage-reporter=lcov
      - name: Upload cobertura para Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

Excluindo Arquivos da Cobertura

Pular Arquivos de Teste

Por padrão, os próprios arquivos de teste são incluídos nos relatórios de cobertura. Você pode excluí-los com:

bunfig.toml

[test]
coverageSkipTestFiles = true  # padrão false

Isso excluirá arquivos que correspondem aos padrões de teste (por exemplo, *.test.ts, *.spec.js) do relatório de cobertura.

Ignorar Caminhos e Padrões Específicos

Você pode excluir arquivos específicos ou padrões de arquivo dos relatórios de cobertura usando coveragePathIgnorePatterns:

bunfig.toml

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

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

Esta opção aceita padrões glob e funciona de forma semelhante aos padrões de ignorar collectCoverageFrom do Jest. Arquivos que correspondem a qualquer um desses padrões serão excluídos do cálculo e relatório de cobertura nas saídas de texto e LCOV.

Casos de Uso Comuns

bunfig.toml

[test]
coveragePathIgnorePatterns = [
  # Excluir arquivos utilitários
  "src/utils/**",

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

  # Excluir padrões de teste específicos
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # Excluir artefatos de build
  "dist/**",
  "build/**",

  # Excluir arquivos gerados
  "src/generated/**",
  "**/*.generated.ts",

  # Excluir código de fornecedores/terceiros
  "vendor/**",
  "third-party/**"
]

Sourcemaps

Internamente, o Bun transpila todos os arquivos por padrão, então o Bun gera automaticamente um source map interno que mapeia linhas do seu código fonte original para a representação interna do Bun. Se por algum motivo você quiser desabilitar isso, defina test.coverageIgnoreSourcemaps como true; isso raramente será desejável fora de casos de uso avançados.

bunfig.toml

[test]
coverageIgnoreSourcemaps = true  # padrão false

Padrões de Cobertura

Por padrão, os relatórios de cobertura:

• Excluem diretórios node_modules
• Excluem arquivos carregados via loaders não-JS/TS (por exemplo, .css, .txt) a menos que um loader JS personalizado seja especificado
• Incluem os próprios arquivos de teste (pode ser desabilitado com coverageSkipTestFiles = true)
• Podem excluir arquivos adicionais com coveragePathIgnorePatterns

Configuração Avançada

Diretório de Cobertura Personalizado

bunfig.toml

[test]
coverageDir = "coverage-reports"  # padrão "coverage"

Múltiplos Relatórios

bunfig.toml

[test]
coverageReporter = ["text", "lcov"]

Cobertura com Padrões de Teste Específicos

# Executar cobertura apenas em arquivos de teste específicos
bun test --coverage src/components/*.test.ts

# Executar cobertura com padrão de nome
bun test --coverage --test-name-pattern="API"

Integração CI/CD

Exemplo GitHub Actions

.github/workflows/coverage.yml

name: Relatório de Cobertura
on: [push, pull_request]

jobs:
  coverage:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2

      - name: Instalar dependências
        run: bun install

      - name: Executar testes com cobertura
        run: bun test --coverage --coverage-reporter=lcov

      - name: Upload para Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info
          fail_ci_if_error: true

Exemplo GitLab CI

.gitlab-ci.yml

test:coverage:
  stage: test
  script:
    - bun install
    - bun test --coverage --coverage-reporter=lcov
  coverage: '/Lines\s*:\s*(\d+.\d+)%/'
  artifacts:
    reports:
      coverage_report:
        coverage_format: cobertura
        path: coverage/lcov.info

Interpretando Relatórios de Cobertura

Explicação da Saída de Texto

-------------|---------|---------|-------------------
Arquivo      | % Funcs | % Lines | Linhas não cobertas
-------------|---------|---------|-------------------
Todos arquivos|  85.71 |   90.48 |
 src/        |   85.71 |   90.48 |
  utils.ts   |  100.00 |  100.00 |
  api.ts     |   75.00 |   85.71 | 15-18,25
  main.ts    |   80.00 |   88.89 | 42,50-52
-------------|---------|---------|-------------------

• % Funcs: Porcentagem de funções que foram chamadas durante os testes
• % Lines: Porcentagem de linhas executáveis que foram executadas durante os testes
• Uncovered Line #s: Números de linha específicos que não foram executados

O Que Buscar

• 80%+ de cobertura geral: Geralmente considerado bom
• 90%+ caminhos críticos: Lógica de negócios importante deve ser bem testada
• 100% funções utilitárias: Funções puras e utilitários são fáceis de testar completamente
• Menor cobertura para componentes de UI: Frequentemente aceitável, pois podem exigir testes de integração

Melhores Práticas

Foque na Qualidade, Não Apenas na Quantidade

test.ts

// Bom: Testar funcionalidade real
test("calculateTax deve lidar com diferentes alíquotas de imposto", () => {
  expect(calculateTax(100, 0.08)).toBe(8);
  expect(calculateTax(100, 0.1)).toBe(10);
  expect(calculateTax(0, 0.08)).toBe(0);
});

// Evite: Apenas atingir linhas para cobertura
test("calculateTax existe", () => {
  calculateTax(100, 0.08); // Sem asserções!
});

Teste Casos Extremos

test.ts

test("validação de entrada do usuário", () => {
  // Testar caso normal
  expect(validateEmail("user@example.com")).toBe(true);

  // Testar casos extremos que melhoram a cobertura significativamente
  expect(validateEmail("")).toBe(false);
  expect(validateEmail("invalid")).toBe(false);
  expect(validateEmail(null)).toBe(false);
});

Use Cobertura para Encontrar Testes Faltantes

# Executar cobertura para identificar código não testado
bun test --coverage

# Olhar arquivos específicos que precisam de atenção
bun test --coverage src/critical-module.ts

Combine com Outras Métricas de Qualidade

Cobertura é apenas uma métrica. Considere também:

• Qualidade da revisão de código
• Cobertura de testes de integração
• Testes de tratamento de erro
• Testes de desempenho
• Segurança de tipo

Solução de Problemas

Cobertura Não Aparecendo para Alguns Arquivos

Se arquivos não estiverem aparecendo nos relatórios de cobertura, eles podem não estar sendo importados pelos seus testes. A cobertura apenas rastreia arquivos que são realmente carregados.

test.ts

// Certifique-se de importar os módulos que deseja testar
import { myFunction } from "../src/my-module";

test("minha função funciona", () => {
  expect(myFunction()).toBeDefined();
});

Relatórios de Cobertura Falsos

Se você vir relatórios de cobertura que não correspondem às suas expectativas:

1. Verifique se os source maps estão funcionando corretamente
2. Verifique os padrões de arquivo em coveragePathIgnorePatterns
3. Certifique-se de que os arquivos de teste estão realmente importando o código a ser testado

Problemas de Desempenho com Bases de Código Grandes

Para projetos grandes, a coleta de cobertura pode desacelerar os testes:

bunfig.toml

[test]
# Excluir diretórios grandes que você não precisa de cobertura
coveragePathIgnorePatterns = [
  "node_modules/**",
  "vendor/**",
  "generated/**"
]

Considere executar a cobertura apenas no CI ou em branches específicos em vez de cada execução de teste durante o desenvolvimento.