feat: add "deno coverage" subcommand (#8664)

This commit adds a new subcommand called "coverage" 
which can generate code coverage reports to stdout in 
multiple formats from code coverage profiles collected to disk.

Currently this supports outputting a pretty printed diff and 
the lcov format for interoperability with third-party services and tools.

Code coverage is still collected via other subcommands 
that run and collect code coverage such as 
"deno test --coverage=<directory>" but that command no 
longer prints a pretty printed report at the end of a test 
run with coverage collection enabled.

The restrictions on which files that can be reported on has 
also been relaxed and are fully controllable with the include 
and exclude regular expression flags on the coverage subcommand.

Co-authored-by: Luca Casonato <lucacasonato@yahoo.com>

1 files changed, 28 insertions, 21 deletions

diff --git a/docs/testing.md b/docs/testing.md
index 9b53c4c82..9d9f2de04 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -234,29 +234,36 @@ deno test --fail-fast
 
 ## Test coverage
 
-Deno will automatically determine test coverage for your code if you specify the
-`--coverage` flag when starting `deno test`. Coverage is determined on a line by
-line basis for modules that share the parent directory with at-least one test
-module that is being executed.
+Deno will collect test coverage into a directory for your code if you specify
+the `--coverage` flag when starting `deno test`.
 
-This coverage information is acquired directly from the JavaScript engine (V8).
-Because of this, the coverage reports are very accurate.
+This coverage information is acquired directly from the JavaScript engine (V8)
+which is very accurate.
 
-When all tests are done running a summary of coverage per file is printed to
-stdout. In the future there will be support for `lcov` output too.
+This can then be further processed from the internal format into well known
+formats by the `deno coverage` tool.
 
 ```
-$ git clone git@github.com:denosaurs/deno_brotli.git && cd deno_brotli
-$ deno test --coverage --unstable
-Debugger listening on ws://127.0.0.1:9229/ws/5a593019-d185-478b-a928-ebc33e5834be
-Check file:///home/deno/deno_brotli/$deno$test.ts
-running 2 tests
-test compress ... ok (26ms)
-test decompress ... ok (13ms)
-
-test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out (40ms)
-
-test coverage:
-file:///home/deno/deno_brotli/mod.ts 100.000%
-file:///home/deno/deno_brotli/wasm.js 100.000%
+# Go into your project's working directory
+git clone https://github.com/oakserver/oak && cd oak
+
+# Collect your coverage profile with deno test --coverage=<output_directory>
+deno test --coverage=cov_profile --unstable
+
+# From this you can get a pretty printed diff of uncovered lines
+deno coverage --unstable cov_profile
+
+# Or generate an lcov report
+deno coverage --unstable cov_profile --lcov > cov_profile.lcov
+
+# Which can then be further processed by tools like genhtml
+genhtml -o cov_profile/html cov_profile.lcov
 ```
+
+By default, `deno coverage` will exclude any files matching the regular
+expression `test\.(js|mjs|ts|jsx|tsx)` and only consider including files
+matching the regular expression `^file:`.
+
+These filters can be overriden using the `--exclude` and `--include` flags. A
+source file's url must match both regular expressions for it to be a part of the
+report.