| line | stmt | bran | cond | sub | pod | time | code | 
| 1 |  |  |  |  |  |  | #!/Users/johanl/perl5/perlbrew/perls/perl-5.18.1/bin/perl -w | 
| 2 |  |  |  |  |  |  |  | 
| 3 | 1 |  |  |  |  | 74655 | eval 'exec /Users/johanl/perl5/perlbrew/perls/perl-5.18.1/bin/perl -w -S $0 ${1+"$@"}' | 
| 4 |  |  |  |  |  |  | if 0; # not running under some shell | 
| 5 |  |  |  |  |  |  |  | 
| 6 | 1 |  |  | 1 |  | 3396 | use strict; | 
|  | 1 |  |  |  |  | 2 |  | 
|  | 1 |  |  |  |  | 33 |  | 
| 7 | 1 |  |  | 1 |  | 3 | use warnings; | 
|  | 1 |  |  |  |  | 1 |  | 
|  | 1 |  |  |  |  | 22 |  | 
| 8 | 1 |  |  | 1 |  | 7677 | use App::Prove; | 
|  | 1 |  |  |  |  | 117653 |  | 
|  | 1 |  |  |  |  | 1167 |  | 
| 9 |  |  |  |  |  |  |  | 
| 10 | 1 |  |  |  |  | 7 | my $app = App::Prove->new; | 
| 11 | 1 |  |  |  |  | 82 | $app->process_args(@ARGV); | 
| 12 | 1 | 50 |  |  |  | 1903 | exit( $app->run ? 0 : 1 ); | 
| 13 |  |  |  |  |  |  |  | 
| 14 |  |  |  |  |  |  | __END__ | 
| 15 |  |  |  |  |  |  |  | 
| 16 |  |  |  |  |  |  | =head1 NAME | 
| 17 |  |  |  |  |  |  |  | 
| 18 |  |  |  |  |  |  | prove - Run tests through a TAP harness. | 
| 19 |  |  |  |  |  |  |  | 
| 20 |  |  |  |  |  |  | =head1 USAGE | 
| 21 |  |  |  |  |  |  |  | 
| 22 |  |  |  |  |  |  | prove [options] [files or directories] | 
| 23 |  |  |  |  |  |  |  | 
| 24 |  |  |  |  |  |  | =head1 OPTIONS | 
| 25 |  |  |  |  |  |  |  | 
| 26 |  |  |  |  |  |  | Boolean options: | 
| 27 |  |  |  |  |  |  |  | 
| 28 |  |  |  |  |  |  | -v,  --verbose         Print all test lines. | 
| 29 |  |  |  |  |  |  | -l,  --lib             Add 'lib' to the path for your tests (-Ilib). | 
| 30 |  |  |  |  |  |  | -b,  --blib            Add 'blib/lib' and 'blib/arch' to the path for | 
| 31 |  |  |  |  |  |  | your tests | 
| 32 |  |  |  |  |  |  | -s,  --shuffle         Run the tests in random order. | 
| 33 |  |  |  |  |  |  | -c,  --color           Colored test output (default). | 
| 34 |  |  |  |  |  |  | --nocolor         Do not color test output. | 
| 35 |  |  |  |  |  |  | --count           Show the X/Y test count when not verbose | 
| 36 |  |  |  |  |  |  | (default) | 
| 37 |  |  |  |  |  |  | --nocount         Disable the X/Y test count. | 
| 38 |  |  |  |  |  |  | -D   --dry             Dry run. Show test that would have run. | 
| 39 |  |  |  |  |  |  | -f,  --failures        Show failed tests. | 
| 40 |  |  |  |  |  |  | -o,  --comments        Show comments. | 
| 41 |  |  |  |  |  |  | --ignore-exit     Ignore exit status from test scripts. | 
| 42 |  |  |  |  |  |  | -m,  --merge           Merge test scripts' STDERR with their STDOUT. | 
| 43 |  |  |  |  |  |  | -r,  --recurse         Recursively descend into directories. | 
| 44 |  |  |  |  |  |  | --reverse         Run the tests in reverse order. | 
| 45 |  |  |  |  |  |  | -q,  --quiet           Suppress some test output while running tests. | 
| 46 |  |  |  |  |  |  | -Q,  --QUIET           Only print summary results. | 
| 47 |  |  |  |  |  |  | -p,  --parse           Show full list of TAP parse errors, if any. | 
| 48 |  |  |  |  |  |  | --directives      Only show results with TODO or SKIP directives. | 
| 49 |  |  |  |  |  |  | --timer           Print elapsed time after each test. | 
| 50 |  |  |  |  |  |  | --trap            Trap Ctrl-C and print summary on interrupt. | 
| 51 |  |  |  |  |  |  | --normalize       Normalize TAP output in verbose output | 
| 52 |  |  |  |  |  |  | -T                     Enable tainting checks. | 
| 53 |  |  |  |  |  |  | -t                     Enable tainting warnings. | 
| 54 |  |  |  |  |  |  | -W                     Enable fatal warnings. | 
| 55 |  |  |  |  |  |  | -w                     Enable warnings. | 
| 56 |  |  |  |  |  |  | -h,  --help            Display this help | 
| 57 |  |  |  |  |  |  | -?,                    Display this help | 
| 58 |  |  |  |  |  |  | -H,  --man             Longer manpage for prove | 
| 59 |  |  |  |  |  |  | --norc            Don't process default .proverc | 
| 60 |  |  |  |  |  |  |  | 
| 61 |  |  |  |  |  |  | Options that take arguments: | 
| 62 |  |  |  |  |  |  |  | 
| 63 |  |  |  |  |  |  | -I                     Library paths to include. | 
| 64 |  |  |  |  |  |  | -P                     Load plugin (searches App::Prove::Plugin::*.) | 
| 65 |  |  |  |  |  |  | -M                     Load a module. | 
| 66 |  |  |  |  |  |  | -e,  --exec            Interpreter to run the tests ('' for compiled | 
| 67 |  |  |  |  |  |  | tests.) | 
| 68 |  |  |  |  |  |  | --ext             Set the extension for tests (default '.t') | 
| 69 |  |  |  |  |  |  | --harness         Define test harness to use.  See TAP::Harness. | 
| 70 |  |  |  |  |  |  | --formatter       Result formatter to use. See FORMATTERS. | 
| 71 |  |  |  |  |  |  | --source          Load and/or configure a SourceHandler. See | 
| 72 |  |  |  |  |  |  | SOURCE HANDLERS. | 
| 73 |  |  |  |  |  |  | -a,  --archive out.tgz Store the resulting TAP in an archive file. | 
| 74 |  |  |  |  |  |  | -j,  --jobs N          Run N test jobs in parallel (try 9.) | 
| 75 |  |  |  |  |  |  | --state=opts      Control prove's persistent state. | 
| 76 |  |  |  |  |  |  | --rc=rcfile       Process options from rcfile | 
| 77 |  |  |  |  |  |  | --rules           Rules for parallel vs sequential processing. | 
| 78 |  |  |  |  |  |  |  | 
| 79 |  |  |  |  |  |  | =head1 NOTES | 
| 80 |  |  |  |  |  |  |  | 
| 81 |  |  |  |  |  |  | =head2 .proverc | 
| 82 |  |  |  |  |  |  |  | 
| 83 |  |  |  |  |  |  | If F<~/.proverc> or F<./.proverc> exist they will be read and any | 
| 84 |  |  |  |  |  |  | options they contain processed before the command line options. Options | 
| 85 |  |  |  |  |  |  | in F<.proverc> are specified in the same way as command line options: | 
| 86 |  |  |  |  |  |  |  | 
| 87 |  |  |  |  |  |  | # .proverc | 
| 88 |  |  |  |  |  |  | --state=hot,fast,save | 
| 89 |  |  |  |  |  |  | -j9 | 
| 90 |  |  |  |  |  |  |  | 
| 91 |  |  |  |  |  |  | Additional option files may be specified with the C<--rc> option. | 
| 92 |  |  |  |  |  |  | Default option file processing is disabled by the C<--norc> option. | 
| 93 |  |  |  |  |  |  |  | 
| 94 |  |  |  |  |  |  | Under Windows and VMS the option file is named F<_proverc> rather than | 
| 95 |  |  |  |  |  |  | F<.proverc> and is sought only in the current directory. | 
| 96 |  |  |  |  |  |  |  | 
| 97 |  |  |  |  |  |  | =head2 Reading from C<STDIN> | 
| 98 |  |  |  |  |  |  |  | 
| 99 |  |  |  |  |  |  | If you have a list of tests (or URLs, or anything else you want to test) in a | 
| 100 |  |  |  |  |  |  | file, you can add them to your tests by using a '-': | 
| 101 |  |  |  |  |  |  |  | 
| 102 |  |  |  |  |  |  | prove - < my_list_of_things_to_test.txt | 
| 103 |  |  |  |  |  |  |  | 
| 104 |  |  |  |  |  |  | See the C<README> in the C<examples> directory of this distribution. | 
| 105 |  |  |  |  |  |  |  | 
| 106 |  |  |  |  |  |  | =head2 Default Test Directory | 
| 107 |  |  |  |  |  |  |  | 
| 108 |  |  |  |  |  |  | If no files or directories are supplied, C<prove> looks for all files | 
| 109 |  |  |  |  |  |  | matching the pattern C<t/*.t>. | 
| 110 |  |  |  |  |  |  |  | 
| 111 |  |  |  |  |  |  | =head2 Colored Test Output | 
| 112 |  |  |  |  |  |  |  | 
| 113 |  |  |  |  |  |  | Colored test output using L<TAP::Formatter::Color> is the default, but | 
| 114 |  |  |  |  |  |  | if output is not to a terminal, color is disabled. You can override this by | 
| 115 |  |  |  |  |  |  | adding the C<--color> switch. | 
| 116 |  |  |  |  |  |  |  | 
| 117 |  |  |  |  |  |  | Color support requires L<Term::ANSIColor> on Unix-like platforms and | 
| 118 |  |  |  |  |  |  | L<Win32::Console> on windows. If the necessary module is not installed | 
| 119 |  |  |  |  |  |  | colored output will not be available. | 
| 120 |  |  |  |  |  |  |  | 
| 121 |  |  |  |  |  |  | =head2 Exit Code | 
| 122 |  |  |  |  |  |  |  | 
| 123 |  |  |  |  |  |  | If the tests fail C<prove> will exit with non-zero status. | 
| 124 |  |  |  |  |  |  |  | 
| 125 |  |  |  |  |  |  | =head2 Arguments to Tests | 
| 126 |  |  |  |  |  |  |  | 
| 127 |  |  |  |  |  |  | It is possible to supply arguments to tests. To do so separate them from | 
| 128 |  |  |  |  |  |  | prove's own arguments with the arisdottle, '::'. For example | 
| 129 |  |  |  |  |  |  |  | 
| 130 |  |  |  |  |  |  | prove -v t/mytest.t :: --url http://example.com | 
| 131 |  |  |  |  |  |  |  | 
| 132 |  |  |  |  |  |  | would run F<t/mytest.t> with the options '--url http://example.com'. | 
| 133 |  |  |  |  |  |  | When running multiple tests they will each receive the same arguments. | 
| 134 |  |  |  |  |  |  |  | 
| 135 |  |  |  |  |  |  | =head2 C<--exec> | 
| 136 |  |  |  |  |  |  |  | 
| 137 |  |  |  |  |  |  | Normally you can just pass a list of Perl tests and the harness will know how | 
| 138 |  |  |  |  |  |  | to execute them.  However, if your tests are not written in Perl or if you | 
| 139 |  |  |  |  |  |  | want all tests invoked exactly the same way, use the C<-e>, or C<--exec> | 
| 140 |  |  |  |  |  |  | switch: | 
| 141 |  |  |  |  |  |  |  | 
| 142 |  |  |  |  |  |  | prove --exec '/usr/bin/ruby -w' t/ | 
| 143 |  |  |  |  |  |  | prove --exec '/usr/bin/perl -Tw -mstrict -Ilib' t/ | 
| 144 |  |  |  |  |  |  | prove --exec '/path/to/my/customer/exec' | 
| 145 |  |  |  |  |  |  |  | 
| 146 |  |  |  |  |  |  | =head2 C<--merge> | 
| 147 |  |  |  |  |  |  |  | 
| 148 |  |  |  |  |  |  | If you need to make sure your diagnostics are displayed in the correct | 
| 149 |  |  |  |  |  |  | order relative to test results you can use the C<--merge> option to | 
| 150 |  |  |  |  |  |  | merge the test scripts' STDERR into their STDOUT. | 
| 151 |  |  |  |  |  |  |  | 
| 152 |  |  |  |  |  |  | This guarantees that STDOUT (where the test results appear) and STDERR | 
| 153 |  |  |  |  |  |  | (where the diagnostics appear) will stay in sync. The harness will | 
| 154 |  |  |  |  |  |  | display any diagnostics your tests emit on STDERR. | 
| 155 |  |  |  |  |  |  |  | 
| 156 |  |  |  |  |  |  | Caveat: this is a bit of a kludge. In particular note that if anything | 
| 157 |  |  |  |  |  |  | that appears on STDERR looks like a test result the test harness will | 
| 158 |  |  |  |  |  |  | get confused. Use this option only if you understand the consequences | 
| 159 |  |  |  |  |  |  | and can live with the risk. | 
| 160 |  |  |  |  |  |  |  | 
| 161 |  |  |  |  |  |  | =head2 C<--trap> | 
| 162 |  |  |  |  |  |  |  | 
| 163 |  |  |  |  |  |  | The C<--trap> option will attempt to trap SIGINT (Ctrl-C) during a test | 
| 164 |  |  |  |  |  |  | run and display the test summary even if the run is interrupted | 
| 165 |  |  |  |  |  |  |  | 
| 166 |  |  |  |  |  |  | =head2 C<--state> | 
| 167 |  |  |  |  |  |  |  | 
| 168 |  |  |  |  |  |  | You can ask C<prove> to remember the state of previous test runs and | 
| 169 |  |  |  |  |  |  | select and/or order the tests to be run based on that saved state. | 
| 170 |  |  |  |  |  |  |  | 
| 171 |  |  |  |  |  |  | The C<--state> switch requires an argument which must be a comma | 
| 172 |  |  |  |  |  |  | separated list of one or more of the following options. | 
| 173 |  |  |  |  |  |  |  | 
| 174 |  |  |  |  |  |  | =over | 
| 175 |  |  |  |  |  |  |  | 
| 176 |  |  |  |  |  |  | =item C<last> | 
| 177 |  |  |  |  |  |  |  | 
| 178 |  |  |  |  |  |  | Run the same tests as the last time the state was saved. This makes it | 
| 179 |  |  |  |  |  |  | possible, for example, to recreate the ordering of a shuffled test. | 
| 180 |  |  |  |  |  |  |  | 
| 181 |  |  |  |  |  |  | # Run all tests in random order | 
| 182 |  |  |  |  |  |  | $ prove -b --state=save --shuffle | 
| 183 |  |  |  |  |  |  |  | 
| 184 |  |  |  |  |  |  | # Run them again in the same order | 
| 185 |  |  |  |  |  |  | $ prove -b --state=last | 
| 186 |  |  |  |  |  |  |  | 
| 187 |  |  |  |  |  |  | =item C<failed> | 
| 188 |  |  |  |  |  |  |  | 
| 189 |  |  |  |  |  |  | Run only the tests that failed on the last run. | 
| 190 |  |  |  |  |  |  |  | 
| 191 |  |  |  |  |  |  | # Run all tests | 
| 192 |  |  |  |  |  |  | $ prove -b --state=save | 
| 193 |  |  |  |  |  |  |  | 
| 194 |  |  |  |  |  |  | # Run failures | 
| 195 |  |  |  |  |  |  | $ prove -b --state=failed | 
| 196 |  |  |  |  |  |  |  | 
| 197 |  |  |  |  |  |  | If you also specify the C<save> option newly passing tests will be | 
| 198 |  |  |  |  |  |  | excluded from subsequent runs. | 
| 199 |  |  |  |  |  |  |  | 
| 200 |  |  |  |  |  |  | # Repeat until no more failures | 
| 201 |  |  |  |  |  |  | $ prove -b --state=failed,save | 
| 202 |  |  |  |  |  |  |  | 
| 203 |  |  |  |  |  |  | =item C<passed> | 
| 204 |  |  |  |  |  |  |  | 
| 205 |  |  |  |  |  |  | Run only the passed tests from last time. Useful to make sure that no | 
| 206 |  |  |  |  |  |  | new problems have been introduced. | 
| 207 |  |  |  |  |  |  |  | 
| 208 |  |  |  |  |  |  | =item C<all> | 
| 209 |  |  |  |  |  |  |  | 
| 210 |  |  |  |  |  |  | Run all tests in normal order. Multple options may be specified, so to | 
| 211 |  |  |  |  |  |  | run all tests with the failures from last time first: | 
| 212 |  |  |  |  |  |  |  | 
| 213 |  |  |  |  |  |  | $ prove -b --state=failed,all,save | 
| 214 |  |  |  |  |  |  |  | 
| 215 |  |  |  |  |  |  | =item C<hot> | 
| 216 |  |  |  |  |  |  |  | 
| 217 |  |  |  |  |  |  | Run the tests that most recently failed first. The last failure time of | 
| 218 |  |  |  |  |  |  | each test is stored. The C<hot> option causes tests to be run in most-recent- | 
| 219 |  |  |  |  |  |  | failure order. | 
| 220 |  |  |  |  |  |  |  | 
| 221 |  |  |  |  |  |  | $ prove -b --state=hot,save | 
| 222 |  |  |  |  |  |  |  | 
| 223 |  |  |  |  |  |  | Tests that have never failed will not be selected. To run all tests with | 
| 224 |  |  |  |  |  |  | the most recently failed first use | 
| 225 |  |  |  |  |  |  |  | 
| 226 |  |  |  |  |  |  | $ prove -b --state=hot,all,save | 
| 227 |  |  |  |  |  |  |  | 
| 228 |  |  |  |  |  |  | This combination of options may also be specified thus | 
| 229 |  |  |  |  |  |  |  | 
| 230 |  |  |  |  |  |  | $ prove -b --state=adrian | 
| 231 |  |  |  |  |  |  |  | 
| 232 |  |  |  |  |  |  | =item C<todo> | 
| 233 |  |  |  |  |  |  |  | 
| 234 |  |  |  |  |  |  | Run any tests with todos. | 
| 235 |  |  |  |  |  |  |  | 
| 236 |  |  |  |  |  |  | =item C<slow> | 
| 237 |  |  |  |  |  |  |  | 
| 238 |  |  |  |  |  |  | Run the tests in slowest to fastest order. This is useful in conjunction | 
| 239 |  |  |  |  |  |  | with the C<-j> parallel testing switch to ensure that your slowest tests | 
| 240 |  |  |  |  |  |  | start running first. | 
| 241 |  |  |  |  |  |  |  | 
| 242 |  |  |  |  |  |  | $ prove -b --state=slow -j9 | 
| 243 |  |  |  |  |  |  |  | 
| 244 |  |  |  |  |  |  | =item C<fast> | 
| 245 |  |  |  |  |  |  |  | 
| 246 |  |  |  |  |  |  | Run test tests in fastest to slowest order. | 
| 247 |  |  |  |  |  |  |  | 
| 248 |  |  |  |  |  |  | =item C<new> | 
| 249 |  |  |  |  |  |  |  | 
| 250 |  |  |  |  |  |  | Run the tests in newest to oldest order based on the modification times | 
| 251 |  |  |  |  |  |  | of the test scripts. | 
| 252 |  |  |  |  |  |  |  | 
| 253 |  |  |  |  |  |  | =item C<old> | 
| 254 |  |  |  |  |  |  |  | 
| 255 |  |  |  |  |  |  | Run the tests in oldest to newest order. | 
| 256 |  |  |  |  |  |  |  | 
| 257 |  |  |  |  |  |  | =item C<fresh> | 
| 258 |  |  |  |  |  |  |  | 
| 259 |  |  |  |  |  |  | Run those test scripts that have been modified since the last test run. | 
| 260 |  |  |  |  |  |  |  | 
| 261 |  |  |  |  |  |  | =item C<save> | 
| 262 |  |  |  |  |  |  |  | 
| 263 |  |  |  |  |  |  | Save the state on exit. The state is stored in a file called F<.prove> | 
| 264 |  |  |  |  |  |  | (F<_prove> on Windows and VMS) in the current directory. | 
| 265 |  |  |  |  |  |  |  | 
| 266 |  |  |  |  |  |  | =back | 
| 267 |  |  |  |  |  |  |  | 
| 268 |  |  |  |  |  |  | The C<--state> switch may be used more than once. | 
| 269 |  |  |  |  |  |  |  | 
| 270 |  |  |  |  |  |  | $ prove -b --state=hot --state=all,save | 
| 271 |  |  |  |  |  |  |  | 
| 272 |  |  |  |  |  |  | =head2 --rules | 
| 273 |  |  |  |  |  |  |  | 
| 274 |  |  |  |  |  |  | The C<--rules> option is used to control which tests are run sequentially and | 
| 275 |  |  |  |  |  |  | which are run in parallel, if the C<--jobs> option is specified. The option may | 
| 276 |  |  |  |  |  |  | be specified multiple times, and the order matters. | 
| 277 |  |  |  |  |  |  |  | 
| 278 |  |  |  |  |  |  | The most practical use is likely to specify that some tests are not | 
| 279 |  |  |  |  |  |  | "parallel-ready".  Since mentioning a file with --rules doesn't cause it to | 
| 280 |  |  |  |  |  |  | be selected to run as a test, you can "set and forget" some rules preferences in | 
| 281 |  |  |  |  |  |  | your .proverc file. Then you'll be able to take maximum advantage of the | 
| 282 |  |  |  |  |  |  | performance benefits of parallel testing, while some exceptions are still run | 
| 283 |  |  |  |  |  |  | in parallel. | 
| 284 |  |  |  |  |  |  |  | 
| 285 |  |  |  |  |  |  | =head3 --rules examples | 
| 286 |  |  |  |  |  |  |  | 
| 287 |  |  |  |  |  |  | # All tests are allowed to run in parallel, except those starting with "p" | 
| 288 |  |  |  |  |  |  | --rules='seq=t/p*.t' --rules='par=**' | 
| 289 |  |  |  |  |  |  |  | 
| 290 |  |  |  |  |  |  | # All tests must run in sequence except those starting with "p", which should be run parallel | 
| 291 |  |  |  |  |  |  | --rules='par=t/p*.t' | 
| 292 |  |  |  |  |  |  |  | 
| 293 |  |  |  |  |  |  | =head3 --rules resolution | 
| 294 |  |  |  |  |  |  |  | 
| 295 |  |  |  |  |  |  | =over 4 | 
| 296 |  |  |  |  |  |  |  | 
| 297 |  |  |  |  |  |  | =item * By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one. | 
| 298 |  |  |  |  |  |  |  | 
| 299 |  |  |  |  |  |  | =item * "First match wins". The first rule that matches a test will be the one that applies. | 
| 300 |  |  |  |  |  |  |  | 
| 301 |  |  |  |  |  |  | =item * Any test which does not match a rule will be run in sequence at the end of the run. | 
| 302 |  |  |  |  |  |  |  | 
| 303 |  |  |  |  |  |  | =item * The existence of a rule does not imply selecting a test. You must still specify the tests to run. | 
| 304 |  |  |  |  |  |  |  | 
| 305 |  |  |  |  |  |  | =item * Specifying a rule to allow tests to run in parallel does not make them run in parallel. You still need specify the number of parallel C<jobs> in your Harness object. | 
| 306 |  |  |  |  |  |  |  | 
| 307 |  |  |  |  |  |  | =back | 
| 308 |  |  |  |  |  |  |  | 
| 309 |  |  |  |  |  |  | =head3 --rules Glob-style pattern matching | 
| 310 |  |  |  |  |  |  |  | 
| 311 |  |  |  |  |  |  | We implement our own glob-style pattern matching for --rules. Here are the | 
| 312 |  |  |  |  |  |  | supported patterns: | 
| 313 |  |  |  |  |  |  |  | 
| 314 |  |  |  |  |  |  | ** is any number of characters, including /, within a pathname | 
| 315 |  |  |  |  |  |  | * is zero or more characters within a filename/directory name | 
| 316 |  |  |  |  |  |  | ? is exactly one character within a filename/directory name | 
| 317 |  |  |  |  |  |  | {foo,bar,baz} is any of foo, bar or baz. | 
| 318 |  |  |  |  |  |  | \ is an escape character | 
| 319 |  |  |  |  |  |  |  | 
| 320 |  |  |  |  |  |  | =head3 More advanced specifications for parallel vs sequence run rules | 
| 321 |  |  |  |  |  |  |  | 
| 322 |  |  |  |  |  |  | If you need more advanced management of what runs in parallel vs in sequence, see | 
| 323 |  |  |  |  |  |  | the associated 'rules' documentation in L<TAP::Harness> and L<TAP::Parser::Scheduler>. | 
| 324 |  |  |  |  |  |  | If what's possible directly through C<prove> is not sufficient, you can write your own | 
| 325 |  |  |  |  |  |  | harness to access these features directly. | 
| 326 |  |  |  |  |  |  |  | 
| 327 |  |  |  |  |  |  | =head2 @INC | 
| 328 |  |  |  |  |  |  |  | 
| 329 |  |  |  |  |  |  | prove introduces a separation between "options passed to the perl which | 
| 330 |  |  |  |  |  |  | runs prove" and "options passed to the perl which runs tests"; this | 
| 331 |  |  |  |  |  |  | distinction is by design. Thus the perl which is running a test starts | 
| 332 |  |  |  |  |  |  | with the default C<@INC>. Additional library directories can be added | 
| 333 |  |  |  |  |  |  | via the C<PERL5LIB> environment variable, via -Ifoo in C<PERL5OPT> or | 
| 334 |  |  |  |  |  |  | via the C<-Ilib> option to F<prove>. | 
| 335 |  |  |  |  |  |  |  | 
| 336 |  |  |  |  |  |  | =head2 Taint Mode | 
| 337 |  |  |  |  |  |  |  | 
| 338 |  |  |  |  |  |  | Normally when a Perl program is run in taint mode the contents of the | 
| 339 |  |  |  |  |  |  | C<PERL5LIB> environment variable do not appear in C<@INC>. | 
| 340 |  |  |  |  |  |  |  | 
| 341 |  |  |  |  |  |  | Because C<PERL5LIB> is often used during testing to add build | 
| 342 |  |  |  |  |  |  | directories to C<@INC> prove passes the names of any directories found | 
| 343 |  |  |  |  |  |  | in C<PERL5LIB> as -I switches. The net effect of this is that | 
| 344 |  |  |  |  |  |  | C<PERL5LIB> is honoured even when prove is run in taint mode. | 
| 345 |  |  |  |  |  |  |  | 
| 346 |  |  |  |  |  |  |  | 
| 347 |  |  |  |  |  |  | =head1 FORMATTERS | 
| 348 |  |  |  |  |  |  |  | 
| 349 |  |  |  |  |  |  | You can load a custom L<TAP::Parser::Formatter>: | 
| 350 |  |  |  |  |  |  |  | 
| 351 |  |  |  |  |  |  | prove --formatter MyFormatter | 
| 352 |  |  |  |  |  |  |  | 
| 353 |  |  |  |  |  |  | =head1 SOURCE HANDLERS | 
| 354 |  |  |  |  |  |  |  | 
| 355 |  |  |  |  |  |  | You can load custom L<TAP::Parser::SourceHandler>s, to change the way the | 
| 356 |  |  |  |  |  |  | parser interprets particular I<sources> of TAP. | 
| 357 |  |  |  |  |  |  |  | 
| 358 |  |  |  |  |  |  | prove --source MyHandler --source YetAnother t | 
| 359 |  |  |  |  |  |  |  | 
| 360 |  |  |  |  |  |  | If you want to provide config to the source you can use: | 
| 361 |  |  |  |  |  |  |  | 
| 362 |  |  |  |  |  |  | prove --source MyCustom \ | 
| 363 |  |  |  |  |  |  | --source Perl --perl-option 'foo=bar baz' --perl-option avg=0.278 \ | 
| 364 |  |  |  |  |  |  | --source File --file-option extensions=.txt --file-option extensions=.tmp t | 
| 365 |  |  |  |  |  |  | --source pgTAP --pgtap-option pset=format=html --pgtap-option pset=border=2 | 
| 366 |  |  |  |  |  |  |  | 
| 367 |  |  |  |  |  |  | Each C<--$source-option> option must specify a key/value pair separated by an | 
| 368 |  |  |  |  |  |  | C<=>. If an option can take multiple values, just specify it multiple times, | 
| 369 |  |  |  |  |  |  | as with the C<extensions=> examples above. If the option should be a hash | 
| 370 |  |  |  |  |  |  | reference, specify the value as a second pair separated by a C<=>, as in the | 
| 371 |  |  |  |  |  |  | C<pset=> examples above (escape C<=> with a backslash). | 
| 372 |  |  |  |  |  |  |  | 
| 373 |  |  |  |  |  |  | All C<--sources> are combined into a hash, and passed to L<TAP::Harness/new>'s | 
| 374 |  |  |  |  |  |  | C<sources> parameter. | 
| 375 |  |  |  |  |  |  |  | 
| 376 |  |  |  |  |  |  | See L<TAP::Parser::IteratorFactory> for more details on how configuration is | 
| 377 |  |  |  |  |  |  | passed to I<SourceHandlers>. | 
| 378 |  |  |  |  |  |  |  | 
| 379 |  |  |  |  |  |  | =head1 PLUGINS | 
| 380 |  |  |  |  |  |  |  | 
| 381 |  |  |  |  |  |  | Plugins can be loaded using the C<< -PI<plugin> >> syntax, eg: | 
| 382 |  |  |  |  |  |  |  | 
| 383 |  |  |  |  |  |  | prove -PMyPlugin | 
| 384 |  |  |  |  |  |  |  | 
| 385 |  |  |  |  |  |  | This will search for a module named C<App::Prove::Plugin::MyPlugin>, or failing | 
| 386 |  |  |  |  |  |  | that, C<MyPlugin>.  If the plugin can't be found, C<prove> will complain & exit. | 
| 387 |  |  |  |  |  |  |  | 
| 388 |  |  |  |  |  |  | You can pass arguments to your plugin by appending C<=arg1,arg2,etc> to the | 
| 389 |  |  |  |  |  |  | plugin name: | 
| 390 |  |  |  |  |  |  |  | 
| 391 |  |  |  |  |  |  | prove -PMyPlugin=fou,du,fafa | 
| 392 |  |  |  |  |  |  |  | 
| 393 |  |  |  |  |  |  | Please check individual plugin documentation for more details. | 
| 394 |  |  |  |  |  |  |  | 
| 395 |  |  |  |  |  |  | =head2 Available Plugins | 
| 396 |  |  |  |  |  |  |  | 
| 397 |  |  |  |  |  |  | For an up-to-date list of plugins available, please check CPAN: | 
| 398 |  |  |  |  |  |  |  | 
| 399 |  |  |  |  |  |  | L<http://search.cpan.org/search?query=App%3A%3AProve+Plugin> | 
| 400 |  |  |  |  |  |  |  | 
| 401 |  |  |  |  |  |  | =head2 Writing Plugins | 
| 402 |  |  |  |  |  |  |  | 
| 403 |  |  |  |  |  |  | Please see L<App::Prove/PLUGINS>. | 
| 404 |  |  |  |  |  |  |  | 
| 405 |  |  |  |  |  |  | =cut | 
| 406 |  |  |  |  |  |  |  | 
| 407 |  |  |  |  |  |  | # vim:ts=4:sw=4:et:sta |