coverage_lens 1.4.0

Static HTML coverage reports for Dart and Flutter LCOV output with compact source previews and threshold checks.

Coverage Lens

Coverage Lens generates compact static HTML coverage reports from Dart and Flutter LCOV output. It is designed for quick local review and CI artifacts: open the report, expand the directories that need attention, and inspect source lines without leaving the browser.

Coverage Lens reads the LCOV file as the source of truth. It does not run tests, instrument code, or infer which test covered a line.

Features

• Static report folder with a lightweight index.html.
• Directory tree with aggregate line and branch coverage.
• Lazy-loaded file previews with LCOV hit counts and branch markers.
• Lists for files below threshold and files with missing branch coverage.
• Include and exclude globs for generated files.
• Local live server for previewing reports without writing HTML assets.
• Optional one-page PDF summary with aggregate statistics.
• CI-friendly threshold exit codes.

Install

dart pub global activate coverage_lens

You can also add it to a project:

dart pub add --dev coverage_lens

Generate Coverage

For Flutter projects:

flutter test --coverage

If your Flutter/Dart toolchain supports branch coverage and emits BRDA records, include branch coverage when generating the LCOV file:

flutter test --coverage --branch-coverage

For Dart packages, generate an LCOV file with your preferred coverage workflow, for example package:coverage.

Generate The Report

After an LCOV file exists, run:

dart run coverage_lens:coverage_lens report \
  --lcov coverage/lcov.info \
  --source . \
  --out build/coverage_lens

You can pass --lcov more than once. This is useful when a Flutter app cannot run tests as one workspace and each package writes its own LCOV file:

dart run coverage_lens:coverage_lens report \
  --lcov coverage/lcov.info \
  --lcov modules/**/coverage/lcov.info \
  --lcov packages/**/coverage/lcov.info \
  --source . \
  --out build/coverage_lens

Coverage Lens merges matching SF: records before building the report. When an LCOV file is inside a package coverage folder, for example modules/core/coverage/lcov.info, package-relative sources such as SF:lib/src/file.dart are shown as modules/core/lib/src/file.dart. Glob entries that do not match any files are ignored as long as at least one LCOV file is found.

Open build/coverage_lens/index.html in a browser.

The report output is a folder. Keep index.html, files/, and assets/ together when sharing or archiving the report. Source previews are stored in files/ so the main index.html stays small even for large projects.

For a lighter report without expandable source previews, add --no-source-preview:

dart run coverage_lens:coverage_lens report \
  --lcov coverage/lcov.info \
  --source . \
  --out build/coverage_lens \
  --no-source-preview

This keeps the summary cards, insights, warnings, attention list, and coverage tree, but does not generate the files/ preview assets.

To focus a report on files changed in a pull request, pass a Git base revision:

dart run coverage_lens:coverage_lens report \
  --lcov coverage/lcov.info \
  --source . \
  --out build/coverage_lens_pr \
  --changed-from origin/main

Coverage Lens runs git diff --name-only <from>...<to> inside sourceRoot and keeps only LCOV records whose source paths are in that changed-file set. The head revision defaults to HEAD; use --changed-to when CI needs an explicit head:

dart run coverage_lens:coverage_lens report \
  --changed-from origin/main \
  --changed-to HEAD

To also write a one-page PDF with aggregate statistics only, add --summary-pdf:

dart run coverage_lens:coverage_lens report \
  --lcov coverage/lcov.info \
  --source . \
  --out build/coverage_lens \
  --summary-pdf \
  --summary-icon assets/app_icon.png \
  --project-name "Example App"

The PDF is written to build/coverage_lens/summary.pdf by default. Use --summary-pdf-out path/to/summary.pdf to choose a different file. Use --summary-icon path/to/icon.png or summaryIcon in the config to place a small project icon in the PDF header. Use --project-name or projectName to show the application name next to that icon. PNG and JPEG files are supported.

If installed globally, use:

coverage_lens report

Live Local Preview

For local review, run a live server instead of writing index.html, files/, and assets/ to disk:

dart run coverage_lens:coverage_lens serve \
  --lcov coverage/lcov.info \
  --lcov modules/**/coverage/lcov.info \
  --source .

By default the report is available at http://127.0.0.1:8787/. Use --host and --port to change the bind address:

dart run coverage_lens:coverage_lens serve --port 9000

The live server still uses the LCOV file as the source of truth, but serves the main report, source previews, and CSS from memory. This keeps local inspection fast without creating a files/ preview folder.

Configuration

Coverage Lens reads coverage_lens.yaml from the current directory by default. Command-line options override values from the config file.

sourceRoot: .
lcovPaths:
  - coverage/lcov.info
  - modules/**/coverage/lcov.info
  - packages/**/coverage/lcov.info
outputDir: build/coverage_lens
summaryIcon: assets/app_icon.png
projectName: Example App
sourcePreview: true
# changedFrom: origin/main
# changedTo: HEAD
thresholds:
  line: 80
  branch: 70
include:
  - lib/**
  - modules/*/lib/**
exclude:
  - "**/*.g.dart"
  - "**/*.freezed.dart"
  - "**/*.config.dart"
  - "**/generated/**"

Thresholds

dart run coverage_lens:coverage_lens report \
  --fail-under-lines 80 \
  --fail-under-branches 70

Exit code 2 means the report was generated but the configured line coverage or branch coverage threshold failed.

LCOV Semantics

Coverage Lens displays line and branch positions exactly as they are reported in LCOV:

• DA:<line>,<count> marks an instrumented line and its execution count.
• BRDA:<line>,<block>,<branch>,<taken> marks a branch record on that line.

Dart and Flutter coverage can attach counters to lines such as annotations or method declarations. Coverage Lens keeps those line numbers intact so the report matches the LCOV file it was generated from.

Ignoring Generated Files

Use exclude patterns to keep generated code out of the report:

exclude:
  - "**/*.g.dart"
  - "**/*.freezed.dart"
  - "**/generated/**"

Excluded files are not counted in coverage totals.