1*7e63c127SSorin Basca<?xml version="1.0" encoding="UTF-8" ?> 2*7e63c127SSorin Basca<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3*7e63c127SSorin Basca<html xmlns="http://www.w3.org/1999/xhtml" lang="en"> 4*7e63c127SSorin Basca<head> 5*7e63c127SSorin Basca <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6*7e63c127SSorin Basca <link rel="stylesheet" href="resources/doc.css" charset="UTF-8" type="text/css" /> 7*7e63c127SSorin Basca <link rel="shortcut icon" href="resources/report.gif" type="image/gif" /> 8*7e63c127SSorin Basca <title>JaCoCo - Coverage Counter</title> 9*7e63c127SSorin Basca</head> 10*7e63c127SSorin Basca<body> 11*7e63c127SSorin Basca 12*7e63c127SSorin Basca<div class="breadcrumb"> 13*7e63c127SSorin Basca <a href="../index.html" class="el_report">JaCoCo</a> > 14*7e63c127SSorin Basca <a href="index.html" class="el_group">Documentation</a> > 15*7e63c127SSorin Basca <span class="el_source">Coverage Counters</span> 16*7e63c127SSorin Basca</div> 17*7e63c127SSorin Basca<div id="content"> 18*7e63c127SSorin Basca 19*7e63c127SSorin Basca<h1>Coverage Counters</h1> 20*7e63c127SSorin Basca 21*7e63c127SSorin Basca<p> 22*7e63c127SSorin Basca JaCoCo uses a set of different counters to calculate coverage metrics. All 23*7e63c127SSorin Basca these counters are derived from information contained in Java class files 24*7e63c127SSorin Basca which basically are Java byte code instructions and debug information 25*7e63c127SSorin Basca optionally embedded in class files. This approach allows efficient on-the-fly 26*7e63c127SSorin Basca instrumentation and analysis of applications even when no source code is 27*7e63c127SSorin Basca available. In most cases the collected information can be mapped back to 28*7e63c127SSorin Basca source code and visualized down to line level granularity. Anyhow there are 29*7e63c127SSorin Basca limitations to this approach. The class files have to be compiled with debug 30*7e63c127SSorin Basca information to calculate line level coverage and provide source highlighting. 31*7e63c127SSorin Basca Not all Java language constructs can be directly compiled to corresponding 32*7e63c127SSorin Basca byte code. In such cases the Java compiler creates so called <i>synthetic</i> 33*7e63c127SSorin Basca code which sometimes results in unexpected code coverage results. 34*7e63c127SSorin Basca</p> 35*7e63c127SSorin Basca 36*7e63c127SSorin Basca<h2>Instructions (C0 Coverage)</h2> 37*7e63c127SSorin Basca 38*7e63c127SSorin Basca<p> 39*7e63c127SSorin Basca The smallest unit JaCoCo counts are single Java byte code instructions. 40*7e63c127SSorin Basca <i>Instruction coverage</i> provides information about the amount of code that 41*7e63c127SSorin Basca has been executed or missed. This metric is completely independent from source 42*7e63c127SSorin Basca formatting and always available, even in absence of debug information in the 43*7e63c127SSorin Basca class files. 44*7e63c127SSorin Basca</p> 45*7e63c127SSorin Basca 46*7e63c127SSorin Basca<h2>Branches (C1 Coverage)</h2> 47*7e63c127SSorin Basca 48*7e63c127SSorin Basca<p> 49*7e63c127SSorin Basca JaCoCo also calculates <i>branch coverage</i> for all <code>if</code> and 50*7e63c127SSorin Basca <code>switch</code> statements. This metric counts the total number of such 51*7e63c127SSorin Basca branches in a method and determines the number of executed or missed branches. 52*7e63c127SSorin Basca Branch coverage is always available, even in absence of debug information in 53*7e63c127SSorin Basca the class files. Note that exception handling is not considered as branches 54*7e63c127SSorin Basca in the context of this counter definition. 55*7e63c127SSorin Basca</p> 56*7e63c127SSorin Basca 57*7e63c127SSorin Basca<p> 58*7e63c127SSorin Basca If the class files haven been compiled with debug information decision points 59*7e63c127SSorin Basca can be mapped to source lines and highlighted accordingly: 60*7e63c127SSorin Basca</p> 61*7e63c127SSorin Basca 62*7e63c127SSorin Basca<ul> 63*7e63c127SSorin Basca <li>No coverage: No branches in the line has been executed (red diamond)</li> 64*7e63c127SSorin Basca <li>Partial coverage: Only a part of the branches in the line have been 65*7e63c127SSorin Basca executed (yellow diamond)</li> 66*7e63c127SSorin Basca <li>Full coverage: All branches in the line have been executed (green diamond)</li> 67*7e63c127SSorin Basca</ul> 68*7e63c127SSorin Basca 69*7e63c127SSorin Basca<h2>Cyclomatic Complexity</h2> 70*7e63c127SSorin Basca 71*7e63c127SSorin Basca<p> 72*7e63c127SSorin Basca JaCoCo also calculates cyclomatic complexity for each non-abstract method and 73*7e63c127SSorin Basca summarizes complexity for classes, packages and groups. According to its 74*7e63c127SSorin Basca definition by 75*7e63c127SSorin Basca <a href="http://hissa.nist.gov/HHRFdata/Artifacts/ITLdoc/235/title.htm">McCabe1996</a> 76*7e63c127SSorin Basca cyclomatic complexity is the minimum number of paths that can, in (linear) 77*7e63c127SSorin Basca combination, generate all possible paths through a method. Thus the 78*7e63c127SSorin Basca complexity value can serve as an indication for the number of unit test cases 79*7e63c127SSorin Basca to fully cover a certain piece of software. Complexity figures can always be 80*7e63c127SSorin Basca calculated, even in absence of debug information in the class files. 81*7e63c127SSorin Basca</p> 82*7e63c127SSorin Basca 83*7e63c127SSorin Basca<p> 84*7e63c127SSorin Basca The formal definition of the cyclomatic complexity v(G) is based on the 85*7e63c127SSorin Basca representation of a method's control flow graph as a directed graph: 86*7e63c127SSorin Basca</p> 87*7e63c127SSorin Basca 88*7e63c127SSorin Basca<blockquote> 89*7e63c127SSorin Basca <p> 90*7e63c127SSorin Basca v(G) = E - N + 2 91*7e63c127SSorin Basca </p> 92*7e63c127SSorin Basca</blockquote> 93*7e63c127SSorin Basca 94*7e63c127SSorin Basca<p> 95*7e63c127SSorin Basca Where E is the number of edges and N the number of nodes. JaCoCo calculates 96*7e63c127SSorin Basca cyclomatic complexity of a method with the following equivalent equation based 97*7e63c127SSorin Basca on the number of branches (B) and the number of decision points (D): 98*7e63c127SSorin Basca</p> 99*7e63c127SSorin Basca 100*7e63c127SSorin Basca<blockquote> 101*7e63c127SSorin Basca <p> 102*7e63c127SSorin Basca v(G) = B - D + 1 103*7e63c127SSorin Basca </p> 104*7e63c127SSorin Basca</blockquote> 105*7e63c127SSorin Basca 106*7e63c127SSorin Basca<p> 107*7e63c127SSorin Basca Based on the coverage status of each branch JaCoCo also calculates covered and 108*7e63c127SSorin Basca missed complexity for each method. Missed complexity again is an indication 109*7e63c127SSorin Basca for the number of test cases missing to fully cover a module. Note that as 110*7e63c127SSorin Basca JaCoCo does not consider exception handling as branches try/catch blocks will 111*7e63c127SSorin Basca also not increase complexity. 112*7e63c127SSorin Basca</p> 113*7e63c127SSorin Basca 114*7e63c127SSorin Basca<h2>Lines</h2> 115*7e63c127SSorin Basca 116*7e63c127SSorin Basca<p> 117*7e63c127SSorin Basca For all class files that have been compiled with debug information, coverage 118*7e63c127SSorin Basca information for individual lines can be calculated. A source line is 119*7e63c127SSorin Basca considered executed when at least one instruction that is assigned to this 120*7e63c127SSorin Basca line has been executed. 121*7e63c127SSorin Basca</p> 122*7e63c127SSorin Basca 123*7e63c127SSorin Basca<p> 124*7e63c127SSorin Basca Due to the fact that a single line typically compiles to multiple byte code 125*7e63c127SSorin Basca instructions the source code highlighting shows three different status for 126*7e63c127SSorin Basca each line containing source code: 127*7e63c127SSorin Basca</p> 128*7e63c127SSorin Basca 129*7e63c127SSorin Basca<ul> 130*7e63c127SSorin Basca <li>No coverage: No instruction in the line has been executed (red 131*7e63c127SSorin Basca background)</li> 132*7e63c127SSorin Basca <li>Partial coverage: Only a part of the instruction in the line have been 133*7e63c127SSorin Basca executed (yellow background)</li> 134*7e63c127SSorin Basca <li>Full coverage: All instructions in the line have been executed (green 135*7e63c127SSorin Basca background)</li> 136*7e63c127SSorin Basca</ul> 137*7e63c127SSorin Basca 138*7e63c127SSorin Basca<p> 139*7e63c127SSorin Basca Depending on source formatting a single line of a source code may refer to 140*7e63c127SSorin Basca multiple methods or multiple classes. Therefore the line count of methods 141*7e63c127SSorin Basca cannot be simply added to obtain the total number for the containing class. 142*7e63c127SSorin Basca The same holds true for the lines of multiple classes within a single source 143*7e63c127SSorin Basca file. JaCoCo calculates line coverage for classes and source file based on the 144*7e63c127SSorin Basca actual source lines covered. 145*7e63c127SSorin Basca</p> 146*7e63c127SSorin Basca 147*7e63c127SSorin Basca<h2>Methods</h2> 148*7e63c127SSorin Basca 149*7e63c127SSorin Basca<p> 150*7e63c127SSorin Basca Each non-abstract method contains at least one instruction. A method is 151*7e63c127SSorin Basca considered as executed when at least one instruction has been executed. As 152*7e63c127SSorin Basca JaCoCo works on byte code level also constructors and static initializers are 153*7e63c127SSorin Basca counted as methods. Some of these methods may not have a direct correspondence 154*7e63c127SSorin Basca in Java source code, like implicit and thus generated default constructors or 155*7e63c127SSorin Basca initializers for constants. 156*7e63c127SSorin Basca</p> 157*7e63c127SSorin Basca 158*7e63c127SSorin Basca<h2>Classes</h2> 159*7e63c127SSorin Basca 160*7e63c127SSorin Basca<p> 161*7e63c127SSorin Basca A class is considered as executed when at least one of its methods has been 162*7e63c127SSorin Basca executed. Note that JaCoCo considers constructors as well as static 163*7e63c127SSorin Basca initializers as methods. As Java interface types may contain static 164*7e63c127SSorin Basca initializers such interfaces are also considered as executable classes. 165*7e63c127SSorin Basca</p> 166*7e63c127SSorin Basca 167*7e63c127SSorin Basca</div> 168*7e63c127SSorin Basca<div class="footer"> 169*7e63c127SSorin Basca <span class="right"><a href="${jacoco.home.url}">JaCoCo</a> ${qualified.bundle.version}</span> 170*7e63c127SSorin Basca <a href="license.html">Copyright</a> © ${copyright.years} Mountainminds GmbH & Co. KG and Contributors 171*7e63c127SSorin Basca</div> 172*7e63c127SSorin Basca 173*7e63c127SSorin Basca</body> 174*7e63c127SSorin Basca</html> 175
