App::Prove(3pm)

1App::Prove(3pm)        Perl Programmers Reference Guide        App::Prove(3pm)
2
3
4

NAME

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

VERSION

9       Version 3.17
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       "extension"
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

PLUGINS

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

NAME

VERSION

DESCRIPTION

SYNOPSIS

METHODS

PLUGINS

SEE ALSO