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 -e, or --exec switch:

If you need to make sure your diagnostics are displayed in the correct order relative to test results you can use the --merge option to merge the test scripts' STDERR into their STDOUT.

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.

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.

The --rules option is used to control which tests are run sequentially and which are run in parallel, if the --jobs option is specified. The option may be specified multiple times, and the order matters.

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.

# All tests are allowed to run in parallel, except those starting with "p"
--rules='seq=t/p*.t' --rules='par=**'
# All tests must run in sequence except those starting with "p", which should be run parallel
--rules='par=t/p*.t'

We implement our own glob-style pattern matching for --rules. Here are the supported patterns:

** 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.
\ is an escape character

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 prove is not sufficient, you can write your own harness to access these features directly.

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 @INC. Additional library directories can be added via the PERL5LIB environment variable, via -Ifoo in PERL5OPT or via the -Ilib option to prove.

Normally when a Perl program is run in taint mode the contents of the PERL5LIB environment variable do not appear in @INC.

Because PERL5LIB is often used during testing to add build directories to @INC prove passes the names of any directories found in PERL5LIB as -I switches. The net effect of this is that PERL5LIB is honoured even when prove is run in taint mode.

Each --$source-option option must specify a key/value pair separated by an =. If an option can take multiple values, just specify it multiple times, as with the extensions= examples above. If the option should be a hash reference, specify the value as a second pair separated by a =, as in the pset= examples above (escape = with a backslash).