Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / jacoco / 1a56c9619e03ee3e4e1b539e592e7d8b51f53a7b / . / org.jacoco.doc / docroot / doc / faq.html
blob: 0e910fb03f37b4f9b7558b118a49208256c57d73 [file] [log] [blame]
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]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" />
Evgeny Mandrikov8b212982016-06-12 17:55:49 +0200[diff] [blame]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" />
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]8 <title>JaCoCo - FAQ</title>
9</head>
10<body>
11
12<div class="breadcrumb">
13 <a href="../index.html" class="el_report">JaCoCo</a> &gt;
14 <a href="index.html" class="el_group">Documentation</a> &gt;
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
Marc R. Hoffmann3de67422018-02-15 01:11:57 +0100[diff] [blame]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 been implemented in master branch and will be available
35 with the next release. And in the meantime you can test latest build of
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
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]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.
Marc R. Hoffmann08db74b2013-01-16 07:58:13 +0100[diff] [blame]44</p>
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]45
Marc R. Hoffmann2cd6b612014-03-12 22:36:32 +0100[diff] [blame]46<h3>What Java versions are supported by JaCoCo?</h3>
47<p>
Evgeny Mandrikove0681662018-03-21 05:23:26 +0100[diff] [blame]48 JaCoCo supports Java class files from version 1.0 to 10. However the minimum
Marc R. Hoffmann2cd6b612014-03-12 22:36:32 +0100[diff] [blame]49 JRE version required by the JaCoCo runtime (e.g. the agent) and the JaCoCo
50 tools is 1.5. Also note that class files under test from version 1.6 and above
51 have to contain valid stackmap frames.
52</p>
53
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]54<h3>Why do I get the error "Can't add different class with same name"?</h3>
55<p>
56 For coverage report generation all classes within a group must have unique
57 names. You get this error during report generation if JaCoCo is supplied with
58 multiple different class files with the same name. To fix this remove those
59 duplicate classes or create separate reports or report groups for each version.
Marc R. Hoffmann08db74b2013-01-16 07:58:13 +0100[diff] [blame]60</p>
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]61
Marc R. Hoffmann87311452015-02-16 09:09:25 +0100[diff] [blame]62<h3>Source code lines with exceptions show no coverage. Why?</h3>
Marc R. Hoffmannf6787ed2012-11-13 23:03:55 +0100[diff] [blame]63<p>
64 JaCoCo determines code execution with so called probes. Probes are inserted
65 into the control flow at certain positions. Code is considered as executed
66 when a subsequent probe has been executed. In case of exceptions such a
Marc R. Hoffmann87311452015-02-16 09:09:25 +0100[diff] [blame]67 sequence of instructions is aborted somewhere in the middle and the
68 corresponding line of source code is not marked as covered.
Marc R. Hoffmannf6787ed2012-11-13 23:03:55 +0100[diff] [blame]69</p>
70
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]71<h3>Why does the coverage report not show line coverage figures?</h3>
72<p>
Marc R. Hoffmann9a7379b2012-09-21 21:48:35 +0200[diff] [blame]73 JaCoCo is based on class files analysis. To calculate line coverage class
74 files must contain line number attributes. For this your code must be compiled
75 with debug information.
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]76</p>
77
Marc R. Hoffmannfa48e772014-03-13 12:31:30 +0100[diff] [blame]78<h3>Why does the coverage report not show highlighted source code?</h3>
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]79<p>
80 Make sure the following prerequisites are fulfilled to get source code
81 highlighting in JaCoCo coverage reports:
82</p>
83<ul>
84 <li>Class files must be compiled with debug information to contain line numbers.</li>
85 <li>Source files must be properly supplied at report generation time. I.e.
86 specified source folders must be the direct parent of the folders that
87 define the Java packages.</li>
88</ul>
89
90<h3>Why does a class show as not covered although it has been executed?</h3>
91<p>
92 First make sure execution data has been collected. For this select the
93 <i>Sessions</i> link on the top right corner of the HTML report and check
94 whether the class in question is listed. If it is listed but not linked the
95 class at execution time is a different class file. Make sure you're using the
Marc R. Hoffmann9a7379b2012-09-21 21:48:35 +0200[diff] [blame]96 exact same class file at runtime as for report generation. Note that some
97 tools (e.g. EJB containers, mocking frameworks) might modify your class files
Marc R. Hoffmannfa48e772014-03-13 12:31:30 +0100[diff] [blame]98 at runtime. Please see the chapter about <a href="classids.html"> class
99 ids</a> for a detailed discussion.
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]100</p>
101
102<h3>Why are Java interface types not shown in the coverage reports?</h3>
103<p>
104 Java interface methods do not contain code, therefore code coverage cannot
105 be evaluated. Indeed code coverage is recorded for the implementation classes.
106 The same applies to abstract methods in abstract classes.
107</p>
108
Marc R. Hoffmann9a7379b2012-09-21 21:48:35 +0200[diff] [blame]109<h3>Can I collect coverage information without stopping the JVM?</h3>
110<p>
Marc R. Hoffmann0974a252014-12-14 11:46:00 +0100[diff] [blame]111 Yes, there are two possible ways: The JaCoCo <a href="agent.html">agent</a>
112 can be configured for remote control via TCP/IP sockets. This allows to
113 collect execution data at any point in time from a running JVM. The
114 <a href="ant.html#dump"><code>dump</code> Ant task</a> or the
115 <a href="dump-mojo.html"><code>dump</code> Maven goal</a> can be used to
116 request dumps. The remote control feature also allows you to reset execution
117 data.
118</p>
119<p>
120 Alternatively the JaCoCo <a href="agent.html">agent</a> can be configured to
121 expose some functionality via JMX (<code>jmx=true</code>). The bean
122 <code><a href="./api/org/jacoco/agent/rt/IAgent.html">org.jacoco:type=Runtime</a></code>
123 provides operations to dump and reset execution data at any point in time.
Marc R. Hoffmann9a7379b2012-09-21 21:48:35 +0200[diff] [blame]124</p>
125
Marc R. Hoffmann08db74b2013-01-16 07:58:13 +0100[diff] [blame]126<h3>My code uses reflection. Why does it fail when I execute it with JaCoCo?</h3>
127<p>
128 To collect execution data JaCoCo instruments the classes under test which adds
129 two members to the classes: A private static field <code>$jacocoData</code>
130 and a private static method <code>$jacocoInit()</code>. Both members are
131 marked as synthetic.
132</p>
133<p>
134 Please change your code to ignore synthetic members. This is a good practice
135 anyways as also the Java compiler creates synthetic members in certain
136 situation.
137</p>
138
Marc R. Hoffmann0974a252014-12-14 11:46:00 +0100[diff] [blame]139<h3>Why do I get an error while instrumenting certain Java classes?</h3>
140<p>
141 JaCoCo can instrument valid class files only. Class files with syntactical or
142 semantical error will typically lead to exceptions. In certain areas JaCoCo is
143 more restrictive then the JVM: JaCoCo expects valid so-called "stackmap
144 frame" information in class files of version 1.6 or higher. In turn JaCoCo
145 instrumented classes are expected to conform the specification.
146</p>
147<p>
148 Invalid class files are typically created by some frameworks which do not
149 properly adjust stackmap frames when manipulating bytecode.
150</p>
151
Marc R. Hoffmann2ed0ccb2014-10-31 07:56:34 +0100[diff] [blame]152<h3>Does JaCoCo run on the IBM JRE J9 and WebSphere?</h3>
153<p>
154 It does. To make the JaCoCo agent work please set the VM option
Marc R. Hoffmannf6bcb212014-12-16 02:56:17 +0100[diff] [blame]155 <code>-Xshareclasses:none</code>.
Marc R. Hoffmann2ed0ccb2014-10-31 07:56:34 +0100[diff] [blame]156</p>
157
Marc R. Hoffmann86856fe2017-07-18 22:55:38 +0200[diff] [blame]158<h3>Why do I get a <code>NoClassDefFoundError</code> or
159 <code>ClassNotFoundException</code> for class
160 <code>org.jacoco.agent[...]Offline</code>?</h3>
Marc R. Hoffmann2a3b7562016-08-22 20:58:14 +0200[diff] [blame]161<p>
162 If you use <a href="offline.html">offline instrumentation</a> the instrumented
163 classes get a direct dependency on the JaCoCo runtime. Therefore
164 <code>jacocoagent.jar</code> of the same JaCoCo version must be on the
165 classpath and accessible from by the instrumented classes.
166</p>
167
Marc R. Hoffmannc24df152017-05-05 21:06:34 +0200[diff] [blame]168<h3>Why do I get a <code>StackOverflowError</code> during code coverage analysis?</h3>
169<p>
170 There are two known reasons for this:
171</p>
172<ul>
173 <li>Misconfiguration: If you configure two JaCoCo agents of different releases
174 they will instrument each other and cause a endless recursion. Check the
175 effective java command line and avoid such configurations.</li>
176 <li>Heavy stack usage: JaCoCo instrumentation adds a small runtime overhead
177 by adding a local variable to each method. If your application is already
178 close to the maximum stack size this can eventually lead to an
179 <code>StackOverflowError</code>. Increase the maximum java stack size with
180 the <code>-Xss</code> JVM option.</li>
181</ul>
182
Marc R. Hoffmann0b8331b2012-09-19 20:45:37 +0200[diff] [blame]183</div>
184<div class="footer">
185 <span class="right"><a href="@jacoco.home.url@">JaCoCo</a> @qualified.bundle.version@</span>
186 <a href="license.html">Copyright</a> &copy; @copyright.years@ Mountainminds GmbH &amp; Co. KG and Contributors
187</div>
188
189</body>
190</html>