prove

prove [options] [files_or_directories...]

-b, --bail
    Stop running tests immediately upon the first test file failure.

-h, --help
    Display a brief help message and exit.

-I dir, --inc dir
    Add dir to the Perl include path (@INC).

-j N, --jobs N
    Run tests in parallel with N concurrent jobs.

-l, --lib
    Add 'blib/lib' and 'blib/arch' to @INC, useful for testing modules during development.

-P, --parseable
    Output test results in a machine-parseable format (TAP).

-q, --quiet
    Suppress normal test output; only show the summary and any failures.

-r, --recurse
    Recursively search subdirectories for test files.

-s, --shuffle
    Run test files in a random order.

-t, --timer
    Display the time taken for each test file to run.

-T, --trap
    Trap child process errors and report them as test failures.

-v, --verbose
    Display verbose output for each test, showing individual assertions.

-V, --version
    Display version information and exit.

-x path, --exec path
    Specify the Perl interpreter to use for running tests (e.g., perl -w).

--ext suffix
    Look for test files ending with the specified suffix instead of .t.

--formatter module
    Use a custom Perl module to format test results.

--input type
    Specify the input format type, e.g., TAP.

--merge
    Merge state files from previous runs to run only failed tests.

--no-bail
    Do not stop on the first test file failure (default behavior).

--only
    Only run tests that failed on the previous run (requires a state file).

--order type
    Specify the order in which to run tests: alpha, file, random, or test.

--state file
    Read and write test state information to the specified file.

--state-only
    Update the state file without actually running tests.

--suppress-state
    Do not read or write any state information.

--tty
    Force TTY-style progress output, even if stdout is not a TTY.

prove is a powerful command-line utility bundled with the Perl distribution, designed to execute Perl test scripts. Acting as an advanced front-end to Perl's Test::Harness module, it processes one or more test files (typically with a .t extension) and reports their results.

It fully supports the Test Anything Protocol (TAP) output generated by standard Perl test modules, presenting detailed and human-readable test outcomes. prove offers extensive options for controlling test execution, including parallel test runs, selective test execution, verbose output, and robust failure handling. This makes it an indispensable tool for Perl developers, essential for unit testing, integration testing, and automated build systems.

prove is primarily designed for running Perl test scripts that adhere to the Test Anything Protocol (TAP). It may not be suitable for testing applications written in other programming languages without a TAP output adapter. When using parallel execution (-j option), ensure your test suite is robust against race conditions and inter-test dependencies, as parallel runs can expose subtle issues that might not appear in serial execution.

prove's default output format is based on TAP, a simple text-based protocol for reporting test results. Understanding TAP is beneficial for writing custom test modules or parsing prove's output programmatically.

The exit status of prove is crucial for scripting and CI pipelines: a status of 0 indicates all tests passed, while any non-zero status signifies test failures or other errors. This allows build systems to reliably determine the success or failure of a test run.

prove's behavior can be influenced by environment variables, notably HARNESS_OPTIONS, which allows setting default options (e.g., verbose mode, timer) without explicitly typing them on the command line for every execution.

Before the advent of prove, Perl developers typically relied on `make test` or manual execution of test scripts via `perl -MTest::Harness -e 'runtests @ARGV'`. While functional, these methods lacked the flexibility and advanced features that modern testing demands.

prove was introduced as a dedicated command-line tool, built atop the existing Test::Harness framework, to provide a more user-friendly and feature-rich interface for running Perl unit tests. Its development focused on simplifying test execution, offering options like parallel processing, verbose output, and better integration with continuous integration systems through its support for TAP. It quickly became the standard tool for automated Perl testing.

perl(1), Test::Harness(3pm), Test::More(3pm), make(1), xargs(1)