Coverage provides coverage data collection, manipulation, and formatting for
Dart.

[![Build Status](https://github.com/dart-lang/tools/actions/workflows/coverage.yaml/badge.svg)](https://github.com/dart-lang/tools/actions/workflows/coverage.yaml)
[![Coverage Status](https://coveralls.io/repos/github/dart-lang/tools/badge.svg?branch=main)](https://coveralls.io/github/dart-lang/tools?branch=main)
[![Pub](https://img.shields.io/pub/v/coverage.svg)](https://pub.dev/packages/coverage)

## Tools

`collect_coverage` collects coverage JSON from the Dart VM Service.
`format_coverage` formats JSON coverage data into either
[LCOV](https://github.com/linux-test-project/lcov) or pretty-printed format.

#### Install coverage

    dart pub global activate coverage

Consider adding the `dart pub global run` executables directory to your path.
See
[Running a script from your PATH](https://dart.dev/tools/pub/cmd/pub-global#running-a-script-from-your-path)
for more details.

#### Running tests with coverage

For the common use case where you just want to run all your tests, and generate
an lcov.info file, you can use the test_with_coverage script:

```
dart pub global run coverage:test_with_coverage
```

By default, this script assumes it's being run from the root directory of a
package, and outputs a coverage.json and lcov.info file to ./coverage/

This script is essentially the same as running:

```
dart run --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=8181 test &
dart pub global run coverage:collect_coverage --wait-paused --uri=http://127.0.0.1:8181/ -o coverage/coverage.json --resume-isolates --scope-output=foo
dart pub global run coverage:format_coverage --packages=.dart_tool/package_config.json --lcov -i coverage/coverage.json -o coverage/lcov.info
```

For more complicated use cases, where you want to control each of these stages,
see the sections below.

#### Workspaces

package:coverage has partial support for
[workspaces](https://dart.dev/tools/pub/workspaces). You can run
`test_with_coverage` from the root of the workspace to collect coverage for all
the tests in all the subpackages, but you must specify the test directories to
run.

For example, in a workspace with subpackages `pkgs/foo` and `pkgs/bar`, you
could run the following command from the root directory of the workspace:

```
dart run coverage:test_with_coverage -- pkgs/foo/test pkgs/bar/test
```

This would output coverage to ./coverage/ as normal. An important caveat is that
the working directory of the tests will be the workspace's root directory. So
this approach won't work if your tests assume that they are being run from the
subpackage directory.

[Full support](https://github.com/dart-lang/tools/issues/2083) for workspaces
will likely be added in a future version. This will mean you won't need to
explicitly specify the test directories: `dart run coverage:test_with_coverage`

#### Collecting coverage from the VM

```
dart --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=NNNN script.dart
dart pub global run coverage:collect_coverage --uri=http://... -o coverage.json --resume-isolates
```

or if the `dart pub global run` executables are on your PATH,

```
collect_coverage --uri=http://... -o coverage.json --resume-isolates
```

where `--uri` specifies the Dart VM Service URI emitted by the VM.

If `collect_coverage` is invoked before the script from which coverage is to be
collected, it will wait until it detects a VM observatory to which it can
connect. An optional `--connect-timeout` may be specified (in seconds). The
`--wait-paused` flag may be enabled, causing `collect_coverage` to wait until
all isolates are paused before collecting coverage.

#### Formatting coverage data

```
dart pub global run coverage:format_coverage --package=app_package -i coverage.json
```

or if the `dart pub global run` exectuables are on your PATH,

```
format_coverage --package=app_package -i coverage.json
```

where `app_package` is the path to the package whose coverage is being collected
(defaults to the current working directory). If `--sdk-root` is set, Dart SDK
coverage will also be output.

#### Ignore lines from coverage

- `// coverage:ignore-line` to ignore one line.
- `// coverage:ignore-start` and `// coverage:ignore-end` to ignore range of
  lines inclusive.
- `// coverage:ignore-file` to ignore the whole file.

Then pass `--check-ignore` to `format_coverage`.

#### Function and branch coverage

To gather function level coverage information, pass `--function-coverage` to
collect_coverage:

```
dart --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=NNNN script.dart
dart pub global run coverage:collect_coverage --uri=http://... -o coverage.json --resume-isolates --function-coverage
```

To gather branch level coverage information, pass `--branch-coverage` to _both_
collect_coverage and the Dart command you're gathering coverage from:

```
dart --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=NNNN --branch-coverage script.dart
dart pub global run coverage:collect_coverage --uri=http://... -o coverage.json --resume-isolates --branch-coverage
```

Branch coverage requires Dart VM 2.17.0, with service API v3.56. Function,
branch, and line coverage can all be gathered at the same time, by combining
those flags:

```
dart --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=NNNN --branch-coverage script.dart
dart pub global run coverage:collect_coverage --uri=http://... -o coverage.json --resume-isolates --function-coverage --branch-coverage
```

These flags can also be passed to test_with_coverage:

```
pub global run coverage:test_with_coverage --branch-coverage --function-coverage
```