PROVE(1p)

✨ NAME ✨

okay bestie, welcome to PROVE(1p), aka prove(1p), straight from User Contributed Perl Documentation. This page is literally about prove — run tests through a TAP harness. That's the assignment. periodt. 💅

---

🚀 USAGE 🚀

the vibe check is exactly this:

prove [options] [files or directories]

---

🔥 OPTIONS 🔥

okay so prove has a whole wardrobe of options. first up: the boolean ones — on/off, no argument, just vibes. then the ones that need a lil argument, bestie. 🫶

🔘 Boolean options:

• -v, --verbose — print all test lines. also sets TEST_VERBOSE. yes bestie, it's giving very chatty. 😭
• -l, --lib — adds 'lib' to the path for your tests, aka the (-Ilib) move.
• -b, --blib — adds 'blib/lib' and 'blib/arch' to the path for your tests.
• -s, --shuffle — runs the tests in random order. chaos, but make it TAP. 🎲
• -c, --color — colored test output, and yes it's the default. slay. 🌈
• --nocolor — do not color test output. beige era, respectfully.
• --count — shows the X/Y test count when not verbose, and it's the default.
• --nocount — disables the X/Y test count.
• -D, --dry — dry run. shows the test that would have run. no actual running, just looking. 👀
• -f, --failures — shows failed tests. the tea we actually need. 🍵
• -o, --comments — shows comments.
• --ignore-exit — ignores exit status from test scripts.
• -m, --merge — merges test scripts' STDERR with their STDOUT.
• -r, --recurse — recursively descends into directories. down the rabbit hole. 🐇
• --reverse — runs the tests in reverse order. backwards but make it fashion.
• -q, --quiet — suppresses some test output while running tests.
• -Q, --QUIET — only prints summary results. minimalism, but uppercase.
• -p, --parse — shows the full list of TAP parse errors, if any. receipts. 🧾
• --directives — only shows results with TODO or SKIP directives.
• --timer — prints elapsed time after each test. ⏱️
• --trap — traps Ctrl-C and prints summary on interrupt. safety but cute.
• --normalize — normalizes TAP output in verbose output.
• -T — enables tainting checks.
• -t — enables tainting warnings.
• -W — enables fatal warnings.
• -w — enables warnings.
• -h, --help — displays this help.
• -? — also displays this help.
• -V, --version — displays the version.
• -H, --man — longer manpage for prove.
• --norc — don't process default .proverc.

🎀 Options that take arguments:

• -I — library paths to include.
• -P — load plugin (searches App::Prove::Plugin::*.)
• -M — load a module.
• -e, --exec — interpreter to run the tests ('' for compiled tests.)
• --ext — sets the extension for tests, default '.t'.
• --harness — defines the 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 — stores the resulting TAP in an archive file.
• -j, --jobs N — runs N test jobs in parallel (try 9.)
• --state=opts — control prove's persistent state.
• --statefile=file — use file instead of .prove for state.
• --rc=rcfile — process options from rcfile.
• --rules — rules for parallel vs sequential processing.

🌸 NOTES 🌸

🎀 ~/.proverc / ./.proverc 🎀

okay so bestie, if ~/.proverc or ./.proverc exist, prove reads them and processes whatever options are in there before it even looks at your command line options. and the options inside go in exactly the same way you'd type them on the command line:

# .proverc
--state=hot,fast,save
-j9

you can point at extra option files with the --rc option. and if you want none of this default option-file business at all, the --norc option turns it off. 💅

under Windows and VMS the file is called _proverc instead of .proverc, and it's only looked for in the current directory. no ~ vibes there.

📥 Reading from STDIN 📥

got a whole list of tests (or URLs, or literally anything you wanna test) sitting in a file? just feed them in with a -:

prove - < my_list_of_things_to_test.txt

there's a README in the examples directory of this distribution if you want the full tea. 🫶

📁 Default Test Directory 📁

if you don't hand prove any files or directories, it goes looking for every file matching the pattern t/*.t. she's got a favorite spot fr.

🌈 Colored Test Output 🌈

colored output via TAP::Formatter::Color is the default, but if output isn't going to a terminal, the color is switched off. you can force it back on by adding the --color switch.

color support needs Term::ANSIColor and, on windows platforms, also Win32::Console::ANSI. if those modules aren't installed, sorry bestie, no colored output available. 💀

🚪 Exit Code 🚪

if the tests fail, prove exits with non-zero status. that's the whole thing. it's giving "nope". 😭

🗣️ Arguments to Tests 🗣️

you can pass arguments to your tests! just separate them from prove's own arguments with the arisdottle, '::'. like so:

prove -v t/mytest.t :: --url http://example.com

that runs t/mytest.t with the options '--url http://example.com'. and when you're running multiple tests, every single one of them gets the same arguments. equal treatment, iconic behavior. 👑

🏃 --exec 🏃

normally you just hand over a list of Perl tests and the harness figures out how to execute them, no thoughts required. but if your tests aren't written in Perl, or you want every test invoked exactly the same way, use the -e or --exec switch:

prove --exec '/usr/bin/ruby -w' t/
prove --exec '/usr/bin/perl -Tw -mstrict -Ilib' t/
prove --exec '/path/to/my/customer/exec'

🔀 --merge 🔀

need your diagnostics to show up in the correct order relative to your test results? the --merge option merges the test scripts' STDERR into their STDOUT.

this guarantees STDOUT (where the test results appear) and STDERR (where the diagnostics appear) stay in sync. the harness will display any diagnostics your tests emit on STDERR. obsessed. ✨

