| Coverage provides coverage data collection, manipulation, and formatting for | |
| Dart. | |
| [](https://github.com/dart-lang/tools/actions/workflows/coverage.yaml) | |
| [](https://coveralls.io/github/dart-lang/tools?branch=main) | |
| [](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 | |
| ``` |