1# Android code coverage instructions
2
3These are instructions for collecting code coverage data for android
4instrumentation and JUnit tests.
5
6[TOC]
7
8## How JaCoCo coverage works
9
10In order to use JaCoCo code coverage, we need to create build time pre-instrumented
11class files and runtime **.exec** files. Then we need to process them using the
12[build/android/generate_jacoco_report.py](https://source.chromium.org/chromium/chromium/src/+/main:build/android/generate_jacoco_report.py) script.
13
14## How to collect coverage data
15
161. Use the following GN build arguments:
17
18  ```gn
19  target_os = "android"
20  use_jacoco_coverage = true
21  ```
22
23   Now when building, pre-instrumented files will be created in the build directory.
24
252. Run tests, with option `--coverage-dir <directory>`, to specify where to save
26   the .exec file. For example, you can run chrome JUnit tests:
27   `out/Debug/bin/run_chrome_junit_tests --coverage-dir /tmp/coverage`.
28
293. The coverage results of JUnit and instrumentation tests will be merged
30   automatically if they are in the same directory.
31
32## How to generate coverage report
33
341. Now we have generated .exec files already. We can create a JaCoCo HTML/XML/CSV
35   report using `generate_jacoco_report.py`, for example:
36
37  ```shell
38  build/android/generate_jacoco_report.py \
39     --format html \
40     --output-dir /tmp/coverage_report/ \
41     --coverage-dir /tmp/coverage/ \
42     --sources-json-dir out/Debug/ \
43  ```
44   Then an index.html containing coverage info will be created in output directory:
45
46  ```
47  [INFO] Loading execution data file /tmp/coverage/testTitle.exec.
48  [INFO] Loading execution data file /tmp/coverage/testSelected.exec.
49  [INFO] Loading execution data file /tmp/coverage/testClickToSelect.exec.
50  [INFO] Loading execution data file /tmp/coverage/testClickToClose.exec.
51  [INFO] Loading execution data file /tmp/coverage/testThumbnail.exec.
52  [INFO] Analyzing 58 classes.
53  ```
54
552. For XML and CSV reports, we need to specify `--output-file` instead of `--output-dir` since
56   only one file will be generated as XML or CSV report.
57  ```shell
58  build/android/generate_jacoco_report.py \
59    --format xml \
60    --output-file /tmp/coverage_report/report.xml \
61    --coverage-dir /tmp/coverage/ \
62    --sources-json-dir out/Debug/ \
63  ```
64
65   or
66
67  ```shell
68  build/android/generate_jacoco_report.py \
69    --format csv \
70    --output-file /tmp/coverage_report/report.csv \
71    --coverage-dir /tmp/coverage/ \
72    --sources-json-dir out/Debug/ \
73  ```
743. If generating coverage and there are duplicate class files, as can happen
75   when generating coverage for downstream targets, use the
76   `--include-substr-filter` option to choose jars in the desired directory. Eg.
77   for generating coverage report for Clank internal repo
78  ```shell
79  build/android/generate_jacoco_report.py --format html \
80   --output-dir /tmp/coverage_report/ --coverage-dir /tmp/coverage/ \
81   --sources-json-dir out/java_coverage/ \
82   --include-substr-filter obj/clank
83  ```
84