1 # Code coverage 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 Starting with the Jack Douarn release (4.x), the code coverage is provided with the Jack plugin 12 `jack-coverage-plugin.jar`. 13 14 ## Enabling code coverage with Jack 15 16 ### Using the Android build system 17 18 You can enable code coverage by setting `EMMA_INSTRUMENT_STATIC=true` in your make command. The build 19 system will compile it with Jack by enabling code coverage and importing the `jacoco-agent.jar` 20 defined in external/jacoco. It will produce the metadata file in the 'intermediates' directory of 21 the app. 22 23 For instance, to instrument the Settings app: 24 25 EMMA_INSTRUMENT_STATIC=true mmma -j32 packages/apps/Settings 26 27 The medatafile is located in `$ANDROID_BUILD_TOP/out/target/common/obj/APPS/Settings_intermediates/coverage.em` 28 29 Once the application is instrumented, you can install it and execute it to produce code coverage 30 execution file. 31 32 You can define class name filters to select which classes will be instrumented (all classes are 33 instrumented by default) by defining the following build variables: 34 * `LOCAL_JACK_COVERAGE_INCLUDE_FILTER`: a comma-separated list of class names to include 35 * `LOCAL_JACK_COVERAGE_EXCLUDE_FILTER`: a comma-separated list of class names to exclude 36 These filters will be passed on the Jack command-line (see below) only when code coverage is 37 enabled. 38 39 ### Using Jack command-line 40 41 To enable code coverage with Jack command-line, pass the following command-line options: 42 43 ``` 44 --pluginpath <code_coverage_plugin_jar> 45 --plugin com.android.jack.coverage.CodeCoverage 46 -D jack.coverage=true 47 -D jack.coverage.metadata.file=<coverage_metadata_file_path> 48 -D jack.coverage.jacoco.package=<jacoco_internal_package_name> 49 ``` 50 51 where 52 * `<code_coverage_plugin_jar>` is the path to the plugin jar file. In the Android tree, it is 53 located in the `prebuilts/sdk/tools` directory. 54 * `<coverage_metadata_file_path>` is a *mandatory* property that indicates the path of the file that 55 will contain coverage information. This file must be passed to reporting tool to generate the 56 report (see section Generating the report below) 57 * `<jacoco_internal_package_name>` is an *optional* property that indicates the fully qualified name 58 of the internal package name containing the class 'Offline' in the associated jacoco-agent.jar 59 file. This package name is different for each release of JaCoCo library. If this property is not 60 provided, Jack will automatically look for a Jacoco package which starts with 61 `org.jacoco.agent.rt.internal`. 62 63 Note: because Jack's code coverage support is based on Jacoco, it is mandatory that Jacoco classes 64 are available at compilation time. They can be either on the classpath (--classpath) or imported 65 as a static library in the output (--import). 66 67 Jack also supports optional include and exclude class filtering based on class name: 68 69 ``` 70 -D jack.coverage.jacoco.include=<includes> 71 -D jack.coverage.jacoco.exclude=<excludes> 72 ``` 73 74 where 75 * `<includes>` is a comma-separated list of fully-qualified class names to include 76 * `<excludes>` is a comma-separated list of fully-qualified class names to exclude 77 78 Wildcards characters '?' and '*' are accepted to replace respectively one character or multiple 79 characters. 80 81 You can find the full command-line usage with 82 83 java -jar <jack_jar> --help 84 85 You can also find the description of all properties (including those for code coverage) with 86 87 java -jar <jack_jar> --pluginpath <code_coverage_plugin_jar> --plugin com.android.jack.coverage.CodeCoverage --help-properties 88 89 ## Collecting code coverage 90 91 To produce coverage execution data, instrumented classes must be executed and coverage data be 92 dumped in a coverage execution file. For Android instrumentation tests, the frameworks can do 93 so automatically: 94 95 adb shell am instrument -w -e coverage true <package_name>/<instrumentation_class_name> 96 97 For the case of the Settings app tests: 98 99 adb shell am instrument -w -e coverage true com.android.settings.tests/android.test.InstrumentationTestRunner 100 101 Once the tests are finished, the location of the coverage execution file should be printed in the 102 console. 103 104 ## Generating the report 105 106 A coverage report can be generated using the `jack-jacoco-reporter.jar` file. This is a command-line 107 tool taking at least three inputs: 108 109 * the coverage metadata file(s) produced by Jack 110 * the coverage execution file(s) produced during execution 111 * an existing directory where the report is generated 112 113 It is also recommended to indicate the directories containing the source code of classes being 114 analyzed to link coverage information with the source code. 115 116 The command then looks like: 117 118 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> 119 120 You can find the full command-line usage with 121 122 java -jar jack-jacoco-reporter.jar --help 123 124
