Dart Test Coverage

Dart Test Coverage

Guidelines for running and interpreting test coverage in Dart packages.

When to use this skill

• When asked to "check test coverage" or "improve coverage".
• When you need to identify which parts of a library are untested.

When NOT to use (Abstention Guardrails)

Do NOT collect or demand test coverage for:

• Generated Code: Code generated by builders (*.g.dart, *.freezed.dart, protobufs).
• Platform-Specific FFI / OS Entrypoints: Low-level platform bindings or entrypoints that require specific physical hardware or OS services not available in the execution environment.
• Example Applications & Tool Scripts: Standalone sample code under example/ or developer maintenance scripts under tool/ unless the package explicitly mandates 100% repository-wide coverage.
• Failing Test Suites: If existing tests are failing under dart test, fix the broken tests first before collecting or reporting coverage.

Discovery

To find areas lacking test coverage:

Run Coverage Analysis

Follow the workflow to generate and interpret coverage data:

1. Run Tests with Coverage: dart test --coverage=.dart_tool/coverage
2. Interpret Results: Use the script or format_coverage as described in the Interpreting Results section to identify specific files and missed lines.

How to use this skill (The Workflow)

1. Ensure tests pass by running dart test.
2. Collect coverage by running dart test --coverage=.dart_tool/coverage.
3. Interpret the results using the provided script or standard tools.
4. Add tests to cover missed lines.

Running Coverage

Run the following command to collect coverage in JSON format:

bashCopy code
dart test --coverage=.dart_tool/coverage

[!NOTE] We use .dart_tool/coverage as the output directory because .dart_tool is typically already ignored in .gitignore files.

[!TIP] For projects with complex conditional logic, you can pass the --branch-coverage flag to dart test to collect branch-level coverage.

Interpreting Results

Option 1: Use the custom interpreter script

This repository includes a zero-dependency script that parses the raw JSON output and provides a summary of covered percentage and missed lines.

Run it from the project root (adjust path to script as needed):

bashCopy code
dart run skills/dart-test-coverage/scripts/interpret_coverage.dart .dart_tool/coverage <package_name>

Replace <package_name> with the name from pubspec.yaml.

Example Output:

Copy code
package:my_pkg/src/file.dart: 50.0% (2/4 lines)
  Missed lines: 3, 4

Option 2: Use package:coverage

If package:test is installed, package:coverage is likely available as a transitive dependency. You can use its format_coverage tool.

To get a human-readable "pretty print" of the coverage:

bashCopy code
dart run coverage:format_coverage --in=.dart_tool/coverage --out=stdout --pretty-print --report-on=lib

This will output the file content with hit counts on the left (e.g., 0| for missed lines).

Best Practices for Reporting Results

When presenting coverage results to the user, follow these guidelines:

1. State the high-level percentage first to give immediate context.
2. Identify specific files and missed lines clearly.
3. Translate line numbers to code: Don't just say "lines 3-6 are missed". Look at the source file and tell the user which functions or blocks are untested (e.g., "The divide function is missing coverage").
4. Propose concrete fixes: Provide example test code that the user can immediately apply to cover the missed lines.
5. Use tables for multi-file summaries: When reporting on multiple files, use a markdown table with columns for File, Coverage %, and Missed Lines to make the summary easy to scan.

Constraints

• ALWAYS verify that tests pass before collecting coverage.
• DO NOT commit the .dart_tool/coverage directory.
• Focus coverage improvements on lib/ files, not test/ or generated files.