1 # Code codeverage with Jack 2 3 Jack supports code coverage with `JaCoCo` (http://eclemma.org/jacoco). During the compilation, 4 it will instrument code using JaCoCo API. Therefore, it requires a dependency to a jacoco-agent.jar 5 that can be imported in the DEX output. Jack supports Jacoco v0.7.5 (see directory external/jacoco 6 in the Android source tree). 7 8 Besides, Jack will also produce a coverage metadata file (or description file) in a JSON format. 9 It will be used to generate the report so we can match coverage execution file with source code. 10 11 ## Enabling code coverage with Jack 12 13 ### Using the Android build system 14 15 You can enable code coverage by setting `EMMA_INSTRUMENT_STATIC=true` in your make command. The build 16 system will compile it with Jack by enabling code coverage and importing the `jacoco-agent.jar` 17 defined in external/jacoco. It will produce the metadata file in the 'intermediates' directory of 18 the app. 19 20 For instance, to instrument the Settings app: 21 22 EMMA_INSTRUMENT_STATIC=true mmma -j32 packages/apps/Settings 23 24 The medatafile is located in `$ANDROID_BUILD_TOP/out/target/common/obj/APPS/Settings_intermediates/coverage.em` 25 26 Once the application is instrumented, you can install it and execute it to produce code coverage 27 execution file. 28 29 You can define class name filters to select which classes will be instrumented (all classes are 30 instrumented by default) by defining the following build variables: 31 * `LOCAL_JACK_COVERAGE_INCLUDE_FILTER`: a comma-separated list of class names to include 32 * `LOCAL_JACK_COVERAGE_EXCLUDE_FILTER`: a comma-separated list of class names to exclude 33 These filters will be passed on the Jack command-line (see below) only when code coverage is 34 enabled. 35 36 ### Using Jack command-line 37 38 To enable code coverage with Jack command-line, pass the following property flags: 39 40 > -D jack.coverage=true 41 > -D jack.coverage.metadata.file=<coverage_metadata_file_path> 42 > -D jack.coverage.jacoco.package=<jacoco_internal_package_name> 43 44 where 45 * `<coverage_metadata_file_path>` is the path of the file that will contain coverage information 46 to generate the report 47 * `<jacoco_internal_package_name>` is the name of the internal package name containing the class 48 'Offline' in the associated jacoco-agent.jar file. This package 49 name is different for each release of JaCoCo. 50 (Note: this may be removed in the future) 51 52 Jack also supports include and exclude filtering based on class name: 53 54 > -D jack.coverage.jacoco.include=<includes> 55 > -D jack.coverage.jacoco.exclude=<excludes> 56 57 where 58 * `<includes>` is a comma-separated list of fully-qualified class names to include 59 * `<excludes>` is a comma-separated list of fully-qualified class names to exclude 60 61 Wildcards characters '?' and '*' are accepted to replace respectively one character or multiple 62 characters. 63 64 ## Collecting code coverage 65 66 To produce coverage execution data, instrumented classes must be executed and coverage data be 67 dumped in a coverage execution file. For Android instrumentation tests, the frameworks can do 68 so automatically: 69 70 adb shell am instrument -w -e coverage true <package_name>/<instrumentation_class_name> 71 72 For the case of the Settings app tests: 73 74 adb shell am instrument -w -e coverage true com.android.settings.tests/android.test.InstrumentationTestRunner 75 76 Once the tests are finished, the location of the coverage execution file should be printed in the 77 console. 78 79 ## Generating the report 80 81 A coverage report can be generated using the `jack-jacoco-reporter.jar` file. This is a command-line 82 tool taking at least three inputs: 83 84 * the coverage metadata file produced by Jack 85 * the coverage execution file produced during execution 86 * an existing directory where the report is generated 87 88 It is also recommended to indicate the directories containing the source code of classes being 89 analyzed to link coverage information with the source code. 90 91 The command then looks like: 92 93 java -jar jack-jacoco-reporter.jar --metadata-file <metadata_file> --coverage-file <execution_file> --report-dir <report_directory> --source-dir <source_dir_1> ... --source-dir <source_dir_N> 94 95 You can find the full command-line usage with 96 97 java -jar jack-jacoco-reporter.jar --help 98 99
