Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 31d0c9026bc3d1a4e90b45ece6c5f81c67cda9b1 / . / org.jacoco.doc / docroot / doc / counters.html
blob: accb04d60fe672c25691bd2338457c74935054f5 [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>
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]22 JaCoCo uses a set of different counters to calculate coverage metrics. All
23 these counters are derived from information contained in Java class files
24 which basically are Java byte code instructions and debug information
25 optionally embedded in class files. This approach allows efficient on-the-fly
26 instrumentation and analysis of applications even when no source code is
27 available. In most cases the collected information can be mapped back to
28 source code and visualized down to line level granularity. Anyhow there are
29 limitations to this approach. The class files have to be compiled with debug
30 information to calculate line level coverage and provide source highlighting.
31 Not all Java language constructs can be directly compiled to corresponding
32 byte code. In such cases the Java compiler creates so called <i>synthetic</i>
33 code which sometimes results in unexpected code coverage results.
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]34</p>
35
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]36<h2>Instructions (C0 Coverage)</h2>
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]37
38<p>
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]39 The smallest unit JaCoCo counts are single Java byte code instructions.
40 <i>Instruction coverage</i> provides information about the amount of code that
41 has been executed or missed. This metric is completely independent from source
42 formatting and always available, even in absence of debug information in the
43 class files.
44</p>
45
46<h2>Branches (C1 Coverage)</h2>
47
48<p>
49 JaCoCo also calculates <i>branch coverage</i> for all <code>if</code> and
50 <code>switch</code> statements. This metric counts the total number of such
51 branches in a method and determines the number of executed or missed branches.
52 Branch coverage is always available, even in absence of debug information in
Marc R. Hoffmanne3fc6e72011-05-11 17:31:23 +0000[diff] [blame]53 the class files. Note that exception handling is not considered as branches
54 in the context of this counter definition.
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]55</p>
56
57<p>
58 If the class files haven been compiled with debug information decision points
Marc R. Hoffmanne3fc6e72011-05-11 17:31:23 +0000[diff] [blame]59 can be mapped to source lines and highlighted accordingly:
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]60</p>
61
62<ul>
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]63 <li>No coverage: No branches in the line has been executed (red diamond)</li>
64 <li>Partial coverage: Only a part of the branches in the line have been
65 executed (yellow diamond)</li>
66 <li>Full coverage: All branches in the line have been executed (green diamond)</li>
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]67</ul>
68
Marc R. Hoffmanne3fc6e72011-05-11 17:31:23 +0000[diff] [blame]69<h2>Cyclomatic Complexity</h2>
70
71<p>
72 JaCoCo also calculates cyclomatic complexity for each non-abstract method and
73 summarizes complexity for classes, packages and groups. According to its
74 definition by
75 <a href="http://hissa.nist.gov/HHRFdata/Artifacts/ITLdoc/235/title.htm">McCabe1996</a>
76 cyclomatic complexity is the minimum number of paths that can, in (linear)
77 combination, generate all possible paths through a method. Thus the
78 complexity value can serve as an indication for the number of unit test cases
79 to fully cover a certain piece of software. Complexity figures can always be
80 calculated, even in absence of debug information in the class files.
81</p>
82
83<p>
84 The formal definition of the cyclomatic complexity v(G) is based on the
85 representation of a method's control flow graph as a directed graph:
86</p>
87
88<blockquote>
89 v(G) = E - N + 2
90</blockquote>
91
92<p>
93 Where E is the number of edges and N the number of nodes. JaCoCo calculates
94 cyclomatic complexity of a method with the following equivalent equation based
95 on the number of branches (B) and the number of decision points (D):
96</p>
97
98<blockquote>
99 v(G) = B - D + 1
100</blockquote>
101
102<p>
103 Based on the coverage status of each branch JaCoCo also calculates covered and
104 missed complexity for each method. Missed complexity again is an indication
105 for the number of test cases missing to fully cover a module. Note that as
106 JaCoCo does not consider exception handling as branches try/catch blocks will
107 also not increase complexity.
108</p>
109
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]110<h2>Lines</h2>
111
112<p>
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]113 For all class files that have been compiled with debug information, coverage
114 information for individual lines can be calculated. A source line is
115 considered executed when at least one instruction that is assigned to this
116 line has been executed.
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]117</p>
118
119<p>
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]120 Due to the fact that a single line typically compiles to multiple byte code
121 instructions the source code highlighting shows three different status for
122 each line containing source code:
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]123</p>
124
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]125<ul>
126 <li>No coverage: No instruction in the line has been executed (red
127 background)</li>
128 <li>Partial coverage: Only a part of the instruction in the line have been
129 executed (yellow background)</li>
130 <li>Full coverage: All instructions in the line have been executed (green
131 background)</li>
132</ul>
133
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]134<h2>Methods</h2>
135
136<p>
Marc R. Hoffmann2593f032010-12-20 18:28:34 +0000[diff] [blame]137 Each non-abstract method contains at least one instruction. A method is
138 considered as executed when at least one instruction has been executed. As
139 JaCoCo works on byte code level also constructors and static initializers are
140 counted as methods. Some of these methods may not have a direct correspondence
141 in Java source code, like implicit and thus generated default constructors or
142 initializers for constants.
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]143</p>
144
145<h2>Classes</h2>
146
147<p>
Radek Libaad5fbc92009-10-26 13:26:53 +0000[diff] [blame]148 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]149 executed. Note that JaCoCo considers constructors as well as static
150 initializers as methods. As Java interface types may contain static
151 initializers such interfaces are also considered as executable classes.
152</p>
153
Marc R. Hoffmann17be2692010-02-02 05:44:47 +0000[diff] [blame]154</div>
Marc R. Hoffmannc4b20782009-10-02 13:28:46 +0000[diff] [blame]155<div class="footer">
Marc R. Hoffmannb623ffb2010-05-06 19:48:08 +0000[diff] [blame]156 <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]157 <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]158</div>
159
160</body>
161</html>