coverage

19 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Enable coverage reporting with --coverage flag

Pass --coverage to the bun test command to print a coverage report to the console showing file coverage percentages and uncovered line numbers.

Enable coverage by default in bunfig.toml

Add [test] coverage = true to bunfig.toml to enable coverage reporting by default for all test runs.

Coverage report columns and meaning

The coverage report displays four columns: File (the filename), % Funcs (percentage of functions called during tests), % Lines (percentage of executable lines run during tests), and Uncovered Line #s (line numbers that were never executed).

Set simple coverage threshold in bunfig.toml

Add [test] coverageThreshold = 0.9 to require 90% line-level and function-level coverage. If coverage falls below this threshold, bun test exits with a non-zero exit code.

Set detailed coverage thresholds by type

In bunfig.toml, use [test] coverageThreshold = { lines = 0.9, functions = 0.9, statements = 0.9 } to set different thresholds for lines, functions, and statements separately. Setting any threshold enables fail_on_low_coverage.

Coverage reporters configuration

Configure coverage reporters in bunfig.toml with [test] coverageReporter = ["text", "lcov"] (default is ["text"]). Also set coverageDir = "path/to/somewhere" (default is "coverage"). Pass --coverage-reporter=lcov on the command line as an alternative.

Available coverage reporters

Bun supports two coverage reporters: text (prints a text summary of coverage to the console) and lcov (saves coverage in lcov format).

LCOV reporter output file

The lcov reporter writes an lcov.info file to the coverage directory. This file can be used by code editors (VS Code extensions), CI/CD services (GitHub Actions, GitLab CI, CircleCI), coverage services (Codecov, Coveralls), and IDEs (WebStorm, IntelliJ IDEA).

Exclude test files from coverage by default

By default, coverage reports exclude test files. To include test files in coverage reports, set [test] coverageSkipTestFiles = false in bunfig.toml (default is true). When true, files matching test patterns like *.test.ts and *.spec.js are excluded.

Exclude specific paths from coverage with coveragePathIgnorePatterns

In bunfig.toml, use [test] coveragePathIgnorePatterns to exclude specific files or patterns from coverage reports. Accepts single pattern as string or multiple patterns as array. Supports glob patterns like Jest's collectCoverageFrom. Files matching any pattern are excluded from both text and LCOV output.

Disable sourcemaps in coverage

Bun transpiles all files by default and generates internal source maps mapping original source code to Bun's internal representation. Set [test] coverageIgnoreSourcemaps = true to disable this (default false). This is rarely needed outside advanced use cases. When disabled, consider adding // @bun comment at the top of source files to opt out of transpilation.

Coverage defaults

By default, coverage reports exclude node_modules directories, exclude files loaded with non-JS/TS loaders (like .css, .txt) unless a custom JS loader is specified, exclude test files themselves (configurable with coverageSkipTestFiles), and can exclude additional files with coveragePathIgnorePatterns.

Run coverage on specific test files

Use bun test --coverage src/components/*.test.ts to run coverage only on specific test files. Combine with bun test --coverage --test-name-pattern="API" to run coverage with a name pattern.

GitHub Actions integration for coverage

In a GitHub Actions workflow, use oven-sh/setup-bun@v2 to setup Bun, run bun test --coverage --coverage-reporter=lcov, then use codecov/codecov-action@v3 with file: ./coverage/lcov.info to upload coverage results.

Coverage quality recommendations

Aim for 80%+ overall coverage as generally good. Ensure 90%+ coverage for critical paths and important business logic. Target 100% for utility functions and pure functions which are easy to test completely. Lower coverage for UI components is often acceptable as they may require integration tests.

Coverage best practice: test functionality not just lines

Write tests that verify actual functionality with assertions rather than tests that just execute code to hit line coverage. For example, test calculateTax with different tax rates and edge cases with assertions, not just call the function without verifying results.

Test edge cases to improve meaningful coverage

Coverage should focus on quality. Test edge cases like empty inputs, null values, and invalid formats to improve coverage meaningfully. For example, when testing email validation, test normal cases, empty strings, invalid formats, and null inputs.

Files not imported are not tracked in coverage

If files aren't appearing in coverage reports, check that your tests import them. Coverage only tracks files that are loaded during test execution.

Optimize coverage performance for large codebases

For large projects, coverage collection can slow down tests. Exclude large directories using coveragePathIgnorePatterns (like node_modules, vendor, generated). Consider running coverage only on CI or specific branches rather than every test run during development.

Give your agent this brain