diff options
| author | Marc R. Hoffmann <hoffmann@mountainminds.com> | 2009-10-02 13:28:46 +0000 |
|---|---|---|
| committer | Marc R. Hoffmann <hoffmann@mountainminds.com> | 2009-10-02 13:28:46 +0000 |
| commit | c4b2078689a7dbdc27c10ca4938c27fc01e64f22 (patch) | |
| tree | 04b35b943ff6c82f997f7738935d4374c6d5a9b0 /org.jacoco.doc/docroot/doc/counters.html | |
| parent | 5d43ad44e9f73cab0e8fd18b3143036a2f23e6cf (diff) | |
| download | jacoco-c4b2078689a7dbdc27c10ca4938c27fc01e64f22.tar.gz | |
Coverage counter definitions, link to XML report, new outline for documentation.
Diffstat (limited to 'org.jacoco.doc/docroot/doc/counters.html')
| -rw-r--r-- | org.jacoco.doc/docroot/doc/counters.html | 127 |
1 files changed, 127 insertions, 0 deletions
diff --git a/org.jacoco.doc/docroot/doc/counters.html b/org.jacoco.doc/docroot/doc/counters.html new file mode 100644 index 00000000..9fcc12e9 --- /dev/null +++ b/org.jacoco.doc/docroot/doc/counters.html @@ -0,0 +1,127 @@ +<?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>
\ No newline at end of file |