Generating Code Coverage Reports in Dart

WHY IT EXISTS To answer the question, "How much of my code is actually being tested?" Without coverage reports, developers can't easily identify untested logic, leading to blind spots where bugs can hide. It provides a quantitative, automated way to measure test reach.

THE MENTAL MODEL Think of code coverage as shining a UV light on your codebase after your tests have run. The lines that glow are the ones your tests touched. The dark spots are areas your tests missed entirely. It shows you where your tests went, but not how well they checked things when they were there.

HOW IT WORKS The process has two stages. First, you run your tests with specific Dart VM flags (--enable-vm-service) that open a service port. The collect_coverage tool connects to this port, inspects which lines of code were executed, and saves this raw data to a coverage.json file. Second, the format_coverage tool reads this JSON and converts it into a standard format like LCOV (lcov.info). The coverage package provides a convenient script, test_with_coverage, that automates this entire sequence.

WHEN TO USE IT Use coverage reports in your CI/CD pipeline to enforce a minimum testing threshold and prevent merging untested code. Locally, use an IDE extension to visualize which lines are missing coverage as you code. It is also effective for identifying dead or unreachable code that could be removed.

WHEN NOT TO USE IT Do not use coverage percentage as the sole metric for code quality or developer performance. A test that runs a line but has no expect assertion still increases coverage but provides zero validation. Chasing 100% on trivial code (like simple data classes) is often a waste of effort. The default setup may also require manual configuration for complex monorepo workspaces.

ONE CANONICAL EXAMPLE The simplest way to generate a report is to run dart pub global run coverage:test_with_coverage from your project's root. This command automatically runs all tests, collects data, and generates two files in a new coverage/ directory: coverage.json (the raw data) and lcov.info (the formatted report for other tools to consume).