From d7fb3534d040373d95be471503dfee5cca05688f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gergely=20F=C3=A1bi=C3=A1n?= <gergo.fb@gmail.com>
Date: Sat, 7 Mar 2020 12:02:33 +0100
Subject: [PATCH] Documentation for coverage support (#1017)

* Documentation for coverage support

* Coverage: update example script to use combined coverage report

* Coverage docs: adding note about only being tested with ScalaTest
---
 README.md        | 37 +++++++++++++++++++++++++++++
 docs/coverage.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 98 insertions(+)
 create mode 100644 docs/coverage.md

diff --git a/README.md b/README.md
index c4bda15940..116aaea0ed 100644
--- a/README.md
+++ b/README.md
@@ -83,6 +83,43 @@ build --worker_sandboxing
 ```
 to your command line, or to enable by default for building/testing add it to your .bazelrc.
 
+## Coverage support
+
+rules_scala supports coverage, but it's disabled by default. You need to enable it with an extra toolchain:
+
+```
+bazel coverage --extra_toolchains="@io_bazel_rules_scala//test/coverage:enable_code_coverage_aspect" //...
+```
+
+It will produce several .dat files with results for your targets.
+
+You can also add more options to receive a combined coverage report:
+
+```
+bazel coverage \
+  --extra_toolchains="@io_bazel_rules_scala//test/coverage:enable_code_coverage_aspect" \
+  --combined_report=lcov \
+  --coverage_report_generator="@bazel_tools//tools/test/CoverageOutputGenerator/java/com/google/devtools/coverageoutputgenerator:Main" \
+  //...
+```
+
+This should produce a single `bazel-out/_coverage/_coverage_report.dat` from all coverage files that are generated.
+
+You can extract information from your coverage reports with `lcov`:
+
+```
+# For a summary:
+lcov --summary your-coverage-report.dat
+# For details:
+lcov --list your-coverage-report.dat
+```
+
+If you prefer an HTML report, then you can use `genhtml` provided also by the `lcov` package.
+
+Coverage support has been only tested with [ScalaTest](http://www.scalatest.org/).
+
+Please check [coverage.md](docs/coverage.md) for more details on coverage support.
+
 ## Selecting Scala version
 
 Rules scala supports the last two released minor versions for each of Scala 2.11 and 2.12.
diff --git a/docs/coverage.md b/docs/coverage.md
new file mode 100644
index 0000000000..d264ffd9a1
--- /dev/null
+++ b/docs/coverage.md
@@ -0,0 +1,61 @@
+## Coverage support
+
+### Running tests with coverage
+
+rules_scala supports coverage, but it's disabled by default. You need to enable it with an extra toolchain:
+
+```
+bazel coverage --extra_toolchains="@io_bazel_rules_scala//test/coverage:enable_code_coverage_aspect" //...
+```
+
+It will produce several .dat files with results for your targets.
+
+You can also add more options to receive a combined coverage report:
+
+```
+bazel coverage \
+  --extra_toolchains="@io_bazel_rules_scala//test/coverage:enable_code_coverage_aspect" \
+  --combined_report=lcov \
+  --coverage_report_generator="@bazel_tools//tools/test/CoverageOutputGenerator/java/com/google/devtools/coverageoutputgenerator:Main" \
+  //...
+```
+
+This should produce a single `bazel-out/_coverage/_coverage_report.dat` from all coverage files that are generated.
+
+### Processing coverage reports
+
+You can install `lcov` package (that supports the format Bazel uses for coverage reports) to have access to additional tools:
+
+```
+# Use your system package manager. E.g. on Ubuntu:
+sudo apt install lcov
+```
+
+Having `lcov` package installed you can extract information from your coverage reports:
+
+```
+# For a summary:
+lcov --summary your-coverage-report.dat
+# For details:
+lcov --list your-coverage-report.dat
+```
+
+If you prefer an HTML report, then you can use `genhtml` provided also by the `lcov` package.
+
+An example with a bit of ceremony:
+
+```bash
+# Output html reports to a new directory.
+destdir="my-coverage-reports"
+mkdir -p ${destdir}
+
+# Generate HTML report from the results.
+genhtml -o ${destdir} --ignore-errors source bazel-out/_coverage/_coverage_report.dat
+
+echo "coverage report at file://${destdir}/index.html"
+
+```
+
+### Support for testing frameworks
+
+Coverage support has been only tested with [ScalaTest](http://www.scalatest.org/).
\ No newline at end of file