| 1 |
<?xml version="1.0" encoding="UTF-8" ?> |
| 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=UTF-8" /> |
| 6 |
<link rel="stylesheet" href="resources/doc.css" charset="UTF-8" type="text/css" /> |
| 7 |
<link rel="shortcut icon" href="resources/report.gif" type="image/gif" /> |
| 8 |
<title>JaCoCo - FAQ</title> |
| 9 |
</head> |
| 10 |
<body> |
| 11 |
|
| 12 |
<div class="breadcrumb"> |
| 13 |
<a href="../index.html" class="el_report">JaCoCo</a> > |
| 14 |
<a href="index.html" class="el_group">Documentation</a> > |
| 15 |
<span class="el_source">FAQ</span> |
| 16 |
</div> |
| 17 |
<div id="content"> |
| 18 |
|
| 19 |
<h1>FAQ</h1> |
| 20 |
|
| 21 |
<p> |
| 22 |
This is a compilation of questions that have been asked by JaCoCo users |
| 23 |
before. |
| 24 |
</p> |
| 25 |
|
| 26 |
<h3>When will feature X be released?</h3> |
| 27 |
<p> |
| 28 |
JaCoCo is maintained by volunteers in their free time. Since we cannot |
| 29 |
guarantee free capacity, we do not commit to particular release dates. |
| 30 |
Typically, you can expect a couple of releases every year. |
| 31 |
</p> |
| 32 |
<p> |
| 33 |
In the <a href="changes.html">change log</a>, you can see all features |
| 34 |
that have been implemented in master branch and will be available |
| 35 |
with the next release. And in the meantime you can test latest build |
| 36 |
of master branch (<a href="repo.html">Maven SNAPSHOT</a>) and provide |
| 37 |
<a href="support.html">feedback</a> to us. |
| 38 |
</p> |
| 39 |
|
| 40 |
<h3>Does JaCoCo have a plug-in for [Eclipse|Netbeans|Whatever...]?</h3> |
| 41 |
<p> |
| 42 |
See <a href="integrations.html">this list</a> for current integrations with |
| 43 |
various tools. |
| 44 |
</p> |
| 45 |
|
| 46 |
<h3>What Java versions are supported by JaCoCo?</h3> |
| 47 |
<p> |
| 48 |
JaCoCo officially supports Java class files from version 1.0 to 25. Also |
| 49 |
experimental support for class files of version 26 is provided. |
| 50 |
However the minimum JRE version required by the JaCoCo runtime |
| 51 |
(e.g. the agent) and the JaCoCo tools is 1.5. Also note that class files under |
| 52 |
test from version 1.6 and above have to contain valid stackmap frames. |
| 53 |
</p> |
| 54 |
|
| 55 |
<h3>Why do I get the error "Can't add different class with same name"?</h3> |
| 56 |
<p> |
| 57 |
For coverage report generation all classes within a group must have unique |
| 58 |
names. You get this error during report generation if JaCoCo is supplied with |
| 59 |
multiple different class files with the same name. To fix this remove those |
| 60 |
duplicate classes or create separate reports or report groups for each version. |
| 61 |
</p> |
| 62 |
|
| 63 |
<h3>Source code lines with exceptions show no coverage. Why?</h3> |
| 64 |
<p> |
| 65 |
JaCoCo determines code execution with so called probes. Probes are inserted |
| 66 |
into the control flow at certain positions. Code is considered as executed |
| 67 |
when a subsequent probe has been executed. In case of exceptions such a |
| 68 |
sequence of instructions is aborted somewhere in the middle and the |
| 69 |
corresponding lines of source code are not marked as covered. |
| 70 |
</p> |
| 71 |
|
| 72 |
<h3>Why does the coverage report not show line coverage figures?</h3> |
| 73 |
<p> |
| 74 |
JaCoCo is based on class files analysis. To calculate line coverage class |
| 75 |
files must contain line number attributes. For this your code must be compiled |
| 76 |
with debug information. |
| 77 |
</p> |
| 78 |
|
| 79 |
<h3>Why does the coverage report not show highlighted source code?</h3> |
| 80 |
<p> |
| 81 |
Make sure the following prerequisites are fulfilled to get source code |
| 82 |
highlighting in JaCoCo coverage reports: |
| 83 |
</p> |
| 84 |
<ul> |
| 85 |
<li>Class files must be compiled with debug information to contain line numbers.</li> |
| 86 |
<li>Source files must be properly supplied at report generation time. I.e. |
| 87 |
specified source folders must be the direct parent of the folders that |
| 88 |
define the Java packages.</li> |
| 89 |
</ul> |
| 90 |
|
| 91 |
<h3>Why does a class show as not covered although it has been executed?</h3> |
| 92 |
<p> |
| 93 |
First make sure execution data has been collected. For this select the |
| 94 |
<i>Sessions</i> link on the top right corner of the HTML report and check |
| 95 |
whether the class in question is listed. If it is listed but not linked the |
| 96 |
class at execution time is a different class file. Make sure you're using the |
| 97 |
exact same class file at runtime as for report generation. Note that some |
| 98 |
tools (e.g. EJB containers, mocking frameworks) might modify your class files |
| 99 |
at runtime. Please see the chapter about <a href="classids.html"> class |
| 100 |
ids</a> for a detailed discussion. |
| 101 |
</p> |
| 102 |
|
| 103 |
<h3>Why are abstract methods not shown in coverage reports?</h3> |
| 104 |
<p> |
| 105 |
Abstract methods do not contain code, therefore code coverage cannot be |
| 106 |
evaluated. Indeed code coverage is recorded for subclasses implementing these |
| 107 |
methods. The same applies to non-default methods in interfaces. |
| 108 |
</p> |
| 109 |
|
| 110 |
<h3>Can I collect coverage information without stopping the JVM?</h3> |
| 111 |
<p> |
| 112 |
Yes, there are three possible ways: The JaCoCo <a href="agent.html">agent</a> |
| 113 |
can be configured for remote control via TCP/IP sockets. This allows to |
| 114 |
collect execution data at any point in time from a running JVM. The |
| 115 |
<a href="ant.html#dump"><code>dump</code> Ant task</a>, the |
| 116 |
<a href="dump-mojo.html"><code>dump</code> Maven goal</a> and the |
| 117 |
<a href="cli.html">command line interface</a> can be used to request dumps. |
| 118 |
The remote control feature also allows you to reset execution data. |
| 119 |
</p> |
| 120 |
<p> |
| 121 |
Alternatively the JaCoCo <a href="agent.html">agent</a> can be configured to |
| 122 |
expose some functionality via JMX (<code>jmx=true</code>). The bean |
| 123 |
<code><a href="./api/org/jacoco/agent/rt/IAgent.html">org.jacoco:type=Runtime</a></code> |
| 124 |
provides operations to dump and reset execution data at any point in time. |
| 125 |
</p> |
| 126 |
<p> |
| 127 |
In addition JaCoCo provides a <a href="./api/org/jacoco/agent/rt/RT.html">Java API</a> |
| 128 |
to directly access the runtime within the JVM executing the tests. |
| 129 |
</p> |
| 130 |
|
| 131 |
<h3>My code uses reflection. Why does it fail when I execute it with JaCoCo?</h3> |
| 132 |
<p> |
| 133 |
To collect execution data JaCoCo instruments the classes under test which adds |
| 134 |
two members to the classes: A private static field <code>$jacocoData</code> |
| 135 |
and a private static method <code>$jacocoInit()</code>. Both members are |
| 136 |
marked as synthetic. |
| 137 |
</p> |
| 138 |
<p> |
| 139 |
Please change your code to ignore synthetic members. This is a good practice |
| 140 |
anyways as also the Java compiler creates synthetic members in certain |
| 141 |
situation. |
| 142 |
</p> |
| 143 |
|
| 144 |
<h3>Why do I get an error while instrumenting certain Java classes?</h3> |
| 145 |
<p> |
| 146 |
JaCoCo can instrument valid class files only. Class files with syntactical or |
| 147 |
semantical error will typically lead to exceptions. In certain areas JaCoCo is |
| 148 |
more restrictive then the JVM: JaCoCo expects valid so-called "stackmap |
| 149 |
frame" information in class files of version 1.6 or higher. In turn JaCoCo |
| 150 |
instrumented classes are expected to conform the specification. |
| 151 |
</p> |
| 152 |
<p> |
| 153 |
Invalid class files are typically created by some frameworks which do not |
| 154 |
properly adjust stackmap frames when manipulating bytecode. |
| 155 |
</p> |
| 156 |
|
| 157 |
<h3>Does JaCoCo run on the IBM JRE J9 and WebSphere?</h3> |
| 158 |
<p> |
| 159 |
It does. To make the JaCoCo agent work please set the VM option |
| 160 |
<code>-Xshareclasses:none</code>. |
| 161 |
</p> |
| 162 |
|
| 163 |
<h3>Why do I get a <code>NoClassDefFoundError</code> or |
| 164 |
<code>ClassNotFoundException</code> for class |
| 165 |
<code>org.jacoco.agent[...]Offline</code>?</h3> |
| 166 |
<p> |
| 167 |
If you use <a href="offline.html">offline instrumentation</a> the instrumented |
| 168 |
classes get a direct dependency on the JaCoCo runtime. Therefore |
| 169 |
<code>jacocoagent.jar</code> of the same JaCoCo version must be on the |
| 170 |
classpath and accessible from by the instrumented classes. |
| 171 |
</p> |
| 172 |
|
| 173 |
<h3>Why do I get a <code>StackOverflowError</code> during code coverage analysis?</h3> |
| 174 |
<p> |
| 175 |
There are two known reasons for this: |
| 176 |
</p> |
| 177 |
<ul> |
| 178 |
<li>Misconfiguration: If you configure two JaCoCo agents of different releases |
| 179 |
they will instrument each other and cause a endless recursion. Check the |
| 180 |
effective java command line and avoid such configurations.</li> |
| 181 |
<li>Heavy stack usage: JaCoCo instrumentation adds a small runtime overhead |
| 182 |
by adding a local variable to each method. If your application is already |
| 183 |
close to the maximum stack size this can eventually lead to an |
| 184 |
<code>StackOverflowError</code>. Increase the maximum java stack size with |
| 185 |
the <code>-Xss</code> JVM option.</li> |
| 186 |
</ul> |
| 187 |
|
| 188 |
<h3>Why do I see classes in the coverage report although I excluded them in the JaCoCo agent configuration?</h3> |
| 189 |
<p> |
| 190 |
The <code>includes</code> and <code>excludes</code> options of the |
| 191 |
<a href="agent.html">JaCoCo agent</a> determine for which classes execution |
| 192 |
data is collected. Except for technical corner cases these options are |
| 193 |
normally not required. If you exclude classes, no execution data is collected |
| 194 |
for them. |
| 195 |
</p> |
| 196 |
<p> |
| 197 |
Report creation is a separate step where all class files which should show up |
| 198 |
in the report are explicitly provided. Coverage is determined from the |
| 199 |
provided execution data. If execution data is missing for a particular class, |
| 200 |
this class is shown as not covered because the report generator cannot |
| 201 |
distinguish whether the class was excluded from instrumentation or not executed. |
| 202 |
</p> |
| 203 |
|
| 204 |
<p> |
| 205 |
If you want to exclude classes from the report please configure the |
| 206 |
respective report generation tool accordingly. |
| 207 |
</p> |
| 208 |
|
| 209 |
</div> |
| 210 |
<div class="footer"> |
| 211 |
<span class="right"><a href="${jacoco.home.url}">JaCoCo</a> ${qualified.bundle.version}</span> |
| 212 |
<a href="license.html">Copyright</a> © ${copyright.years} Mountainminds GmbH & Co. KG and Contributors |
| 213 |
</div> |
| 214 |
|
| 215 |
</body> |
| 216 |
</html> |