Running Tests

Test Harness: t/TEST

PetaPerl’s test harness is t/TEST, a Perl 5 script that runs each .t file under both perl and pperl, then compares output. A test passes when pperl’s output matches perl5’s output exactly.

t/TEST [OPTIONS] [FILTERS...]

The harness is executable — run it directly, never as perl t/TEST.

Filter Semantics

Positional arguments are substring filters with OR logic:

t/TEST 00-base                    # Run tests matching "00-base"
t/TEST 00-base 05-op              # Run tests matching "00-base" OR "05-op"
t/TEST 25-regex/010-basic.t       # Run a specific test file

Negative filtering via --skip:

t/TEST --skip=bytecode,tier,debug # Run all except these categories

When using a positive filter, --skip is unnecessary — the filter already limits scope.

Options

Option	Description
`-v, --verbose`	Show diffs on failure
`-m, --monitor`	Show memory/time stats per test
`-c, --compare`	Compare against previous run in `t/.results/`
`--skip=PATTERN`	Skip tests matching substring (comma-separated)
`--no-bail`	Continue even if 00-base tests fail
`--no-save`	Don’t save results to `.results/`
`--timeout=SECS`	Timeout per test (default: 5)
`--memory=MB`	Memory limit per test (default: 512)
`--pperl-flags=STR`	Override default pperl flags
`-h, --help`	Show help

Default pperl Flags

The harness runs pperl with --no-jit --no-parallel by default. This ensures tests exercise the interpreter, not the JIT or parallelization engine.

Override per-test via a comment header in the test file:

# pperl-cli: -(--no-jit)

This removes --no-jit from the flags, enabling JIT for that test. Override globally:

t/TEST --pperl-flags="--no-timeout"

Result Tracking

Results are automatically saved to t/.results/YYYYMMDD-HHMMSS.txt. The most recent results are also symlinked as t/.results/LATEST.txt.

Compare against the previous run:

t/TEST --compare --skip=bytecode,tier,debug

Check current pass/fail status without re-running:

grep "FAIL" t/.results/LATEST.txt
grep "05-op" t/.results/LATEST.txt

This is significantly faster than re-running tests and should be preferred when checking status.

Bail-Out Behavior

If any test in 00-base/ fails, the harness stops by default (bail-out). This gate ensures fundamental functionality works before running the larger suite. Override with --no-bail.

Multiple developers (or Claude instances) may share the same machine. Running the full test suite without coordination risks interference. Always use targeted filters during development. Full-suite runs (t/TEST --skip=bytecode,tier,debug) should be coordinated.

PetaPerl Documentation