Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / d7d2f75c3b74ac589b61c8d3f3a23603fd33828d / . / org.jacoco.doc / docroot / doc / counters.html
blob: 133c865ffe00a3c6da117dd1e96eb73c12c06072 [file] [log] [blame]
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]1<?xml version="1.0" encoding="ISO-8859-1" ?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
4<head>
5 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
6 <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
Marc R. Hoffmannd7d2f752010-05-06 21:12:31 +0000[diff] [blame^]7 <link rel="shortcut icon" href=".resources/report.gif" type="image/gif" />
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]8 <title>JaCoCo - Coverage Counter</title>
9</head>
10<body>
11
12<div class="breadcrumb">
Marc R. Hoffmannd7d2f752010-05-06 21:12:31 +0000[diff] [blame^]13 <a href="../index.html" class="el_report">JaCoCo</a> &gt;
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]14 <a href="index.html" class="el_group">Documentation</a> &gt;
15 <span class="el_source">Coverage Counters</span>
16</div>
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]17<div id="content">
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]18
19<h1>Coverage Counters</h1>
20
21<p>
22 JaCoCo uses a set of different counters to calculate coverage metrics. The
23 foundation of all counters are so called <i>basic blocks</i>. All other
24 counters are derived from the <i>basic block</i> coverage information. While
25 JaCoCo counters appear to be closely related to Java source code they are
26 actually only derived from Java class files. In cases where the Java compiler
27 creates so called <i>synthetic</i> code to reflect certain Java language
28 constructs counters may therefore show unexpected results.
29</p>
30
31<h2>Basic Blocks</h2>
32
33<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]34 A basic block &ndash; mostly just referred to as <i>block</i> in the APIs and
35 reports &ndash; represents a consecutive sequence of byte code instructions
36 and is a unit that will either execute completely or not all. The single
37 exception from this definition occurs when the java exception mechanism comes
38 to action (i.e. a java exception "flies"). This always interrupts the current
39 blocks execution. The boundaries between blocks are
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]40</p>
41
42<ul>
43 <li>return instructions,</li>
44 <li>throw instructions,</li>
45 <li>(conditional) jump instructions and</li>
46 <li>target labels referred from jump, try/catch or switch instructions.</li>
47</ul>
48
49<p>
50 The JaCoCo instrumentation mechanism inserts a probe at the end of every
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]51 block. When the probe gets executed the block is considered executed.
52 This results in the major drawback of basic block based probes:
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]53</p>
54
55<p class="hint">
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]56 Blocks that encounter an exception somewhere in the middle of their execution
57 will be considered as not executed. This is correct as the block actually
58 didn't get executed but JaCoCo won't be able to tell which lines of the block
59 executed and which didn't.
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]60</p>
61
62<p>
63 Beside this, basic block code coverage has been proven to work very
64 efficiently even with huge applications under test. The reasons are that the
65 blocks can be easily determined at instrumentation time. The amount of
66 inserted probes offer a good tradeoff between runtime overhead and report
67 granularity. And last but not least basic blocks can be determined even if the
68 class files have not been compiled in debug mode and therefore do not contain
69 any source line information. Therefore all coverage counters except the line
70 counter will work also in this case and provide useful coverage information
71 e.g. for binary third party libraries.
72</p>
73
74<h2>Instructions</h2>
75
76<p>
77 For each block the number of included byte code instructions can be easily
78 determined. The instruction counter summarizes the number of single byte code
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]79 instructions that belong to executed blocks. As blocks may be of different
80 length, instructions give a good measure of block size and can serve as a
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]81 replacement when no line information is available.
82</p>
83
84<h2>Lines</h2>
85
86<p>
87 For all class files that have been compiled in debug mode with source line
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]88 information, coverage information for individual lines can be derived from
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]89 basic blocks. Each block may span one ore multiple lines of source code. On
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]90 the other hand a single line of source may belong to multiple blocks. A source
91 line is considered executed when at least one block that includes this line
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]92 has been executed.
93</p>
94
95<p>
96 Due to the fact that a single line may belong to more that one block
97 <i>partial</i> coverage can happen if some of the blocks are executed while
98 others are not. This is typically the case with boolean expressions. While
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]99 partially covered lines are seen as executed due to the definition in the
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]100 previous paragraph, they are highlighted in yellow color in the coverage
101 reports.
102</p>
103
104<h2>Methods</h2>
105
106<p>
107 Each non-abstract method consists of at least one block. A method is
108 considered as executed when at least one block has been executed. As JaCoCo
109 works on byte code level also constructors and static initializers are counted
110 as methods. Some of these methods may not have a direct correspondence in Java
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]111 source code, like implicit and thus generated default constructors or initializers
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]112 for constants.
113</p>
114
115<h2>Classes</h2>
116
117<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]118 A class is considered as executed when at least one of its methods has been
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]119 executed. Note that JaCoCo considers constructors as well as static
120 initializers as methods. As Java interface types may contain static
121 initializers such interfaces are also considered as executable classes.
122</p>
123
124
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]125</div>
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]126<div class="footer">
Marc R. Hoffmannb623ffb2010-05-06 19:48:08 +0000[diff] [blame]127 <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
Marc R. Hoffmanndf6ff962010-04-09 15:31:22 +0000[diff] [blame]128 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]129</div>
130
131</body>
132</html>