Debian Codegraph @

upstream/opensuse-tumbleweed/man3/App::Prove.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "App::Prove 3pm"
61 .TH App::Prove 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 App::Prove \- Implements the "prove" command.
68 .SH VERSION
69 .IX Header "VERSION"
70 Version 3.50
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 Test::Harness provides a command, \f(CW\*(C`prove\*(C'\fR, which runs a TAP based
74 test suite and prints a report. The \f(CW\*(C`prove\*(C'\fR command is a minimal
75 wrapper around an instance of this module.
76 .SH SYNOPSIS
77 .IX Header "SYNOPSIS"
78 .Vb 1
79 \& use App::Prove;
80 \&
81 \& my $app = App::Prove\->new;
82 \& $app\->process_args(@ARGV);
83 \& $app\->run;
84 .Ve
85 .SH METHODS
86 .IX Header "METHODS"
87 .SS "Class Methods"
88 .IX Subsection "Class Methods"
89 \fR\f(CI\*(C`new\*(C'\fR\fI\fR
90 .IX Subsection "new"
91 .PP
92 Create a new \f(CW\*(C`App::Prove\*(C'\fR. Optionally a hash ref of attribute
93 initializers may be passed.
94 .PP
95 \fR\f(CI\*(C`state_class\*(C'\fR\fI\fR
96 .IX Subsection "state_class"
97 .PP
98 Getter/setter for the name of the class used for maintaining state. This
99 class should either subclass from \f(CW\*(C`App::Prove::State\*(C'\fR or provide an identical
100 interface.
101 .PP
102 \fR\f(CI\*(C`state_manager\*(C'\fR\fI\fR
103 .IX Subsection "state_manager"
104 .PP
105 Getter/setter for the instance of the \f(CW\*(C`state_class\*(C'\fR.
106 .PP
107 \fR\f(CI\*(C`add_rc_file\*(C'\fR\fI\fR
108 .IX Subsection "add_rc_file"
109 .PP
110 .Vb 1
111 \& $prove\->add_rc_file(\*(Aqmyproj/.proverc\*(Aq);
112 .Ve
113 .PP
114 Called before \f(CW\*(C`process_args\*(C'\fR to prepend the contents of an rc file to
115 the options.
116 .PP
117 \fR\f(CI\*(C`process_args\*(C'\fR\fI\fR
118 .IX Subsection "process_args"
119 .PP
120 .Vb 1
121 \& $prove\->process_args(@args);
122 .Ve
123 .PP
124 Processes the command\-line arguments. Attributes will be set
125 appropriately. Any filenames may be found in the \f(CW\*(C`argv\*(C'\fR attribute.
126 .PP
127 Dies on invalid arguments.
128 .PP
129 \fR\f(CI\*(C`run\*(C'\fR\fI\fR
130 .IX Subsection "run"
131 .PP
132 Perform whatever actions the command line args specified. The \f(CW\*(C`prove\*(C'\fR
133 command line tool consists of the following code:
134 .PP
135 .Vb 1
136 \& use App::Prove;
137 \&
138 \& my $app = App::Prove\->new;
139 \& $app\->process_args(@ARGV);
140 \& exit( $app\->run ? 0 : 1 ); # if you need the exit code
141 .Ve
142 .PP
143 \fR\f(CI\*(C`require_harness\*(C'\fR\fI\fR
144 .IX Subsection "require_harness"
145 .PP
146 Load a harness replacement class.
147 .PP
148 .Vb 1
149 \& $prove\->require_harness($for => $class_name);
150 .Ve
151 .PP
152 \fR\f(CI\*(C`print_version\*(C'\fR\fI\fR
153 .IX Subsection "print_version"
154 .PP
155 Display the version numbers of the loaded TAP::Harness and the
156 current Perl.
157 .SS Attributes
158 .IX Subsection "Attributes"
159 After command line parsing the following attributes reflect the values
160 of the corresponding command line switches. They may be altered before
161 calling \f(CW\*(C`run\*(C'\fR.
162 .ie n .IP """archive""" 4
163 .el .IP \f(CWarchive\fR 4
164 .IX Item "archive"
165 .PD 0
166 .ie n .IP """argv""" 4
167 .el .IP \f(CWargv\fR 4
168 .IX Item "argv"
169 .ie n .IP """backwards""" 4
170 .el .IP \f(CWbackwards\fR 4
171 .IX Item "backwards"
172 .ie n .IP """blib""" 4
173 .el .IP \f(CWblib\fR 4
174 .IX Item "blib"
175 .ie n .IP """color""" 4
176 .el .IP \f(CWcolor\fR 4
177 .IX Item "color"
178 .ie n .IP """directives""" 4
179 .el .IP \f(CWdirectives\fR 4
180 .IX Item "directives"
181 .ie n .IP """dry""" 4
182 .el .IP \f(CWdry\fR 4
183 .IX Item "dry"
184 .ie n .IP """exec""" 4
185 .el .IP \f(CWexec\fR 4
186 .IX Item "exec"
187 .ie n .IP """extensions""" 4
188 .el .IP \f(CWextensions\fR 4
189 .IX Item "extensions"
190 .ie n .IP """failures""" 4
191 .el .IP \f(CWfailures\fR 4
192 .IX Item "failures"
193 .ie n .IP """comments""" 4
194 .el .IP \f(CWcomments\fR 4
195 .IX Item "comments"
196 .ie n .IP """formatter""" 4
197 .el .IP \f(CWformatter\fR 4
198 .IX Item "formatter"
199 .ie n .IP """harness""" 4
200 .el .IP \f(CWharness\fR 4
201 .IX Item "harness"
202 .ie n .IP """ignore_exit""" 4
203 .el .IP \f(CWignore_exit\fR 4
204 .IX Item "ignore_exit"
205 .ie n .IP """includes""" 4
206 .el .IP \f(CWincludes\fR 4
207 .IX Item "includes"
208 .ie n .IP """jobs""" 4
209 .el .IP \f(CWjobs\fR 4
210 .IX Item "jobs"
211 .ie n .IP """lib""" 4
212 .el .IP \f(CWlib\fR 4
213 .IX Item "lib"
214 .ie n .IP """merge""" 4
215 .el .IP \f(CWmerge\fR 4
216 .IX Item "merge"
217 .ie n .IP """modules""" 4
218 .el .IP \f(CWmodules\fR 4
219 .IX Item "modules"
220 .ie n .IP """parse""" 4
221 .el .IP \f(CWparse\fR 4
222 .IX Item "parse"
223 .ie n .IP """plugins""" 4
224 .el .IP \f(CWplugins\fR 4
225 .IX Item "plugins"
226 .ie n .IP """quiet""" 4
227 .el .IP \f(CWquiet\fR 4
228 .IX Item "quiet"
229 .ie n .IP """really_quiet""" 4
230 .el .IP \f(CWreally_quiet\fR 4
231 .IX Item "really_quiet"
232 .ie n .IP """recurse""" 4
233 .el .IP \f(CWrecurse\fR 4
234 .IX Item "recurse"
235 .ie n .IP """rules""" 4
236 .el .IP \f(CWrules\fR 4
237 .IX Item "rules"
238 .ie n .IP """show_count""" 4
239 .el .IP \f(CWshow_count\fR 4
240 .IX Item "show_count"
241 .ie n .IP """show_help""" 4
242 .el .IP \f(CWshow_help\fR 4
243 .IX Item "show_help"
244 .ie n .IP """show_man""" 4
245 .el .IP \f(CWshow_man\fR 4
246 .IX Item "show_man"
247 .ie n .IP """show_version""" 4
248 .el .IP \f(CWshow_version\fR 4
249 .IX Item "show_version"
250 .ie n .IP """shuffle""" 4
251 .el .IP \f(CWshuffle\fR 4
252 .IX Item "shuffle"
253 .ie n .IP """state""" 4
254 .el .IP \f(CWstate\fR 4
255 .IX Item "state"
256 .ie n .IP """state_class""" 4
257 .el .IP \f(CWstate_class\fR 4
258 .IX Item "state_class"
259 .ie n .IP """taint_fail""" 4
260 .el .IP \f(CWtaint_fail\fR 4
261 .IX Item "taint_fail"
262 .ie n .IP """taint_warn""" 4
263 .el .IP \f(CWtaint_warn\fR 4
264 .IX Item "taint_warn"
265 .ie n .IP """test_args""" 4
266 .el .IP \f(CWtest_args\fR 4
267 .IX Item "test_args"
268 .ie n .IP """timer""" 4
269 .el .IP \f(CWtimer\fR 4
270 .IX Item "timer"
271 .ie n .IP """verbose""" 4
272 .el .IP \f(CWverbose\fR 4
273 .IX Item "verbose"
274 .ie n .IP """warnings_fail""" 4
275 .el .IP \f(CWwarnings_fail\fR 4
276 .IX Item "warnings_fail"
277 .ie n .IP """warnings_warn""" 4
278 .el .IP \f(CWwarnings_warn\fR 4
279 .IX Item "warnings_warn"
280 .ie n .IP """tapversion""" 4
281 .el .IP \f(CWtapversion\fR 4
282 .IX Item "tapversion"
283 .ie n .IP """trap""" 4
284 .el .IP \f(CWtrap\fR 4
285 .IX Item "trap"
286 .PD
287 .SH PLUGINS
288 .IX Header "PLUGINS"
289 \&\f(CW\*(C`App::Prove\*(C'\fR provides support for 3rd\-party plugins. These are currently
290 loaded at run\-time, \fIafter\fR arguments have been parsed (so you can not
291 change the way arguments are processed, sorry), typically with the
292 \&\f(CW\*(C`\-P\fR\f(CIplugin\fR\f(CW\*(C'\fR switch, eg:
293 .PP
294 .Vb 1
295 \& prove \-PMyPlugin
296 .Ve
297 .PP
298 This will search for a module named \f(CW\*(C`App::Prove::Plugin::MyPlugin\*(C'\fR, or failing
299 that, \f(CW\*(C`MyPlugin\*(C'\fR. If the plugin can\*(Aqt be found, \f(CW\*(C`prove\*(C'\fR will complain & exit.
300 .PP
301 You can pass an argument to your plugin by appending an \f(CW\*(C`=\*(C'\fR after the plugin
302 name, eg \f(CW\*(C`\-PMyPlugin=foo\*(C'\fR. You can pass multiple arguments using commas:
303 .PP
304 .Vb 1
305 \& prove \-PMyPlugin=foo,bar,baz
306 .Ve
307 .PP
308 These are passed in to your plugin\*(Aqs \f(CWload()\fR class method (if it has one),
309 along with a reference to the \f(CW\*(C`App::Prove\*(C'\fR object that is invoking your plugin:
310 .PP
311 .Vb 2
312 \& sub load {
313 \& my ($class, $p) = @_;
314 \&
315 \& my @args = @{ $p\->{args} };
316 \& # @args will contain ( \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq, \*(Aqbaz\*(Aq )
317 \& $p\->{app_prove}\->do_something;
318 \& ...
319 \& }
320 .Ve
321 .SS "Sample Plugin"
322 .IX Subsection "Sample Plugin"
323 Here\*(Aqs a sample plugin, for your reference:
324 .PP
325 .Vb 1
326 \& package App::Prove::Plugin::Foo;
327 \&
328 \& # Sample plugin, try running with:
329 \& # prove \-PFoo=bar \-r \-j3
330 \& # prove \-PFoo \-Q
331 \& # prove \-PFoo=bar,My::Formatter
332 \&
333 \& use strict;
334 \& use warnings;
335 \&
336 \& sub load {
337 \& my ($class, $p) = @_;
338 \& my @args = @{ $p\->{args} };
339 \& my $app = $p\->{app_prove};
340 \&
341 \& print "loading plugin: $class, args: ", join(\*(Aq, \*(Aq, @args ), "\en";
342 \&
343 \& # turn on verbosity
344 \& $app\->verbose( 1 );
345 \&
346 \& # set the formatter?
347 \& $app\->formatter( $args[1] ) if @args > 1;
348 \&
349 \& # print some of App::Prove\*(Aqs state:
350 \& for my $attr (qw( jobs quiet really_quiet recurse verbose )) {
351 \& my $val = $app\->$attr;
352 \& $val = \*(Aqundef\*(Aq unless defined( $val );
353 \& print "$attr: $val\en";
354 \& }
355 \&
356 \& return 1;
357 \& }
358 \&
359 \& 1;
360 .Ve
361 .SH "SEE ALSO"
362 .IX Header "SEE ALSO"
363 prove, TAP::Harness