1Devel::Cover(3) User Contributed Perl Documentation Devel::Cover(3)
2
6 Devel::Cover - Code coverage metrics for Perl
7
9 version 1.03
10
12 To get coverage for an uninstalled module:
13 cover -test
15 or
17 cover -delete
19 HARNESS_PERL_SWITCHES=-MDevel::Cover make test
20 cover
21 To get coverage for an uninstalled module which uses Module::Build
23 (0.26 or later):
24 ./Build testcover
26 If the module does not use the t/*.t framework:
28 PERL5OPT=-MDevel::Cover make test
30 If you want to get coverage for a program:
32 perl -MDevel::Cover yourprog args
34 cover
35 To alter default values:
37 perl -MDevel::Cover=-db,cover_db,-coverage,statement,time yourprog args
39
41 This module provides code coverage metrics for Perl. Code coverage
42 metrics describe how thoroughly tests exercise code. By using
43 Devel::Cover you can discover areas of code not exercised by your tests
44 and determine which tests to create to increase coverage. Code
45 coverage can be considered an indirect measure of quality.
46 Although it is still being developed, Devel::Cover is now quite stable
48 and provides many of the features to be expected in a useful coverage
49 tool.
50 Statement, branch, condition, subroutine, and pod coverage information
52 is reported. Statement and subroutine coverage data should be
53 accurate. Branch and condition coverage data should be mostly accurate
54 too, although not always what one might initially expect. Pod coverage
55 comes from Pod::Coverage. If Pod::Coverage::CountParents is available
56 it will be used instead. Coverage data for other criteria are not yet
57 collected.
58 The cover program can be used to generate coverage reports.
60 Devel::Cover ships with a number of different reports including various
61 types of HTML output, textual reports, a report to display missing
62 coverage in the same format as compilation errors and a report to
63 display coverage information within the Vim editor.
64 It is possible to add annotations to reports, for example you can add a
66 column to an HTML report showing who last changed a line, as determined
67 by git blame. Some annotation modules are shipped with Devel::Cover
68 and you can easily create your own.
69 The gcov2perl program can be used to convert gcov files to
71 "Devel::Cover" databases. This allows you to display your C or XS code
72 coverage together with your Perl coverage, or to use any of the
73 Devel::Cover reports to display your C coverage data.
74 Code coverage data are collected by replacing perl ops with functions
76 which count how many times the ops are executed. These data are then
77 mapped back to reality using the B compiler modules. There is also a
78 statement profiling facility which should not be relied on. For proper
79 profiling use Devel::NYTProf. Previous versions of Devel::Cover
80 collected coverage data by replacing perl's runops function. It is
81 still possible to switch to that mode of operation, but this now gets
82 little testing and will probably be removed soon. You probably don't
83 care about any of this.
84 The most appropriate mailing list on which to discuss this module would
86 be perl-qa. See <http://lists.perl.org/list/perl-qa.html>.
87 The Devel::Cover repository can be found at
89 <http://github.com/pjcj/Devel--Cover>. This is also where problems
90 should be reported.
91
93 REQUIREMENTS
94 · Perl 5.6.1 or greater. Perl 5.8.8 or greater is recommended.
95 Perl 5.7 is unsupported. Perl 5.8.8 or greater is recommended.
97 Perl 5.8.7 has problems and may crash. Whilst Perl 5.6 should
98 mostly work you will probably miss out on coverage information
99 which would be available using a more modern version and will
100 likely run into bugs in perl. Devel::Cover support for unsupported
101 Perl versions may be removed at any time, but I try to keep older
102 versions running provided this does not cause undue difficulty i
103 other areas.
104 Different versions of perl may give slightly different results due
106 to changes in the op tree.
107 · The ability to compile XS extensions.
109 This means a working C compiler and make program at least. If you
111 built perl from source you will have these already and they will be
112 used automatically. If your perl was built in some other way, for
113 example you may have installed it using your Operating System's
114 packaging mechanism, you will need to ensure that the appropriate
115 tools are installed.
116 · Storable and Digest::MD5
118 Both are in the core in Perl 5.8.0 and above.
120 OPTIONAL MODULES
122 · Template, and either PPI::HTML or Perl::Tidy
123 Needed if you want syntax highlighted HTML reports.
125 · Pod::Coverage (0.06 or above) or Pod::Coverage::CountParents
127 One is needed if you want Pod coverage. If
129 Pod::Coverage::CountParents is installed, it is preferred.
130 · Test::More
132 Required if you want to run Devel::Cover's own tests.
134 · Test::Warn
136 Some of Devel::Cover's own tests require it.
138 · Test::Differences
140 Needed if the tests fail and you would like nice output telling you
142 why.
143 · Template and Parallel::Iterator
145 Needed if you want to run cpancover.
147 · JSON, JSON::PP or JSON::XS
149 JSON is used to store the coverage database if it is available.
151 Use with mod_perl
153 By adding "use Devel::Cover;" to your mod_perl startup script, you
154 should be able to collect coverage information when running under
155 mod_perl. You can also add any options you need at this point. I
156 would suggest adding this as early as possible in your startup script
157 in order to collect as much coverage information as possible.
158
160 -blib - "use blib" and ignore files matching \bt/ (default true
161 iff blib directory exists).
162 -coverage criterion - Turn on coverage for the specified criterion. Criteria
163 include statement, branch, condition, path, subroutine,
164 pod, time, all and none (default all available).
165 -db cover_db - Store results in coverage db (default ./cover_db).
166 -dir path - Directory in which coverage will be collected (default
167 cwd).
168 -ignore RE - Set REs of files to ignore (default "/Devel/Cover\b").
169 +ignore RE - Append to REs of files to ignore.
170 -inc path - Set prefixes of files to ignore (default @INC).
171 +inc path - Append to prefixes of files to ignore.
172 -merge val - Merge databases, for multiple test benches (default on).
173 -select RE - Set REs of files to select (default none).
174 +select RE - Append to REs of files to select.
175 -silent val - Don't print informational messages (default off).
176 -subs_only val - Only cover code in subroutine bodies (default off).
177 -replace_ops val - Use op replacing rather than runops (default on).
178 -summary val - Print summary information iff val is true (default on).
179 More on Coverage Options
181 You can specify options to some coverage criteria. At the moment only
182 pod coverage takes any options. These are the parameters which are
183 passed into the Pod::Coverage constructor. The extra options are
184 separated by dashes, and you may specify as many as you wish. For
185 example, to specify that all subroutines containing xx are private,
186 call Devel::Cover with the option -coverage,pod-also_private-xx.
187
189 You may select the files for which you want to collect coverage data
190 using the select, ignore and inc options. The system uses the
191 following procedure to decide whether a file will be included in
192 coverage reports:
193 · If the file matches a RE given as a select option, it will be
195 included.
196 · Otherwise, if it matches a RE given as an ignore option, it won't
198 be included.
199 · Otherwise, if it is in one of the inc directories, it won't be
201 included.
202 · Otherwise, it will be included.
204 You may add to the REs to select by using +select, or you may reset the
206 selections using -select. The same principle applies to the REs to
207 ignore.
208 The inc directories are initially populated with the contents of perl's
210 @INC array. You may reset these directories using -inc, or add to them
211 using +inc.
212 Although these options take regular expressions, you should not enclose
214 the RE within // or any other quoting characters.
215 The options -coverage, [+-]select, [+-]ignore and [+-]inc can be
217 specified multiple times, but they can also take multiple comma
218 separated arguments. In any case you should not add a space after the
219 comma, unless you want the argument to start with that literal space.
220
222 Sometimes you have code which is uncoverable for some reason. Perhaps
223 it is an else clause that cannot be reached, or a check for an error
224 condition that should never happen. You can tell Devel::Cover that
225 certain criteria are uncoverable and then they are not counted as
226 errors when they are not exercised. In fact, they are counted as
227 errors if they are exercised.
228 This feature should only be used as something of a last resort.
230 Ideally you would find some way of exercising all your code. But if
231 you have analysed your code and determined that you are not going to be
232 able to exercise it, it may be better to record that fact in some
233 formal fashion and stop Devel::Cover complaining about it, so that real
234 problems are not lost in the noise.
235 There are two ways to specify a construct as uncoverable, one invasive
237 and one non-invasive.
238 Invasive specification
240 You can use special comments in your code to specify uncoverable
241 criteria. Comments are of the form:
242 # uncoverable <criterion> [details]
244 The keyword "uncoverable" must be the first text in the comment. It
246 should be followed by the name of the coverage criterion which is
247 uncoverable. There may then be further information depending on the
248 nature of the uncoverable construct.
249 Statements
251 The "uncoverable" comment should appear on either the same line as the
253 statement, of on the line before it:
254 $impossible++; # uncoverable statement
256 # uncoverable statement
257 it_has_all_gone_horribly_wrong();
258 If there are multiple statements (or any other criterion) on a line you
260 can specify which statement is uncoverable by using the "count"
261 attribute, count:n, which indicates that the uncoverable statement is
262 the nth statement on the line.
263 # uncoverable statement count:1
265 # uncoverable statement count:2
266 cannot_run_this(); or_this();
267 Branches
269 The "uncoverable" comment should specify whether the "true" or "false"
271 branch is uncoverable.
272 # uncoverable branch true
274 if (pi == 3)
275 Both branches may be uncoverable:
277 # uncoverable branch true
279 # uncoverable branch false
280 if (impossible_thing_happened_one_way()) {
281 handle_it_one_way(); # uncoverable statement
282 } else {
283 handle_it_another_way(); # uncoverable statement
284 }
285 Conditions
287 Because of the way in which Perl short-circuits boolean operations,
289 there are three ways in which such conditionals can be uncoverable. In
290 the case of " $x && $y" for example, the left operator may never be
291 true, the right operator may never be true, and the whole operation may
292 never be false. These conditions may be modelled thus:
293 # uncoverable branch true
295 # uncoverable condition left
296 # uncoverable condition false
297 if ($x && !$y)
298 {
299 $x++; # uncoverable statement
300 }
301 # uncoverable branch true
303 # uncoverable condition right
304 # uncoverable condition false
305 if (!$x && $y)
306 {
307 }
308 "Or" conditionals are handled in a similar fashion (TODO - provide some
310 examples) but "xor" conditionals are not properly handled yet.
311 Subroutines
313 A subroutine should be marked as uncoverable at the point where the
315 first statement is marked as uncoverable. Ideally all other criteria
316 in the subroutine would be marked as uncoverable automatically, but
317 that isn't the case at the moment.
318 sub z
320 {
321 # uncoverable subroutine
322 $y++; # uncoverable statement
323 }
324 Non-invasive specification
326 If you can't, or don't want to add coverage comments to your code, you
327 can specify the uncoverable information in a separate file. My default
328 this file is .uncoverable but you can override that.
329 The interface to managing this file is the cover program, and the
331 options are:
332 -uncoverable_file
334 -add_uncoverable_point
335 -delete_uncoverable_point
336 -clean_uncoverable_points
337 Of these, only the first two are implemented at the moment. The
339 parameter for -add_uncoverable_point is a string composed of up to
340 seven space separated elements: "$file $criterion $line $count $type
341 $class $note".
342 TODO - more information and examples.
344
346 User variables
347 The -silent option is turned on when Devel::Cover is invoked via
348 $HARNESS_PERL_SWITCHES or $PERL5OPT. Devel::Cover tries to do the
349 right thing when $MOD_PERL is set. $DEVEL_COVER_OPTIONS is appended to
350 any options passed into Devel::Cover.
351 Developer variables
353 When running Devel::Cover's own test suite, $DEVEL_COVER_DEBUG turns on
354 debugging information, $DEVEL_COVER_GOLDEN_VERSION overrides
355 Devel::Cover's own idea of which golden results it should test against,
356 and $DEVEL_COVER_NO_COVERAGE runs the tests without collecting
357 coverage. $DEVEL_COVER_DB_FORMAT may be set to either "JSON" or
358 "Storable" to override the default choice of DB format (JSON if
359 available, otherwise Storable). $DEVEL_COVER_IO_OPTIONS provides fine-
360 grained control over the DB format. For example, setting it to
361 "pretty" when the format is JSON will store the DB in a readable JSON
362 format.
363
365 Some code and ideas cribbed from:
366 L<Devel::OpProf>
368 L<B::Concise>
369 L<B::Deparse>
370
372 L<Devel::Cover::Tutorial>
373 L<B>
374 L<Pod::Coverage>
375
377 There are things that Devel::Cover can't cover.
378 Absence of shared dependencies
380 Perl keeps track of which modules have been loaded (to avoid reloading
381 them). Because of this, it isn't possible to get coverage for a path
382 where a runtime import fails if the module being imported is one that
383 Devel::Cover uses internally. For example, suppose your program has
384 this function:
385 sub foo {
387 eval { require Storable };
388 if ($@) {
389 carp "Can't find Storable";
390 return;
391 }
392 # ...
393 }
394 You might write a test for the failure mode as
396 BEGIN { @INC = () }
398 foo();
399 # check for error message
400 Because Devel::Cover uses Storable internally, the import will succeed
402 (and the test will fail) under a coverage run.
403 Modules used by Devel::Cover while gathering coverage:
405 · B
407 · B::Debug
409 · B::Deparse
411 · Carp
413 · Cwd
415 · Digest::MD5
417 · File::Path
419 · File::Spec
421 · Storable or JSON
423 Redefined subroutines
425 If you redefine a subroutine you may find that the original subroutine
426 is not reported on. This is because I haven't yet found a way to
427 locate the original CV. Hints, tips or patches to resolve this will be
428 gladly accepted.
429
431 Almost certainly.
432 See the BUGS file, the TODO file and the bug trackers at
434 <https://github.com/pjcj/Devel--Cover/issues?sort=created&direction=desc&state=open>
435 and <https://rt.cpan.org/Public/Dist/Display.html?Name=Devel-Cover>
436 Please report new bugs on Github.
438
440 Copyright 2001-2013, Paul Johnson (paul@pjcj.net)
441 This software is free. It is licensed under the same terms as Perl
443 itself.
444 The latest version of this software should be available on CPAN and
446 from my homepage: http://www.pjcj.net/.
447perl v5.16.3 2013-05-20 Devel::Cover(3)