Writing Tests

Format: Raw TAP

Tests use raw TAP (Test Anything Protocol). No test framework, no shared library. Each .t file is a self-contained Perl script that produces TAP on stdout.

#!/usr/bin/perl
# Description of what this tests
print "1..3\n";
my $t = 1;
sub ok { my ($c,$n) = @_; print $c ? "ok $t - $n\n" : "not ok $t - $n\n"; $t++; }

ok(1 + 1 == 2, "addition");
ok("a" eq "a", "string eq");
ok(defined 0, "zero is defined");

The plan line (1..N) must be the first line of output and declares how many tests to expect.

Diagnostics

Lines starting with # are diagnostics. The harness ignores them, but they appear in verbose mode:

print "# debug: x=$x\n";

Test Helper Pattern

Most test files define a local ok sub. Keep it minimal:

my $t = 1;
sub ok { my ($c,$n) = @_; print $c ? "ok $t - $n\n" : "not ok $t - $n\n"; $t++; }

For tests that need is (value comparison with diagnostic on failure):

sub is {
    my ($got, $expected, $name) = @_;
    if ($got eq $expected) {
        print "ok $t - $name\n";
    } else {
        print "not ok $t - $name\n";
        print "# got:      '$got'\n";
        print "# expected: '$expected'\n";
    }
    $t++;
}

Per-Test Configuration

pperl CLI Flags

Override default harness flags via comment header:

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

This removes --no-jit, enabling JIT for the test. Other examples:

# pperl-cli: -(--no-parallel)           # enable parallelization
# pperl-cli: --timeout=60               # longer timeout
# pperl-cli: -(--no-jit) --timeout=120  # JIT + long timeout

Timeout

The default per-test timeout is 5 seconds. For slow tests:

# pperl-cli: --timeout=30

File Naming

• Files end in .t
• Numbered prefix: NNN-name.t (005, 010, 015, … — gaps for insertion)
• Perl5 ports use -perl5.t suffix: 010-array-perl5.t

Placement

Place tests in the appropriate numbered directory based on category. See Test Structure for the directory layout.

New tests for bug regressions during development go in 99-debug/ initially. Once the bug is fixed and tests pass, move them to the appropriate category directory.

What Makes a Test Pass

The harness runs each .t file under both perl (system perl5) and pperl. A test passes when pperl produces identical output to perl5. This means:

• The TAP output (ok/not ok lines) must match
• Diagnostic output must match
• Warnings on stderr are compared separately
• Exit codes are compared

This is a conformance test: it verifies pperl behaves like perl5, not that a particular result is correct in isolation.