code-coverage.mdx

title	description
Code coverage	Learn how to use Bun's built-in code coverage reporting to track test coverage and find untested areas in your codebase

Bun's test runner now supports built-in code coverage reporting. This makes it easy to see how much of the codebase is covered by tests, and find areas that are not currently well-tested.

Enabling Coverage

bun:test supports seeing which lines of code are covered by tests. To use this feature, pass --coverage to the CLI. It will print out a coverage report to the console:

bun test --coverage

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   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 |
-------------|---------|---------|-------------------

Enable by Default

To always enable coverage reporting by default, add the following line to your bunfig.toml:

[test]
# Always enable coverage
coverage = true

By default coverage reports will include test files and exclude sourcemaps. This is usually what you want, but it can be configured otherwise in bunfig.toml.

[test]
coverageSkipTestFiles = true  # default false

Coverage Thresholds

It is possible to specify a coverage threshold in bunfig.toml. If your test suite does not meet or exceed this threshold, bun test will exit with a non-zero exit code to indicate the failure.

Simple Threshold

[test]
# To require 90% line-level and function-level coverage
coverageThreshold = 0.9

Detailed Thresholds

[test]
# To set different thresholds for lines and functions
coverageThreshold = { lines = 0.9, functions = 0.9, statements = 0.9 }

Setting any of these thresholds enables fail_on_low_coverage, causing the test run to fail if coverage is below the threshold.

Coverage Reporters

By default, coverage reports will be printed to the console.

For persistent code coverage reports in CI environments and for other tools, you can pass a --coverage-reporter=lcov CLI option or coverageReporter option in bunfig.toml.

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

Available Reporters

Reporter	Description
text	Prints a text summary of the coverage to the console
lcov	Save coverage in lcov format

LCOV Coverage Reporter

To generate an lcov report, you can use the lcov reporter. This will generate an lcov.info file in the coverage directory.

[test]
coverageReporter = "lcov"

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

The LCOV format is widely supported by various tools and services:

• Code editors: VS Code extensions can show coverage inline
• CI/CD services: GitHub Actions, GitLab CI, CircleCI
• Coverage services: Codecov, Coveralls
• IDEs: WebStorm, IntelliJ IDEA

Using LCOV with GitHub Actions

name: Test with Coverage
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 coverage to Codecov
        uses: codecov/codecov-action@v3
        with:
          file: ./coverage/lcov.info

Including Uncovered Files

By default, coverage reports only include files that are actually imported by your tests. To also show files that aren't imported by any test (with 0% coverage), use the collectCoverageFrom option — similar to Jest's collectCoverageFrom configuration.

Configuration

[test]
collectCoverageFrom = [
  "src/**/*.ts",
  "src/**/*.tsx",
  "!src/**/*.d.ts"
]

This accepts glob patterns specifying which source files should be included in coverage reports, even if no test imports them. Files matching these patterns that are not loaded during tests will appear in the coverage report with 0% coverage for both functions and lines.

Example Output

bun test --coverage

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   50.00 |   60.00 |
 src/
  tested.ts  |  100.00 |  100.00 |
  untested.ts|    0.00 |    0.00 | Not imported by tests
-------------|---------|---------|-------------------

Files that are not imported by any test will show "Not imported by tests" in the uncovered lines column, making it easy to identify source files that have no test coverage at all.

Common Patterns

[test]
# Include all TypeScript source files
collectCoverageFrom = ["src/**/*.ts", "src/**/*.tsx"]

# Include specific directories
collectCoverageFrom = ["src/components/**/*.ts", "src/utils/**/*.ts"]

# Single pattern
collectCoverageFrom = "src/**/*.ts"

The collectCoverageFrom option works together with other coverage options:

• Files matching coveragePathIgnorePatterns will still be excluded
• If coverageSkipTestFiles is enabled, test files will be excluded
• node_modules and hidden directories (starting with .) are always excluded

Excluding Files from Coverage

Skip Test Files

By default, test files themselves are included in coverage reports. You can exclude them with:

[test]
coverageSkipTestFiles = true  # default false

This will exclude files matching test patterns (e.g., *.test.ts, *.spec.js) from the coverage report.

Ignore Specific Paths and Patterns

You can exclude specific files or file patterns from coverage reports using coveragePathIgnorePatterns:

[test]
# Single pattern
coveragePathIgnorePatterns = "**/*.spec.ts"

# Multiple patterns
coveragePathIgnorePatterns = [
  "**/*.spec.ts",
  "**/*.test.ts",
  "src/utils/**",
  "*.config.js"
]

This option accepts glob patterns and works similarly to Jest's collectCoverageFrom ignore patterns. Files matching any of these patterns will be excluded from coverage calculation and reporting in both text and LCOV outputs.