Caveat bestie, and this one's real: this is a bit of a kludge. in particular, note that if anything appearing on STDERR looks like a test result, the test harness will get confused. only use this option if you understand the consequences and can live with the risk. ⚠️

🪤 --trap 🪤

the --trap option will attempt to trap SIGINT (Ctrl-C) during a test run and display the test summary even if the run gets interrupted. she doesn't give up, she reports. 💅

💾 --state 💾

you can ask prove to remember the state of previous test runs and then select and/or order the tests to be run based on that saved state.

the --state switch requires an argument, and that argument has to be a comma separated list of one or more of the following options:

"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.

# Run all tests in random order
$ prove -b --state=save --shuffle

# Run them again in the same order
$ prove -b --state=last

"failed"

run only the tests that failed on the last run.

# Run all tests
$ prove -b --state=save

# Run failures
$ prove -b --state=failed

if you also specify the "save" option, newly passing tests get excluded from subsequent runs. glow-up behavior. 🌸

# Repeat until no more failures
$ prove -b --state=failed,save

"passed"

run only the passed tests from last time. useful to make sure no new problems have been introduced. 🧚

"all"

run all tests in normal order. you can specify multiple options, so to run all tests with the failures from last time first:

$ prove -b --state=failed,all,save

"hot"

run the tests that most recently failed first. the last failure time of each test is stored, and the "hot" option causes tests to be run in most-recent-failure order.

$ prove -b --state=hot,save

tests that have never failed will not be selected. if you want to run all tests with the most recently failed first, use:

$ prove -b --state=hot,all,save

this combination of options may also be specified thus:

$ prove -b --state=adrian

(yes really, that's a real alias, she said what she said 😌)

"todo"

run any tests with todos.

"slow"

run the tests in slowest to fastest order. this is useful in conjunction with the -j parallel testing switch to make sure your slowest tests start running first. 🔥

$ prove -b --state=slow -j9

"fast"

run test tests in fastest to slowest order.

"new"

run the tests in newest to oldest order based on the modification times of the test scripts.

"old"

run the tests in oldest to newest order.

"fresh"

run those test scripts that have been modified since the last test run.

"save"

save the state on exit. the state is stored in a file called .prove (_prove on Windows and VMS) in the current directory.

the --state switch may be used more than once.

$ prove -b --state=hot --state=all,save

📏 --rules 📏

the --rules option controls which tests run sequentially and which run in parallel, if the --jobs option is specified. it may be specified multiple times, and the order matters.

the most practical use is probably telling prove 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 get maximum advantage of the performance benefits of parallel testing, while some exceptions still run in parallel. bestie that's the dream setup. 💖

--rules examples

# 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'

--rules resolution

• by default, all tests are eligible to be run in parallel. specifying any of your own rules removes this one.
• "First match wins". the first rule that matches a test will be the one that applies.
• any test which does not match a rule will be run in sequence at the end of the run.
• the existence of a rule does not imply selecting a test. you must still specify the tests to run.
• specifying a rule to allow tests to run in parallel does not make them run in parallel. you still need to specify the number of parallel "jobs" in your Harness object.

--rules Glob-style pattern matching

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

More advanced specifications for parallel vs sequence run rules

if you need more advanced management of what runs in parallel vs in sequence, check out the associated 'rules' documentation in TAP::Harness and TAP::Parser::Scheduler. if what's possible directly through prove isn't sufficient, you can write your own harness to access those features directly. main character move, honestly. 👑

📚 @INC 📚

prove introduces a separation between "options passed to the perl which runs prove" and "options passed to the perl which runs tests" — and that distinction is by design. so the perl that's running a test starts with the default @INC. you can add extra library directories via the PERL5LIB environment variable, via -Ifoo in PERL5OPT, or via the -Ilib option to prove.

🛡️ Taint Mode 🛡️

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

but 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 is that PERL5LIB is honoured even when prove is run in taint mode. she looks out for you fr fr. 🫶

---

💅 FORMATTERS 💅

you can load a custom TAP::Parser::Formatter:

prove --formatter MyFormatter

---

🔌 SOURCE HANDLERS 🔌

you can load custom TAP::Parser::SourceHandlers to change the way the parser interprets particular sources of TAP.

prove --source MyHandler --source YetAnother t

if you want to provide config to the source you can use:

prove --source MyCustom \
      --source Perl --perl-option 'foo=bar baz' --perl-option avg=0.278 \
      --source File --file-option extensions=.txt --file-option extensions=.tmp t
      --source pgTAP --pgtap-option pset=format=html --pgtap-option pset=border=2

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, like 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).

all --sources are combined into a hash, and passed to new in TAP::Harness's sources parameter.

see TAP::Parser::IteratorFactory for more details on how configuration is passed to SourceHandlers. ✨

---

🧩 PLUGINS 🧩

plugins can be loaded using the -Pplugin syntax, eg:

prove -PMyPlugin

this will search for a module named App::Prove::Plugin::MyPlugin, or failing that, MyPlugin. if the plugin can't be found, prove will complain & exit. 😭

you can pass arguments to your plugin by appending =arg1,arg2,etc to the plugin name:

prove -PMyPlugin=fou,du,fafa

please check individual plugin documentation for more details.

🌟 Available Plugins 🌟

for an up-to-date list of plugins available, please check CPAN:

<https://metacpan.org/search?q=App%3A%3AProve+Plugin>

✍️ Writing Plugins ✍️

please see "PLUGINS" in App::Prove.

---

and that's a wrap bestie!! 🎀 this page is from perl v5.40.1, dated 2025-08-10 — go forth and prove all the things, you've got this 💖✨🦋