| Marc R. Hoffmann | c4b2078 | 2009-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" />
|
| 7 | <title>JaCoCo - Coverage Counter</title>
|
| 8 | </head>
|
| 9 | <body>
|
| 10 |
|
| 11 | <div class="breadcrumb">
|
| 12 | <a href="../index.html" class="el_session">JaCoCo</a> >
|
| 13 | <a href="index.html" class="el_group">Documentation</a> >
|
| 14 | <span class="el_source">Coverage Counters</span>
|
| 15 | </div>
|
| Marc R. Hoffmann | 17be269 | 2010-02-02 05:44:47 +0000 | [diff] [blame] | 16 | <div id="content">
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 17 |
|
| 18 | <h1>Coverage Counters</h1>
|
| 19 |
|
| 20 | <p>
|
| 21 | JaCoCo uses a set of different counters to calculate coverage metrics. The
|
| 22 | foundation of all counters are so called <i>basic blocks</i>. All other
|
| 23 | counters are derived from the <i>basic block</i> coverage information. While
|
| 24 | JaCoCo counters appear to be closely related to Java source code they are
|
| 25 | actually only derived from Java class files. In cases where the Java compiler
|
| 26 | creates so called <i>synthetic</i> code to reflect certain Java language
|
| 27 | constructs counters may therefore show unexpected results.
|
| 28 | </p>
|
| 29 |
|
| 30 | <h2>Basic Blocks</h2>
|
| 31 |
|
| 32 | <p>
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 33 | A basic block – mostly just referred to as <i>block</i> in the APIs and
|
| 34 | reports – represents a consecutive sequence of byte code instructions
|
| 35 | and is a unit that will either execute completely or not all. The single
|
| 36 | exception from this definition occurs when the java exception mechanism comes
|
| 37 | to action (i.e. a java exception "flies"). This always interrupts the current
|
| 38 | blocks execution. The boundaries between blocks are
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 39 | </p>
|
| 40 |
|
| 41 | <ul>
|
| 42 | <li>return instructions,</li>
|
| 43 | <li>throw instructions,</li>
|
| 44 | <li>(conditional) jump instructions and</li>
|
| 45 | <li>target labels referred from jump, try/catch or switch instructions.</li>
|
| 46 | </ul>
|
| 47 |
|
| 48 | <p>
|
| 49 | The JaCoCo instrumentation mechanism inserts a probe at the end of every
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 50 | block. When the probe gets executed the block is considered executed.
|
| 51 | This results in the major drawback of basic block based probes:
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 52 | </p>
|
| 53 |
|
| 54 | <p class="hint">
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 55 | Blocks that encounter an exception somewhere in the middle of their execution
|
| 56 | will be considered as not executed. This is correct as the block actually
|
| 57 | didn't get executed but JaCoCo won't be able to tell which lines of the block
|
| 58 | executed and which didn't.
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 59 | </p>
|
| 60 |
|
| 61 | <p>
|
| 62 | Beside this, basic block code coverage has been proven to work very
|
| 63 | efficiently even with huge applications under test. The reasons are that the
|
| 64 | blocks can be easily determined at instrumentation time. The amount of
|
| 65 | inserted probes offer a good tradeoff between runtime overhead and report
|
| 66 | granularity. And last but not least basic blocks can be determined even if the
|
| 67 | class files have not been compiled in debug mode and therefore do not contain
|
| 68 | any source line information. Therefore all coverage counters except the line
|
| 69 | counter will work also in this case and provide useful coverage information
|
| 70 | e.g. for binary third party libraries.
|
| 71 | </p>
|
| 72 |
|
| 73 | <h2>Instructions</h2>
|
| 74 |
|
| 75 | <p>
|
| 76 | For each block the number of included byte code instructions can be easily
|
| 77 | determined. The instruction counter summarizes the number of single byte code
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 78 | instructions that belong to executed blocks. As blocks may be of different
|
| 79 | length, instructions give a good measure of block size and can serve as a
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 80 | replacement when no line information is available.
|
| 81 | </p>
|
| 82 |
|
| 83 | <h2>Lines</h2>
|
| 84 |
|
| 85 | <p>
|
| 86 | For all class files that have been compiled in debug mode with source line
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 87 | information, coverage information for individual lines can be derived from
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 88 | basic blocks. Each block may span one ore multiple lines of source code. On
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 89 | the other hand a single line of source may belong to multiple blocks. A source
|
| 90 | line is considered executed when at least one block that includes this line
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 91 | has been executed.
|
| 92 | </p>
|
| 93 |
|
| 94 | <p>
|
| 95 | Due to the fact that a single line may belong to more that one block
|
| 96 | <i>partial</i> coverage can happen if some of the blocks are executed while
|
| 97 | others are not. This is typically the case with boolean expressions. While
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 98 | partially covered lines are seen as executed due to the definition in the
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 99 | previous paragraph, they are highlighted in yellow color in the coverage
|
| 100 | reports.
|
| 101 | </p>
|
| 102 |
|
| 103 | <h2>Methods</h2>
|
| 104 |
|
| 105 | <p>
|
| 106 | Each non-abstract method consists of at least one block. A method is
|
| 107 | considered as executed when at least one block has been executed. As JaCoCo
|
| 108 | works on byte code level also constructors and static initializers are counted
|
| 109 | as methods. Some of these methods may not have a direct correspondence in Java
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 110 | source code, like implicit and thus generated default constructors or initializers
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 111 | for constants.
|
| 112 | </p>
|
| 113 |
|
| 114 | <h2>Classes</h2>
|
| 115 |
|
| 116 | <p>
|
| Radek Liba | ad5fbc9 | 2009-10-26 13:26:53 +0000 | [diff] [blame] | 117 | A class is considered as executed when at least one of its methods has been
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 118 | executed. Note that JaCoCo considers constructors as well as static
|
| 119 | initializers as methods. As Java interface types may contain static
|
| 120 | initializers such interfaces are also considered as executable classes.
|
| 121 | </p>
|
| 122 |
|
| 123 |
|
| Marc R. Hoffmann | 17be269 | 2010-02-02 05:44:47 +0000 | [diff] [blame] | 124 | </div>
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 125 | <div class="footer">
|
| Marc R. Hoffmann | b623ffb | 2010-05-06 19:48:08 +0000 | [diff] [blame^] | 126 | <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
|
| Marc R. Hoffmann | df6ff96 | 2010-04-09 15:31:22 +0000 | [diff] [blame] | 127 | <a href="license.html">Copyright</a> © @copyright.years@ Mountainminds GmbH & Co. KG and Contributors
|
| Marc R. Hoffmann | c4b2078 | 2009-10-02 13:28:46 +0000 | [diff] [blame] | 128 | </div>
|
| 129 |
|
| 130 | </body>
|
| 131 | </html> |