1COVER(1)              User Contributed Perl Documentation             COVER(1)
2
3
4

NAME

6       cover - report coverage statistics
7

VERSION

9       version 1.36
10

SYNOPSIS

12        cover -test
13
14        cover -report html_basic
15

DESCRIPTION

17       Report coverage statistics in a variety of formats.
18
19       The summary option produces a short textual summary.  Other reports are
20       available by using the report option.
21
22       The following reports are currently available:
23
24        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

OPTIONS

32       The following command line options are supported:
33
34        -h -help              - show help
35        -i -info              - show documentation
36        -v -version           - show version
37
38        -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
44        -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        -write [db]           - write the merged database          (default off)
49        -delete               - drop database(s)                   (default off)
50        -dump_db              - dump database(s) (for debugging)   (default off)
51
52        -coverage criterion   - report on criterion  (default all available)
53
54        -test                 - drop database(s) and run make test (default off)
55        -gcov                 - run gcov to cover XS code     (default on if using gcc)
56        -make make_prog       - use the given 'make' program for 'make test'
57        -prefer_lib           - prefer files in lib                (default off)
58
59        -add_uncoverable_point    string
60        -delete_uncoverable_point string
61        -clean_uncoverable_points
62        -uncoverable_file         file
63
64        other options specific to the report format
65
66        coverage_database [coverage_database ...]
67
68       The "-report", "-select", "-ignore", "-select_re", "-ignore_re", and
69       "-coverage" options may be specified multiple times.
70

REPORT FORMATS

72       The following "-report" options are available in the core module.
73       Other reports may be available if they've been installed from external
74       packages.
75
76       html|html_minimal (default)
77           HTML reporting. Percentage thresholds are colour-coded and
78           configurable via -report_c0 <integer>, -report_c1 <integer> and
79           -report_c2 <integer>.:
80
81               0%      75%      90%      100%
82               |   ..   |   ..   |   ..   |
83                  <c0      <c1      <c2   c3
84                  red     yellow   orange green
85
86       html_basic
87           HTML reporting with syntax highlighting if PPI::HTML or Perl::Tidy
88           module is detected. Like html|html_minimal reporting, percentage
89           thresholds are colour-coded and configurable.
90
91       text
92           Plain text reporting.
93
94       compilation
95           A textual report in a format similar to that output by Perl itself
96           such that the report may be used by your editor or other reporting
97           tools to show where coverage is missing.
98
99       json
100           A report in JSON format.
101
102       vim A report suitable for use with the vim editor to show coverage data
103           in the sign column.
104

DETAILS

106       Any number of coverage databases may be specified on the command line.
107       These databases will be merged and the reports will be based on the
108       merged information.  If no databases are specified the default database
109       (cover_db) will be used.
110
111       The "-write" option will write out the merged database.  If no name is
112       given for the new database, the first database read in will be
113       overwritten.  When this option is used no reports are generated by
114       default.
115
116       Specify the "-select", "-select_re", "-ignore", and "-ignore_re"
117       options to report on specific files.  "-select" and "-ignore" are
118       interpreted as shell globs; "-select_re" and "-ignore_re" are
119       interpreted as regular expressions.
120
121       Specify "-coverage" options to report on specific criteria.  By default
122       all available information on all criteria in all files will be
123       reported.  Available coverage options are statement, branch, condition,
124       subroutine, pod, and default (which equates to all available options).
125       However, if you know you only want coverage information for certain
126       criteria it is better to only collect data for those criteria in the
127       first place by specifying them at that point.  This will make the data
128       collection and reporting processes faster and less memory intensive.
129       See the documentation for Devel::Cover for more information.
130
131       If you want all *except* some criteria, then you can say something like
132       "-coverage default,-pod".
133
134       If you specify multiple "-report" options, make sure that they do not
135       conflict.  For example, the different HTML reports will overwrite each
136       other's results.
137
138       The "-test" option will delete the databases and run your tests to
139       generate new coverage data before reporting on it.  Devel::Cover knows
140       how to work with standard Perl Makefiles as well as Module::Build based
141       distributions.  For detailed instructions see the documentation for
142       ExtUtils::MakeMaker at
143       <https://metacpan.org/module/ExtUtils::MakeMaker> or for Module::Build
144       at <https://metacpan.org/module/Module::Build> both of which come as
145       standard in recent Perl distributions.
146
147       The "-gcov" option will try to run gcov on any XS code.  This requires
148       that you are using gcc of course.  If you are using the "-test" option
149       will be turned on by default.
150
151       The "-prefer_lib" option tells Devel::Cover to report on files in the
152       lib directory even if they were used from the blib directory.
153

EXIT STATUS

155       The following exit values are returned:
156
157       0   All operations were completed successfully.
158
159       >0  An error occurred.
160
161       With the -test option the exit status of the underlying test run is
162       returned.
163

SEE ALSO

165       Devel::Cover
166

BUGS

168       Did I mention that this is alpha code?
169
170       See the BUGS file.
171

LICENCE

173       Copyright 2001-2019, Paul Johnson (paul@pjcj.net)
174
175       This software is free.  It is licensed under the same terms as Perl
176       itself.
177
178       The latest version of this software should be available from my
179       homepage: http://www.pjcj.net
180
181
182
183perl v5.34.0                      2022-01-21                          COVER(1)
Impressum