| Coverage provides coverage data collection, manipulation, and formatting for |
| Dart. |
| |
| [](https://github.com/dart-lang/coverage/actions?query=workflow%3A"Dart+CI"+branch%3Amaster) |
| [](https://coveralls.io/r/dart-lang/coverage) |
| [](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](http://ltp.sourceforge.net/coverage/lcov.php) or pretty-printed format. |
| |
| #### Install coverage |
| |
| dart pub global activate coverage |
| |
| Consider adding the `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. |
| |
| #### Collecting coverage from the VM |
| |
| ``` |
| dart --pause-isolates-on-exit --disable-service-auth-codes --enable-vm-service=NNNN script.dart |
| pub global run coverage:collect_coverage --uri=http://... -o coverage.json --resume-isolates |
| ``` |
| |
| or if the `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 |
| |
| ``` |
| pub global run coverage:format_coverage --packages=app_package/.packages -i coverage.json |
| ``` |
| |
| or if the `pub global run` exectuables are on your PATH, |
| |
| ``` |
| format_coverage --packages=app_package/.packages -i coverage.json |
| ``` |
| |
| where `app_package` is the path to the package whose coverage is being |
| collected. 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. |
| |
| #### 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 |
| 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 |
| 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 |
| pub global run coverage:collect_coverage --uri=http://... -o coverage.json --resume-isolates --function-coverage --branch-coverage |
| ``` |
