1# Android code coverage instructions 2 3These are instructions for collecting code coverage data for android 4instrumentation and JUnit tests. For Clang(C++) code coverage refer to [clang coverage]. 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 85[clang coverage]: https://chromium.googlesource.com/chromium/src/+/HEAD/docs/testing/code_coverage.md