Common Use Cases

[test]
coveragePathIgnorePatterns = [
  # Exclude utility files
  "src/utils/**",

  # Exclude configuration files
  "*.config.js",
  "webpack.config.ts",
  "vite.config.ts",

  # Exclude specific test patterns
  "**/*.spec.ts",
  "**/*.e2e.ts",

  # Exclude build artifacts
  "dist/**",
  "build/**",

  # Exclude generated files
  "src/generated/**",
  "**/*.generated.ts",

  # Exclude vendor/third-party code
  "vendor/**",
  "third-party/**"
]

Sourcemaps

Internally, Bun transpiles all files by default, so Bun automatically generates an internal source map that maps lines of your original source code onto Bun's internal representation. If for any reason you want to disable this, set test.coverageIgnoreSourcemaps to true; this will rarely be desirable outside of advanced use cases.

[test]
coverageIgnoreSourcemaps = true  # default false

When using this option, you probably want to stick a `// @bun` comment at the top of the source file to opt out of the transpilation process.

Coverage Defaults

By default, coverage reports:

• Exclude node_modules directories
• Exclude files loaded via non-JS/TS loaders (e.g., .css, .txt) unless a custom JS loader is specified
• Include test files themselves (can be disabled with coverageSkipTestFiles = true)
• Can exclude additional files with coveragePathIgnorePatterns

Advanced Configuration

Custom Coverage Directory

[test]
coverageDir = "coverage-reports"  # default "coverage"

Multiple Reporters

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

Coverage with Specific Test Patterns

# Run coverage only on specific test files
bun test --coverage src/components/*.test.ts

# Run coverage with name pattern
bun test --coverage --test-name-pattern="API"

CI/CD Integration

GitHub Actions Example

name: Coverage Report
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: Install dependencies
        run: bun install

      - name: Run tests with coverage
        run: bun test --coverage --coverage-reporter=lcov

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

GitLab CI Example

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

Interpreting Coverage Reports

Text Output Explanation

-------------|---------|---------|-------------------
File         | % Funcs | % Lines | Uncovered Line #s
-------------|---------|---------|-------------------
All files    |   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: Percentage of functions that were called during tests
• % Lines: Percentage of executable lines that were run during tests
• Uncovered Line #s: Specific line numbers that were not executed

What to Aim For

• 80%+ overall coverage: Generally considered good
• 90%+ critical paths: Important business logic should be well-tested
• 100% utility functions: Pure functions and utilities are easy to test completely
• Lower coverage for UI components: Often acceptable as they may require integration tests

Best Practices

Focus on Quality, Not Just Quantity

// Good: Test actual functionality
test("calculateTax should handle different tax rates", () => {
  expect(calculateTax(100, 0.08)).toBe(8);
  expect(calculateTax(100, 0.1)).toBe(10);
  expect(calculateTax(0, 0.08)).toBe(0);
});

// Avoid: Just hitting lines for coverage
test("calculateTax exists", () => {
  calculateTax(100, 0.08); // No assertions!
});

Test Edge Cases

test("user input validation", () => {
  // Test normal case
  expect(validateEmail("user@example.com")).toBe(true);

  // Test edge cases that improve coverage meaningfully
  expect(validateEmail("")).toBe(false);
  expect(validateEmail("invalid")).toBe(false);
  expect(validateEmail(null)).toBe(false);
});

Use Coverage to Find Missing Tests

# Run coverage to identify untested code
bun test --coverage

# Look at specific files that need attention
bun test --coverage src/critical-module.ts

Combine with Other Quality Metrics

Coverage is just one metric. Also consider:

• Code review quality
• Integration test coverage
• Error handling tests
• Performance tests
• Type safety

Troubleshooting

Coverage Not Showing for Some Files

If files aren't appearing in coverage reports, they might not be imported by your tests. You have two options:

1. Use collectCoverageFrom to automatically include all source files in the coverage report, even if they aren't imported by tests:

[test]
collectCoverageFrom = ["src/**/*.ts"]

2. Import the modules in your test files:

// Make sure to import the modules you want to test
import { myFunction } from "../src/my-module";

test("my function works", () => {
  expect(myFunction()).toBeDefined();
});

False Coverage Reports

If you see coverage reports that don't match your expectations:

1. Check if source maps are working correctly
2. Verify file patterns in coveragePathIgnorePatterns
3. Ensure test files are actually importing the code to test

Performance Issues with Large Codebases

For large projects, coverage collection can slow down tests:

[test]
# Exclude large directories you don't need coverage for
coveragePathIgnorePatterns = [
  "node_modules/**",
  "vendor/**",
  "generated/**"
]

Consider running coverage only on CI or specific branches rather than every test run during development.