Debian Codegraph @

org.jacoco.doc/docroot/doc/faq.html

raw
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> &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
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> &copy; ${copyright.years} Mountainminds GmbH &amp; Co. KG and Contributors
213 </div>
214
215 </body>
216 </html>