1COVER(1) User Contributed Perl Documentation COVER(1)
2
6 cover - report coverage statistics
7
9 version 1.40
10
12 cover -test
13 cover -report html_basic
15
17 Report coverage statistics in a variety of formats.
18 The summary option produces a short textual summary. Other reports are
20 available by using the report option.
21 The following reports are currently available:
23 html - detailed HTML reports (default)
25 html_basic - detailed HTML reports with syntax highlighting
26 text - detailed textual summary
27 compilation - output in a format similar to Perl errors
28 json - output in a JSON format
29 vim - show coverage information in vim gutter
30
32 The following command line options are supported:
33 -h -help - show help
35 -i -info - show documentation
36 -v -version - show version
37 -silent - don't print informational messages (default off)
39 -summary - give summary report (default on)
40 -report report_format - report format (default html)
41 -outputdir dir - directory for output (default given db)
42 -launch - launch report in viewer (if avail) (default off)
43 -select filename - only report on the file (default all)
45 -ignore filename - don't report on the file (default none)
46 -select_re RE - append to REs of files to select (default none)
47 -ignore_re RE - append to REs of files to ignore (default none)
48 -relative_only - for XS, ignore absolute paths (default off)
49 -gcov_chdir - for XS, run gcov in subdirs (default off)
50 -write [db] - write the merged database (default off)
51 -delete - drop database(s) (default off)
52 -dump_db - dump database(s) (for debugging) (default off)
53 -coverage criterion - report on criterion (default all available)
55 -test - drop database(s) and run make test (default off)
57 -gcov - run gcov to cover XS code (default on if using gcc)
58 -make make_prog - use the given 'make' program for 'make test'
59 -prefer_lib - prefer files in lib (default off)
60 -ignore_covered_err - allow coverung uncoverable code (default off)
61 -add_uncoverable_point string
63 -delete_uncoverable_point string
64 -clean_uncoverable_points
65 -uncoverable_file file
66 other options specific to the report format
68 coverage_database [coverage_database ...]
70 The "-report", "-select", "-ignore", "-select_re", "-ignore_re", and
72 "-coverage" options may be specified multiple times.
73
75 The following "-report" options are available in the core module.
76 Other reports may be available if they've been installed from external
77 packages.
78 html|html_minimal (default)
80 HTML reporting. Percentage thresholds are colour-coded and
81 configurable via -report_c0 <integer>, -report_c1 <integer> and
82 -report_c2 <integer>.:
83 0% 75% 90% 100%
85 | .. | .. | .. |
86 <c0 <c1 <c2 c3
87 red yellow orange green
88 html_basic
90 HTML reporting with syntax highlighting if PPI::HTML or Perl::Tidy
91 module is detected. Like html|html_minimal reporting, percentage
92 thresholds are colour-coded and configurable.
93 text
95 Plain text reporting.
96 compilation
98 A textual report in a format similar to that output by Perl itself
99 such that the report may be used by your editor or other reporting
100 tools to show where coverage is missing.
101 json
103 A report in JSON format.
104 vim A report suitable for use with the vim editor to show coverage data
106 in the sign column.
107
109 Any number of coverage databases may be specified on the command line.
110 These databases will be merged and the reports will be based on the
111 merged information. If no databases are specified the default database
112 (cover_db) will be used.
113 The "-write" option will write out the merged database. If no name is
115 given for the new database, the first database read in will be
116 overwritten. When this option is used no reports are generated by
117 default.
118 Specify the "-select", "-select_re", "-ignore", and "-ignore_re"
120 options to report on specific files. "-select" and "-ignore" are
121 interpreted as shell globs; "-select_re" and "-ignore_re" are
122 interpreted as regular expressions.
123 Specify "-coverage" options to report on specific criteria. By default
125 all available information on all criteria in all files will be
126 reported. Available coverage options are statement, branch, condition,
127 subroutine, pod, and default (which equates to all available options).
128 However, if you know you only want coverage information for certain
129 criteria it is better to only collect data for those criteria in the
130 first place by specifying them at that point. This will make the data
131 collection and reporting processes faster and less memory intensive.
132 See the documentation for Devel::Cover for more information.
133 If you want all *except* some criteria, then you can say something like
135 "-coverage default,-pod".
136 If you specify multiple "-report" options, make sure that they do not
138 conflict. For example, the different HTML reports will overwrite each
139 other's results.
140 The "-test" option will delete the databases and run your tests to
142 generate new coverage data before reporting on it. Devel::Cover knows
143 how to work with standard Perl Makefiles as well as Module::Build based
144 distributions. For detailed instructions see the documentation for
145 ExtUtils::MakeMaker at
146 <https://metacpan.org/module/ExtUtils::MakeMaker> or for Module::Build
147 at <https://metacpan.org/module/Module::Build> both of which come as
148 standard in recent Perl distributions.
149 The "-gcov" option will try to run gcov on any XS code. This requires
151 that you are using gcc of course. If you are using the "-test" option
152 will be turned on by default. If you have XS code in subdirectories,
153 you will probably need to add the "-gcov_chdir" option since gcov seems
154 to work better with that.
155 The "-prefer_lib" option tells Devel::Cover to report on files in the
157 lib directory even if they were used from the blib directory.
158 The "-ignore_covered_err" option will not flag an error if uncoverable
160 code is covered.
161
163 The following exit values are returned:
164 0 All operations were completed successfully.
166 >0 An error occurred.
168 With the -test option the exit status of the underlying test run is
170 returned.
171
173 Devel::Cover
174
176 Did I mention that this is alpha code?
177 See the BUGS file.
179
181 Copyright 2001-2023, Paul Johnson (paul@pjcj.net)
182 This software is free. It is licensed under the same terms as Perl
184 itself.
185 The latest version of this software should be available from my
187 homepage: http://www.pjcj.net
188perl v5.38.2 2023-11-30 COVER(1)