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