App::Prove(3pm)

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.44
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       Note that the user's arguments are also passed to your plugin's
157       "import()" function as a list, eg:
158
159         sub import {
160             my ($class, @args) = @_;
161             # @args will contain ( 'foo', 'bar', 'baz' )
162             ...
163         }
164
165       This is for backwards compatibility, and may be deprecated in the
166       future.
167
168   Sample Plugin
169       Here's a sample plugin, for your reference:
170
171         package App::Prove::Plugin::Foo;
172
173         # Sample plugin, try running with:
174         # prove -PFoo=bar -r -j3
175         # prove -PFoo -Q
176         # prove -PFoo=bar,My::Formatter
177
178         use strict;
179         use warnings;
180
181         sub load {
182             my ($class, $p) = @_;
183             my @args = @{ $p->{args} };
184             my $app  = $p->{app_prove};
185
186             print "loading plugin: $class, args: ", join(', ', @args ), "\n";
187
188             # turn on verbosity
189             $app->verbose( 1 );
190
191             # set the formatter?
192             $app->formatter( $args[1] ) if @args > 1;
193
194             # print some of App::Prove's state:
195             for my $attr (qw( jobs quiet really_quiet recurse verbose )) {
196                 my $val = $app->$attr;
197                 $val    = 'undef' unless defined( $val );
198                 print "$attr: $val\n";
199             }
200
201             return 1;
202         }
203
204         1;
205

NAME

VERSION

DESCRIPTION

SYNOPSIS

METHODS

PLUGINS

SEE ALSO