1App::Prove(3)         User Contributed Perl Documentation        App::Prove(3)
2
3
4

NAME

6       App::Prove - Implements the "prove" command.
7

VERSION

9       Version 3.48
10

DESCRIPTION

12       Test::Harness provides a command, "prove", which runs a TAP based test
13       suite and prints a report. The "prove" command is a minimal wrapper
14       around an instance of this module.
15

SYNOPSIS

17           use App::Prove;
18
19           my $app = App::Prove->new;
20           $app->process_args(@ARGV);
21           $app->run;
22

METHODS

24   Class Methods
25       "new"
26
27       Create a new "App::Prove". Optionally a hash ref of attribute
28       initializers may be passed.
29
30       "state_class"
31
32       Getter/setter for the name of the class used for maintaining state.
33       This class should either subclass from "App::Prove::State" or provide
34       an identical interface.
35
36       "state_manager"
37
38       Getter/setter for the instance of the "state_class".
39
40       "add_rc_file"
41
42           $prove->add_rc_file('myproj/.proverc');
43
44       Called before "process_args" to prepend the contents of an rc file to
45       the options.
46
47       "process_args"
48
49           $prove->process_args(@args);
50
51       Processes the command-line arguments. Attributes will be set
52       appropriately. Any filenames may be found in the "argv" attribute.
53
54       Dies on invalid arguments.
55
56       "run"
57
58       Perform whatever actions the command line args specified. The "prove"
59       command line tool consists of the following code:
60
61           use App::Prove;
62
63           my $app = App::Prove->new;
64           $app->process_args(@ARGV);
65           exit( $app->run ? 0 : 1 );  # if you need the exit code
66
67       "require_harness"
68
69       Load a harness replacement class.
70
71         $prove->require_harness($for => $class_name);
72
73       "print_version"
74
75       Display the version numbers of the loaded TAP::Harness and the current
76       Perl.
77
78   Attributes
79       After command line parsing the following attributes reflect the values
80       of the corresponding command line switches. They may be altered before
81       calling "run".
82
83       "archive"
84       "argv"
85       "backwards"
86       "blib"
87       "color"
88       "directives"
89       "dry"
90       "exec"
91       "extensions"
92       "failures"
93       "comments"
94       "formatter"
95       "harness"
96       "ignore_exit"
97       "includes"
98       "jobs"
99       "lib"
100       "merge"
101       "modules"
102       "parse"
103       "plugins"
104       "quiet"
105       "really_quiet"
106       "recurse"
107       "rules"
108       "show_count"
109       "show_help"
110       "show_man"
111       "show_version"
112       "shuffle"
113       "state"
114       "state_class"
115       "taint_fail"
116       "taint_warn"
117       "test_args"
118       "timer"
119       "verbose"
120       "warnings_fail"
121       "warnings_warn"
122       "tapversion"
123       "trap"
124

PLUGINS

126       "App::Prove" provides support for 3rd-party plugins.  These are
127       currently loaded at run-time, after arguments have been parsed (so you
128       can not change the way arguments are processed, sorry), typically with
129       the "-Pplugin" switch, eg:
130
131         prove -PMyPlugin
132
133       This will search for a module named "App::Prove::Plugin::MyPlugin", or
134       failing that, "MyPlugin".  If the plugin can't be found, "prove" will
135       complain & exit.
136
137       You can pass an argument to your plugin by appending an "=" after the
138       plugin name, eg "-PMyPlugin=foo".  You can pass multiple arguments
139       using commas:
140
141         prove -PMyPlugin=foo,bar,baz
142
143       These are passed in to your plugin's load() class method (if it has
144       one), along with a reference to the "App::Prove" object that is
145       invoking your plugin:
146
147         sub load {
148             my ($class, $p) = @_;
149
150             my @args = @{ $p->{args} };
151             # @args will contain ( 'foo', 'bar', 'baz' )
152             $p->{app_prove}->do_something;
153             ...
154         }
155
156   Sample Plugin
157       Here's a sample plugin, for your reference:
158
159         package App::Prove::Plugin::Foo;
160
161         # Sample plugin, try running with:
162         # prove -PFoo=bar -r -j3
163         # prove -PFoo -Q
164         # prove -PFoo=bar,My::Formatter
165
166         use strict;
167         use warnings;
168
169         sub load {
170             my ($class, $p) = @_;
171             my @args = @{ $p->{args} };
172             my $app  = $p->{app_prove};
173
174             print "loading plugin: $class, args: ", join(', ', @args ), "\n";
175
176             # turn on verbosity
177             $app->verbose( 1 );
178
179             # set the formatter?
180             $app->formatter( $args[1] ) if @args > 1;
181
182             # print some of App::Prove's state:
183             for my $attr (qw( jobs quiet really_quiet recurse verbose )) {
184                 my $val = $app->$attr;
185                 $val    = 'undef' unless defined( $val );
186                 print "$attr: $val\n";
187             }
188
189             return 1;
190         }
191
192         1;
193

SEE ALSO

195       prove, TAP::Harness
196
197
198
199perl v5.38.0                      2023-10-03                     App::Prove(3)