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>
 <div id="content">

 <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>
   A basic block &ndash; mostly just referred to as <i>block</i> in the APIs and
   reports &ndash; represents a consecutive sequence of byte code instructions
   and is a unit that will either execute completely or not all. The single
   exception from this definition occurs when the java exception mechanism comes
   to action (i.e. a java exception "flies"). This always interrupts the current
   blocks execution. 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 executed the block is considered 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 of their execution
   will be considered as not executed. This is correct as the block actually
   didn't get executed but JaCoCo won't be able to tell which lines of the block
   executed and which didn't.
 </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 be of different
   length, instructions give a good measure of block size 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 derived from
   basic blocks. Each block may span one ore multiple lines of source code. On
   the other hand a single line of source may belong to multiple blocks. A source
   line is considered 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 covered lines are seen 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 implicit and thus generated default constructors or initializers
   for constants.
 </p>

 <h2>Classes</h2>

 <p>
   A class is considered as executed when at least one of its methods 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>
 <div class="footer">
   <div class="versioninfo"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</div>
   <a href="license.html">Copyright</a> &copy; @copyright.years@ 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>
	<div id="content">

	<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>
	A basic block – mostly just referred to as <i>block</i> in the APIs and
	reports – represents a consecutive sequence of byte code instructions
	and is a unit that will either execute completely or not all. The single
	exception from this definition occurs when the java exception mechanism comes
	to action (i.e. a java exception "flies"). This always interrupts the current
	blocks execution. 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 executed the block is considered 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 of their execution
	will be considered as not executed. This is correct as the block actually
	didn't get executed but JaCoCo won't be able to tell which lines of the block
	executed and which didn't.
	</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 be of different
	length, instructions give a good measure of block size 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 derived from
	basic blocks. Each block may span one ore multiple lines of source code. On
	the other hand a single line of source may belong to multiple blocks. A source
	line is considered 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 covered lines are seen 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 implicit and thus generated default constructors or initializers
	for constants.
	</p>

	<h2>Classes</h2>

	<p>
	A class is considered as executed when at least one of its methods 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>
	<div class="footer">
	<div class="versioninfo"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</div>
	<a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors
	</div>

	</body>
	</html>