diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1/prove.1')
| -rw-r--r-- | upstream/mageia-cauldron/man1/prove.1 | 478 |
1 files changed, 478 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1/prove.1 b/upstream/mageia-cauldron/man1/prove.1 new file mode 100644 index 00000000..77b3587b --- /dev/null +++ b/upstream/mageia-cauldron/man1/prove.1 @@ -0,0 +1,478 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PROVE 1" +.TH PROVE 1 2023-12-15 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +prove \- Run tests through a TAP harness. +.SH USAGE +.IX Header "USAGE" +.Vb 1 +\& prove [options] [files or directories] +.Ve +.SH OPTIONS +.IX Header "OPTIONS" +Boolean options: +.PP +.Vb 10 +\& \-v, \-\-verbose Print all test lines. +\& \-l, \-\-lib Add \*(Aqlib\*(Aq to the path for your tests (\-Ilib). +\& \-b, \-\-blib Add \*(Aqblib/lib\*(Aq and \*(Aqblib/arch\*(Aq to the path for +\& your tests +\& \-s, \-\-shuffle Run the tests in random order. +\& \-c, \-\-color Colored test output (default). +\& \-\-nocolor Do not color test output. +\& \-\-count Show the X/Y test count when not verbose +\& (default) +\& \-\-nocount Disable the X/Y test count. +\& \-D \-\-dry Dry run. Show test that would have run. +\& \-f, \-\-failures Show failed tests. +\& \-o, \-\-comments Show comments. +\& \-\-ignore\-exit Ignore exit status from test scripts. +\& \-m, \-\-merge Merge test scripts\*(Aq STDERR with their STDOUT. +\& \-r, \-\-recurse Recursively descend into directories. +\& \-\-reverse Run the tests in reverse order. +\& \-q, \-\-quiet Suppress some test output while running tests. +\& \-Q, \-\-QUIET Only print summary results. +\& \-p, \-\-parse Show full list of TAP parse errors, if any. +\& \-\-directives Only show results with TODO or SKIP directives. +\& \-\-timer Print elapsed time after each test. +\& \-\-trap Trap Ctrl\-C and print summary on interrupt. +\& \-\-normalize Normalize TAP output in verbose output +\& \-T Enable tainting checks. +\& \-t Enable tainting warnings. +\& \-W Enable fatal warnings. +\& \-w Enable warnings. +\& \-h, \-\-help Display this help +\& \-?, Display this help +\& \-V, \-\-version Display the version +\& \-H, \-\-man Longer manpage for prove +\& \-\-norc Don\*(Aqt process default .proverc +.Ve +.PP +Options that take arguments: +.PP +.Vb 10 +\& \-I Library paths to include. +\& \-P Load plugin (searches App::Prove::Plugin::*.) +\& \-M Load a module. +\& \-e, \-\-exec Interpreter to run the tests (\*(Aq\*(Aq for compiled +\& tests.) +\& \-\-ext Set the extension for tests (default \*(Aq.t\*(Aq) +\& \-\-harness Define test harness to use. See TAP::Harness. +\& \-\-formatter Result formatter to use. See FORMATTERS. +\& \-\-source Load and/or configure a SourceHandler. See +\& SOURCE HANDLERS. +\& \-a, \-\-archive out.tgz Store the resulting TAP in an archive file. +\& \-j, \-\-jobs N Run N test jobs in parallel (try 9.) +\& \-\-state=opts Control prove\*(Aqs persistent state. +\& \-\-statefile=file Use \`file\` instead of \`.prove\` for state +\& \-\-rc=rcfile Process options from rcfile +\& \-\-rules Rules for parallel vs sequential processing. +.Ve +.SH NOTES +.IX Header "NOTES" +.SS .proverc +.IX Subsection ".proverc" +If \fI~/.proverc\fR or \fI./.proverc\fR exist they will be read and any +options they contain processed before the command line options. Options +in \fI.proverc\fR are specified in the same way as command line options: +.PP +.Vb 3 +\& # .proverc +\& \-\-state=hot,fast,save +\& \-j9 +.Ve +.PP +Additional option files may be specified with the \f(CW\*(C`\-\-rc\*(C'\fR option. +Default option file processing is disabled by the \f(CW\*(C`\-\-norc\*(C'\fR option. +.PP +Under Windows and VMS the option file is named \fI_proverc\fR rather than +\&\fI.proverc\fR and is sought only in the current directory. +.ie n .SS "Reading from ""STDIN""" +.el .SS "Reading from \f(CWSTDIN\fP" +.IX Subsection "Reading from STDIN" +If you have a list of tests (or URLs, or anything else you want to test) in a +file, you can add them to your tests by using a '\-': +.PP +.Vb 1 +\& prove \- < my_list_of_things_to_test.txt +.Ve +.PP +See the \f(CW\*(C`README\*(C'\fR in the \f(CW\*(C`examples\*(C'\fR directory of this distribution. +.SS "Default Test Directory" +.IX Subsection "Default Test Directory" +If no files or directories are supplied, \f(CW\*(C`prove\*(C'\fR looks for all files +matching the pattern \f(CW\*(C`t/*.t\*(C'\fR. +.SS "Colored Test Output" +.IX Subsection "Colored Test Output" +Colored test output using TAP::Formatter::Color is the default, but +if output is not to a terminal, color is disabled. You can override this by +adding the \f(CW\*(C`\-\-color\*(C'\fR switch. +.PP +Color support requires Term::ANSIColor and, on windows platforms, also +Win32::Console::ANSI. If the necessary module(s) are not installed +colored output will not be available. +.SS "Exit Code" +.IX Subsection "Exit Code" +If the tests fail \f(CW\*(C`prove\*(C'\fR will exit with non-zero status. +.SS "Arguments to Tests" +.IX Subsection "Arguments to Tests" +It is possible to supply arguments to tests. To do so separate them from +prove's own arguments with the arisdottle, '::'. For example +.PP +.Vb 1 +\& prove \-v t/mytest.t :: \-\-url http://example.com +.Ve +.PP +would run \fIt/mytest.t\fR with the options '\-\-url http://example.com'. +When running multiple tests they will each receive the same arguments. +.ie n .SS """\-\-exec""" +.el .SS \f(CW\-\-exec\fP +.IX Subsection "--exec" +Normally you can just pass a list of Perl tests and the harness will know how +to execute them. However, if your tests are not written in Perl or if you +want all tests invoked exactly the same way, use the \f(CW\*(C`\-e\*(C'\fR, or \f(CW\*(C`\-\-exec\*(C'\fR +switch: +.PP +.Vb 3 +\& prove \-\-exec \*(Aq/usr/bin/ruby \-w\*(Aq t/ +\& prove \-\-exec \*(Aq/usr/bin/perl \-Tw \-mstrict \-Ilib\*(Aq t/ +\& prove \-\-exec \*(Aq/path/to/my/customer/exec\*(Aq +.Ve +.ie n .SS """\-\-merge""" +.el .SS \f(CW\-\-merge\fP +.IX Subsection "--merge" +If you need to make sure your diagnostics are displayed in the correct +order relative to test results you can use the \f(CW\*(C`\-\-merge\*(C'\fR option to +merge the test scripts' STDERR into their STDOUT. +.PP +This guarantees that STDOUT (where the test results appear) and STDERR +(where the diagnostics appear) will stay in sync. The harness will +display any diagnostics your tests emit on STDERR. +.PP +Caveat: this is a bit of a kludge. In particular note that if anything +that appears on STDERR looks like a test result the test harness will +get confused. Use this option only if you understand the consequences +and can live with the risk. +.ie n .SS """\-\-trap""" +.el .SS \f(CW\-\-trap\fP +.IX Subsection "--trap" +The \f(CW\*(C`\-\-trap\*(C'\fR option will attempt to trap SIGINT (Ctrl-C) during a test +run and display the test summary even if the run is interrupted +.ie n .SS """\-\-state""" +.el .SS \f(CW\-\-state\fP +.IX Subsection "--state" +You can ask \f(CW\*(C`prove\*(C'\fR to remember the state of previous test runs and +select and/or order the tests to be run based on that saved state. +.PP +The \f(CW\*(C`\-\-state\*(C'\fR switch requires an argument which must be a comma +separated list of one or more of the following options. +.ie n .IP """last""" 4 +.el .IP \f(CWlast\fR 4 +.IX Item "last" +Run the same tests as the last time the state was saved. This makes it +possible, for example, to recreate the ordering of a shuffled test. +.Sp +.Vb 2 +\& # Run all tests in random order +\& $ prove \-b \-\-state=save \-\-shuffle +\& +\& # Run them again in the same order +\& $ prove \-b \-\-state=last +.Ve +.ie n .IP """failed""" 4 +.el .IP \f(CWfailed\fR 4 +.IX Item "failed" +Run only the tests that failed on the last run. +.Sp +.Vb 2 +\& # Run all tests +\& $ prove \-b \-\-state=save +\& +\& # Run failures +\& $ prove \-b \-\-state=failed +.Ve +.Sp +If you also specify the \f(CW\*(C`save\*(C'\fR option newly passing tests will be +excluded from subsequent runs. +.Sp +.Vb 2 +\& # Repeat until no more failures +\& $ prove \-b \-\-state=failed,save +.Ve +.ie n .IP """passed""" 4 +.el .IP \f(CWpassed\fR 4 +.IX Item "passed" +Run only the passed tests from last time. Useful to make sure that no +new problems have been introduced. +.ie n .IP """all""" 4 +.el .IP \f(CWall\fR 4 +.IX Item "all" +Run all tests in normal order. Multiple options may be specified, so to +run all tests with the failures from last time first: +.Sp +.Vb 1 +\& $ prove \-b \-\-state=failed,all,save +.Ve +.ie n .IP """hot""" 4 +.el .IP \f(CWhot\fR 4 +.IX Item "hot" +Run the tests that most recently failed first. The last failure time of +each test is stored. The \f(CW\*(C`hot\*(C'\fR option causes tests to be run in most\-recent\- +failure order. +.Sp +.Vb 1 +\& $ prove \-b \-\-state=hot,save +.Ve +.Sp +Tests that have never failed will not be selected. To run all tests with +the most recently failed first use +.Sp +.Vb 1 +\& $ prove \-b \-\-state=hot,all,save +.Ve +.Sp +This combination of options may also be specified thus +.Sp +.Vb 1 +\& $ prove \-b \-\-state=adrian +.Ve +.ie n .IP """todo""" 4 +.el .IP \f(CWtodo\fR 4 +.IX Item "todo" +Run any tests with todos. +.ie n .IP """slow""" 4 +.el .IP \f(CWslow\fR 4 +.IX Item "slow" +Run the tests in slowest to fastest order. This is useful in conjunction +with the \f(CW\*(C`\-j\*(C'\fR parallel testing switch to ensure that your slowest tests +start running first. +.Sp +.Vb 1 +\& $ prove \-b \-\-state=slow \-j9 +.Ve +.ie n .IP """fast""" 4 +.el .IP \f(CWfast\fR 4 +.IX Item "fast" +Run test tests in fastest to slowest order. +.ie n .IP """new""" 4 +.el .IP \f(CWnew\fR 4 +.IX Item "new" +Run the tests in newest to oldest order based on the modification times +of the test scripts. +.ie n .IP """old""" 4 +.el .IP \f(CWold\fR 4 +.IX Item "old" +Run the tests in oldest to newest order. +.ie n .IP """fresh""" 4 +.el .IP \f(CWfresh\fR 4 +.IX Item "fresh" +Run those test scripts that have been modified since the last test run. +.ie n .IP """save""" 4 +.el .IP \f(CWsave\fR 4 +.IX Item "save" +Save the state on exit. The state is stored in a file called \fI.prove\fR +(\fI_prove\fR on Windows and VMS) in the current directory. +.PP +The \f(CW\*(C`\-\-state\*(C'\fR switch may be used more than once. +.PP +.Vb 1 +\& $ prove \-b \-\-state=hot \-\-state=all,save +.Ve +.SS \-\-rules +.IX Subsection "--rules" +The \f(CW\*(C`\-\-rules\*(C'\fR option is used to control which tests are run sequentially and +which are run in parallel, if the \f(CW\*(C`\-\-jobs\*(C'\fR option is specified. The option may +be specified multiple times, and the order matters. +.PP +The most practical use is likely to specify that some tests are not +"parallel-ready". Since mentioning a file with \-\-rules doesn't cause it to +be selected to run as a test, you can "set and forget" some rules preferences in +your .proverc file. Then you'll be able to take maximum advantage of the +performance benefits of parallel testing, while some exceptions are still run +in parallel. +.PP +\fI\-\-rules examples\fR +.IX Subsection "--rules examples" +.PP +.Vb 2 +\& # All tests are allowed to run in parallel, except those starting with "p" +\& \-\-rules=\*(Aqseq=t/p*.t\*(Aq \-\-rules=\*(Aqpar=**\*(Aq +\& +\& # All tests must run in sequence except those starting with "p", which should be run parallel +\& \-\-rules=\*(Aqpar=t/p*.t\*(Aq +.Ve +.PP +\fI\-\-rules resolution\fR +.IX Subsection "--rules resolution" +.IP \(bu 4 +By default, all tests are eligible to be run in parallel. Specifying any of your own rules removes this one. +.IP \(bu 4 +"First match wins". The first rule that matches a test will be the one that applies. +.IP \(bu 4 +Any test which does not match a rule will be run in sequence at the end of the run. +.IP \(bu 4 +The existence of a rule does not imply selecting a test. You must still specify the tests to run. +.IP \(bu 4 +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 \f(CW\*(C`jobs\*(C'\fR in your Harness object. +.PP +\fI\-\-rules Glob-style pattern matching\fR +.IX Subsection "--rules Glob-style pattern matching" +.PP +We implement our own glob-style pattern matching for \-\-rules. Here are the +supported patterns: +.PP +.Vb 5 +\& ** is any number of characters, including /, within a pathname +\& * is zero or more characters within a filename/directory name +\& ? is exactly one character within a filename/directory name +\& {foo,bar,baz} is any of foo, bar or baz. +\& \e is an escape character +.Ve +.PP +\fIMore advanced specifications for parallel vs sequence run rules\fR +.IX Subsection "More advanced specifications for parallel vs sequence run rules" +.PP +If you need more advanced management of what runs in parallel vs in sequence, see +the associated 'rules' documentation in TAP::Harness and TAP::Parser::Scheduler. +If what's possible directly through \f(CW\*(C`prove\*(C'\fR is not sufficient, you can write your own +harness to access these features directly. +.ie n .SS @INC +.el .SS \f(CW@INC\fP +.IX Subsection "@INC" +prove introduces a separation between "options passed to the perl which +runs prove" and "options passed to the perl which runs tests"; this +distinction is by design. Thus the perl which is running a test starts +with the default \f(CW@INC\fR. Additional library directories can be added +via the \f(CW\*(C`PERL5LIB\*(C'\fR environment variable, via \-Ifoo in \f(CW\*(C`PERL5OPT\*(C'\fR or +via the \f(CW\*(C`\-Ilib\*(C'\fR option to \fIprove\fR. +.SS "Taint Mode" +.IX Subsection "Taint Mode" +Normally when a Perl program is run in taint mode the contents of the +\&\f(CW\*(C`PERL5LIB\*(C'\fR environment variable do not appear in \f(CW@INC\fR. +.PP +Because \f(CW\*(C`PERL5LIB\*(C'\fR is often used during testing to add build +directories to \f(CW@INC\fR prove passes the names of any directories found +in \f(CW\*(C`PERL5LIB\*(C'\fR as \-I switches. The net effect of this is that +\&\f(CW\*(C`PERL5LIB\*(C'\fR is honoured even when prove is run in taint mode. +.SH FORMATTERS +.IX Header "FORMATTERS" +You can load a custom TAP::Parser::Formatter: +.PP +.Vb 1 +\& prove \-\-formatter MyFormatter +.Ve +.SH "SOURCE HANDLERS" +.IX Header "SOURCE HANDLERS" +You can load custom TAP::Parser::SourceHandlers, to change the way the +parser interprets particular \fIsources\fR of TAP. +.PP +.Vb 1 +\& prove \-\-source MyHandler \-\-source YetAnother t +.Ve +.PP +If you want to provide config to the source you can use: +.PP +.Vb 4 +\& prove \-\-source MyCustom \e +\& \-\-source Perl \-\-perl\-option \*(Aqfoo=bar baz\*(Aq \-\-perl\-option avg=0.278 \e +\& \-\-source File \-\-file\-option extensions=.txt \-\-file\-option extensions=.tmp t +\& \-\-source pgTAP \-\-pgtap\-option pset=format=html \-\-pgtap\-option pset=border=2 +.Ve +.PP +Each \f(CW\*(C`\-\-$source\-option\*(C'\fR option must specify a key/value pair separated by an +\&\f(CW\*(C`=\*(C'\fR. If an option can take multiple values, just specify it multiple times, +as with the \f(CW\*(C`extensions=\*(C'\fR examples above. If the option should be a hash +reference, specify the value as a second pair separated by a \f(CW\*(C`=\*(C'\fR, as in the +\&\f(CW\*(C`pset=\*(C'\fR examples above (escape \f(CW\*(C`=\*(C'\fR with a backslash). +.PP +All \f(CW\*(C`\-\-sources\*(C'\fR are combined into a hash, and passed to "new" in TAP::Harness's +\&\f(CW\*(C`sources\*(C'\fR parameter. +.PP +See TAP::Parser::IteratorFactory for more details on how configuration is +passed to \fISourceHandlers\fR. +.SH PLUGINS +.IX Header "PLUGINS" +Plugins can be loaded using the \f(CW\*(C`\-P\fR\f(CIplugin\fR\f(CW\*(C'\fR syntax, eg: +.PP +.Vb 1 +\& prove \-PMyPlugin +.Ve +.PP +This will search for a module named \f(CW\*(C`App::Prove::Plugin::MyPlugin\*(C'\fR, or failing +that, \f(CW\*(C`MyPlugin\*(C'\fR. If the plugin can't be found, \f(CW\*(C`prove\*(C'\fR will complain & exit. +.PP +You can pass arguments to your plugin by appending \f(CW\*(C`=arg1,arg2,etc\*(C'\fR to the +plugin name: +.PP +.Vb 1 +\& prove \-PMyPlugin=fou,du,fafa +.Ve +.PP +Please check individual plugin documentation for more details. +.SS "Available Plugins" +.IX Subsection "Available Plugins" +For an up-to-date list of plugins available, please check CPAN: +.PP +<http://search.cpan.org/search?query=App%3A%3AProve+Plugin> +.SS "Writing Plugins" +.IX Subsection "Writing Plugins" +Please see "PLUGINS" in App::Prove. |