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 #

• Check coverage value computed from a trace file
• Filter the tested files included in a trace file
• Remove a set of files and folders
• Generate HTML coverage report
• Compute and display the coverage value from a trace file

coverde check #

Check coverage value computed from a trace file.

Options #

• --input | -i

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

Flags #

• --verbose | -v

  Whether to print the coverage value.
  Use --no-verbose to disable this flag.
  Default value: Enabled

Parameters #

• <min_coverage>

  An integer between 0 and 100 used as minimum acceptable coverage value.
  This value is required.

Examples #

• coverde check 90
• coverde check -i lcov.info 75
• coverde check 100 --no-verbose

Results #

coverde filter #

Filter the tested files included in a trace file.

Options #

• --input | -i

  Coverage trace file to be filtered.
  Default value: coverage/lcov.info

• --output | -o

  Filtered coverage trace file (automatically created if it is absent).
  Default value: coverage/filtered.lcov.info

• --paths-parent | -p

  Prefix of the resulting filtered paths.
  Default value: Unset

• --filters | -f

  Set of comma-separated patterns of the files to be opted out of coverage.
  Default value: Unset

• --mode | -m

  The mode in which the filtered trace file content should be generated.
  a: append content.
  w: overwrite content.
  Default value: a (append content)

Examples #

• coverde filter
• coverde filter -f '\.g\.dart'
• coverde filter -f '\.freezed\.dart' -mode w
• coverde filter -f generated -mode a
• coverde filter -o coverage/trace-file.info

coverde remove #

Remove a set of files and folders.

Flags #

• --accept-absence

  Set the command behavior according to a file/folder existence.
  If enabled, the command continues and notifies the element absence.
  If disabled, the command fails.
  Use --no-accept-absence to disable this flag.
  Default value: Enabled

Parameters #

• <paths>

  Set of paths to be removed.
  Multiple paths can be specified by separating them with a space.
  This value is required.

Examples #

• coverde remove file.txt
• coverde remove path/to/folder/
• coverde remove path/to/another.file.txt path/to/another/folder/ local.folder/

coverde report #

Generate HTML coverage report.

Options #

• --input | -i

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

• --output | -o

  Destination folder where the generated report files will be placed.
  Default value: coverage/html/

• --medium

  Medium threshold for coverage value.
  Default value: 75

• --high

  High threshold for coverage value.
  Default value: 90

Flags #

• --launch | -l

  Whether to launch the generated report in the default browser.
  Use --no-launch to disable this flag.
  Default value: Disabled

Examples #

• coverde report
• coverde report -i coverage/trace-file.info --medium 50
• coverde report -o coverage/report --high 95 -l

Results #

coverde value #

Compute and display the coverage value from a trace file.

Options #

• --input | -i

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

Flags #

• --verbose | -v

  Whether to print the coverage value for each source file referenced in the trace file.
  Use --no-verbose to disable this flag.
  Default value: Enabled

Examples #

• coverde value
• coverde value -i coverage/trace-file.info --no-verbose

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 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 --paths-parent MELOS_PACKAGE_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.