org.jacoco.doc/docroot/doc/counters.html - platform/external/jacoco - Gitiles

 <?xml version="1.0" encoding="ISO-8859-1" ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml" lang="en">
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
   <link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
   <title>JaCoCo - Coverage Counter</title>
 </head>
 <body>

 <div class="breadcrumb">
   <a href="../index.html" class="el_session">JaCoCo</a> &gt;
   <a href="index.html" class="el_group">Documentation</a> &gt;
   <span class="el_source">Coverage Counters</span>
 </div>

 <h1>Coverage Counters</h1>

 <p>
   JaCoCo uses a set of different counters to calculate coverage metrics. The
   foundation of all counters are so called <i>basic blocks</i>. All other
   counters are derived from the <i>basic block</i> coverage information. While
   JaCoCo counters appear to be closely related to Java source code they are
   actually only derived from Java class files. In cases where the Java compiler
   creates so called <i>synthetic</i> code to reflect certain Java language
   constructs counters may therefore show unexpected results.
 </p>

 <h2>Basic Blocks</h2>

 <p>
   Basic blocks &ndash; mostly just referred to as <i>blocks</i> in the APIs and
   reports &ndash; are consecutive sequences of byte code instructions that will
   normally only executed on-block. The boundaries between blocks are
 </p>

 <ul>
   <li>return instructions,</li>
   <li>throw instructions,</li>
   <li>(conditional) jump instructions and</li>
   <li>target labels referred from jump, try/catch or switch instructions.</li>
 </ul>

 <p>
   The JaCoCo instrumentation mechanism inserts a probe at the end of every
   block. When the probe gets executes the block can be considered as executed.
   Unfortunately the opposite does not hold true: Exceptions might interrupt a
   block somewhere in the middle and the probe will not get executed. This
   results in the major drawback of basic block based probes:
 </p>

 <p class="hint">
   Blocks that encounter an exception somewhere in the middle will be considered
   as not executed.
 </p>

 <p>
   Beside this, basic block code coverage has been proven to work very
   efficiently even with huge applications under test. The reasons are that the
   blocks can be easily determined at instrumentation time. The amount of
   inserted probes offer a good tradeoff between runtime overhead and report
   granularity. And last but not least basic blocks can be determined even if the
   class files have not been compiled in debug mode and therefore do not contain
   any source line information. Therefore all coverage counters except the line
   counter will work also in this case and provide useful coverage information
   e.g. for binary third party libraries.
 </p>

 <h2>Instructions</h2>

 <p>
   For each block the number of included byte code instructions can be easily
   determined. The instruction counter summarizes the number of single byte code
   instructions that belong to executed blocks. As blocks may have different
   lengths instructions represent the size of the blocks and can serve as a
   replacement when no line information is available.
 </p>

 <h2>Lines</h2>

 <p>
   For all class files that have been compiled in debug mode with source line
   information, coverage information for individual lines can be calculated from
   basic blocks. Each block may span one ore multiple lines of source code. On
   the other hand a single line of source my belong to multiple blocks. A source
   line is considered as executed when at least one block that includes this line
   has been executed.
 </p>

 <p>
   Due to the fact that a single line may belong to more that one block
   <i>partial</i> coverage can happen if some of the blocks are executed while
   others are not. This is typically the case with boolean expressions. While
   partially coverage lines are counted as executed due to the definition in the
   previous paragraph, they are highlighted in yellow color in the coverage
   reports.
 </p>

 <h2>Methods</h2>

 <p>
   Each non-abstract method consists of at least one block. A method is
   considered as executed when at least one block has been executed. As JaCoCo
   works on byte code level also constructors and static initializers are counted
   as methods. Some of these methods may not have a direct correspondence in Java
   source code, like implicitly generated default constructors or initializers
   for constants.
 </p>

 <h2>Classes</h2>

 <p>
   A class is considered as executed when at least one of its method has been
   executed. Note that JaCoCo considers constructors as well as static
   initializers as methods. As Java interface types may contain static
   initializers such interfaces are also considered as executable classes.
 </p>


 <div class="footer">
   <div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
   <a href="license.html">Copyright</a> &copy; 2009 Mountainminds GmbH &amp; Co. KG and Contributors
 </div>

 </body>
 </html>
	<?xml version="1.0" encoding="ISO-8859-1" ?>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
	<head>
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
	<link rel="stylesheet" href=".resources/doc.css" charset="ISO-8859-1" type="text/css" />
	<title>JaCoCo - Coverage Counter</title>
	</head>
	<body>

	<div class="breadcrumb">
	<a href="../index.html" class="el_session">JaCoCo</a> >
	<a href="index.html" class="el_group">Documentation</a> >
	<span class="el_source">Coverage Counters</span>
	</div>

	<h1>Coverage Counters</h1>

	<p>
	JaCoCo uses a set of different counters to calculate coverage metrics. The
	foundation of all counters are so called <i>basic blocks</i>. All other
	counters are derived from the <i>basic block</i> coverage information. While
	JaCoCo counters appear to be closely related to Java source code they are
	actually only derived from Java class files. In cases where the Java compiler
	creates so called <i>synthetic</i> code to reflect certain Java language
	constructs counters may therefore show unexpected results.
	</p>

	<h2>Basic Blocks</h2>

	<p>
	Basic blocks – mostly just referred to as <i>blocks</i> in the APIs and
	reports – are consecutive sequences of byte code instructions that will
	normally only executed on-block. The boundaries between blocks are
	</p>

	<ul>
	<li>return instructions,</li>
	<li>throw instructions,</li>
	<li>(conditional) jump instructions and</li>
	<li>target labels referred from jump, try/catch or switch instructions.</li>
	</ul>

	<p>
	The JaCoCo instrumentation mechanism inserts a probe at the end of every
	block. When the probe gets executes the block can be considered as executed.
	Unfortunately the opposite does not hold true: Exceptions might interrupt a
	block somewhere in the middle and the probe will not get executed. This
	results in the major drawback of basic block based probes:
	</p>

	<p class="hint">
	Blocks that encounter an exception somewhere in the middle will be considered
	as not executed.
	</p>

	<p>
	Beside this, basic block code coverage has been proven to work very
	efficiently even with huge applications under test. The reasons are that the
	blocks can be easily determined at instrumentation time. The amount of
	inserted probes offer a good tradeoff between runtime overhead and report
	granularity. And last but not least basic blocks can be determined even if the
	class files have not been compiled in debug mode and therefore do not contain
	any source line information. Therefore all coverage counters except the line
	counter will work also in this case and provide useful coverage information
	e.g. for binary third party libraries.
	</p>

	<h2>Instructions</h2>

	<p>
	For each block the number of included byte code instructions can be easily
	determined. The instruction counter summarizes the number of single byte code
	instructions that belong to executed blocks. As blocks may have different
	lengths instructions represent the size of the blocks and can serve as a
	replacement when no line information is available.
	</p>

	<h2>Lines</h2>

	<p>
	For all class files that have been compiled in debug mode with source line
	information, coverage information for individual lines can be calculated from
	basic blocks. Each block may span one ore multiple lines of source code. On
	the other hand a single line of source my belong to multiple blocks. A source
	line is considered as executed when at least one block that includes this line
	has been executed.
	</p>

	<p>
	Due to the fact that a single line may belong to more that one block
	<i>partial</i> coverage can happen if some of the blocks are executed while
	others are not. This is typically the case with boolean expressions. While
	partially coverage lines are counted as executed due to the definition in the
	previous paragraph, they are highlighted in yellow color in the coverage
	reports.
	</p>

	<h2>Methods</h2>

	<p>
	Each non-abstract method consists of at least one block. A method is
	considered as executed when at least one block has been executed. As JaCoCo
	works on byte code level also constructors and static initializers are counted
	as methods. Some of these methods may not have a direct correspondence in Java
	source code, like implicitly generated default constructors or initializers
	for constants.
	</p>

	<h2>Classes</h2>

	<p>
	A class is considered as executed when at least one of its method has been
	executed. Note that JaCoCo considers constructors as well as static
	initializers as methods. As Java interface types may contain static
	initializers such interfaces are also considered as executable classes.
	</p>



	<div class="footer">
	<div class="versioninfo"><a href="@HOMEURL@">JaCoCo</a> @VERSION@</div>
	<a href="license.html">Copyright</a> © 2009 Mountainminds GmbH & Co. KG and Contributors
	</div>

	</body>
	</html>