Coverde

A CLI for basic coverage trace files manipulation.

---

Index

• Installing
• Features
• Usage with melos
• CI integration for coverage checks

---

Installing

You can make coverde globally available by executing the following command:

$ dart pub global activate coverde

NOTE: To run coverde directly from the terminal, add the system cache bin directory to your PATH environment variable.

---

Features

• Optimize tests by gathering them.
• Check the coverage value (%) computed from a trace file.
• Filter a coverage trace file.
• Generate the coverage report from a trace file.
• Remove a set of files and folders.
• Compute the coverage value (%) of an info file.

coverde optimize-tests

Optimize tests by gathering them.

Arguments

Single-options

• --include

  The glob pattern for the tests files to include.
  Default value: test/**_test.dart

• --exclude

  The glob pattern for the tests files to exclude.

• --output

  The path to the optimized tests file.
  Default value: test/optimized_test.dart

Flags

• --flutter-goldens

  Whether to use golden tests in case of a Flutter package.
  Default value: Enabled

coverde check

Check the coverage value (%) computed from a trace file.

The unique argument should be an integer between 0 and 100.
This parameter indicates the minimum value for the coverage to be accepted.

Arguments

Single-options

• --input

  Trace file used for the coverage check.
  Default value: coverage/lcov.info

• --file-coverage-log-level

  The log level for the coverage value for each source file listed in the input info file.
  Default value: line-content
  Allowed values:

  • none: Log nothing.
  • overview: Log the overview of the coverage value for the file.
  • line-numbers: Log only the uncovered line numbers.
  • line-content: Log the uncovered line numbers and their content.

Parameters

• min-coverage

  The minimum coverage value to be accepted. It should be an integer between 0 and 100.

Examples

coverde filter

Filter a coverage trace file.

Filter the coverage info by ignoring data related to files with paths that matches the given FILTERS.
The coverage data is taken from the INPUT_LCOV_FILE file and the result is appended to the OUTPUT_LCOV_FILE file.

All the relative paths in the resulting coverage trace file will be resolved relative to the , if provided.

Arguments

Single-options

• --input

  Origin coverage info file to pick coverage data from.
  Default value: coverage/lcov.info

• --output

  Destination coverage info file to dump the resulting coverage data into.
  Default value: coverage/filtered.lcov.info

• --base-directory

  Base directory relative to which trace file source paths are resolved.

• --mode

  The mode in which the OUTPUT_LCOV_FILE can be generated.
  Default value: a
  Allowed values:

  • a: Append filtered content to the OUTPUT_LCOV_FILE content, if any.
  • w: Override the OUTPUT_LCOV_FILE content, if any, with the filtered content.

Multi-options

• --filters

  Set of comma-separated path patterns of the files to be ignored.

  Each pattern must be a valid regex expression. Invalid patterns will cause the command to fail.
  Default value: None

coverde report

Generate the coverage report from a trace file.

Generate the coverage report inside REPORT_DIR from the TRACE_FILE trace file.

Arguments

Single-options

• --input

  Coverage trace file to be used for the coverage report generation.
  Default value: coverage/lcov.info

• --output

  Destination directory where the generated coverage report will be stored.
  Default value: coverage/html/

• --medium

  Medium threshold.

  Must be a number between 0 and 100, and must be less than the high threshold.
  Default value: 75

• --high

  High threshold.

  Must be a number between 0 and 100, and must be greater than the medium threshold.
  Default value: 90

Flags

• --launch

  Launch the generated report in the default browser. This option is only supported on desktop platforms. (defaults to off)
  Default value: Disabled

Examples

coverde remove

Remove a set of files and folders.

Arguments

Flags

• --dry-run

  Preview what would be deleted without actually deleting. When enabled (default), the command will list what would be deleted but not perform the deletion. When disabled, the command will actually delete the specified files and folders.
  Default value: Enabled

• --accept-absence

  Accept absence of a file or folder. When an element is not present:

  • If enabled, the command will continue.
  • If disabled, the command will fail.
    Default value: Enabled

Parameters

• paths

  Set of file and/or directory paths to be removed.

coverde value

Compute the coverage value (%) of an info file.

Compute the coverage value of the LCOV_FILE info file.

Arguments

Single-options

• --input

  Coverage info file to be used for the coverage value computation.
  Default value: coverage/lcov.info

• --file-coverage-log-level

  The log level for the coverage value for each source file listed in the LCOV_FILE info file.
  Default value: line-content
  Allowed values:

  • none: Log nothing.
  • overview: Log the overview of the coverage value for the file.
  • line-numbers: Log only the uncovered line numbers.
  • line-content: Log the uncovered line numbers and their content.

Examples

---

Usage with melos

If your project uses melos to manage its multi-package structure, it could be handy to collect test coverage data in a unified trace file.

This can be achieved by defining a melos script as follows:

merge-trace-files:
  description: Merge all packages coverage trace files ignoring data related to generated files.
  run: >
    coverde rm --no-dry-run MELOS_ROOT_PATH/coverage/filtered.lcov.info &&
    melos exec --file-exists=coverage/lcov.info -- "coverde filter --input ./coverage/lcov.info --output MELOS_ROOT_PATH/coverage/filtered.lcov.info --base-directory MELOS_ROOT_PATH --filters '\.g\.dart'"

merge-trace-files is the melos script that merges the coverage trace file of all tested packages contained within the project

First, the script removes the filtered.lcov.info file, if it exists, from the coverage folder in the root folder of the project.

Then, the script executes the coverde filter command for each package that contains a coverage/lcov.info file, using its content as input and the filtered.lcov.info file in the project root as output.

The resulting merged trace file ignores data related to generated files, which are identified by the .g.dart extension.

Each referenced file path is prefixed with the package path, so that the resulting merged trace file contains a set of paths that represent the actual project structure, which is critical for the coverde report command to work properly, as it relies on the file system to generate the HTML report.

---

CI integration for coverage checks

If your project uses GitHub Actions for CI, you might already know very_good_coverage, which offers a simple but effective method for coverage validation.

However, adding coverage checks to CI workflows hosted by other alternatives is not always that straightforward.

To solve this, after enabling Dart or Flutter in your CI workflow, according to your project requirements, you can use coverde and its check tool by adding the following commands to your workflow steps:

• dart pub global activate coverde
• coverde check <min_coverage>

Bugs or Requests

If you encounter any problems or you believe the CLI is missing a feature, feel free to open an issue on GitHub.

Pull request are also welcome. See CONTRIBUTING.md.