git:20260912.57dc63f to git:20260913.6c39005

---

name: dart-test-coverage

description: |-

Understand and improve test coverage in a Dart package.

Helps agents run coverage, interpret results, and identify missed lines.

key_features:

- LCOV report collection

- Missed line identification

- Coverage analysis & improvement

---

# 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:

```bash

dart test --coverage=.dart_tool/coverage

```

> `--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):

```bash

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:

```

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:

```bash

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,

## 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.