perl-testing

intent

use test2::v0, test::more, and the prove test runner to build fast, maintainable perl test suites. follow red-green-refactor tdd workflow: write a failing test first, implement minimal code to pass it, then refactor while keeping tests green. this skill covers unit testing, integration testing, mocking external dependencies, measuring coverage with devel::cover, and organizing test files for ci/cd pipelines. activate this when starting a new perl module, building a test suite, migrating from test::more to test2::v0, debugging test failures, or reviewing coverage gaps.

inputs

• perl version: v5.36 or later (signed subroutine signatures, modern syntax)
• cpan modules: test2::v0 (core modern framework), test::more (standard assertions, ships with perl), test::mockedule (method mocking), test::mockobject (lightweight test doubles), devel::cover (coverage analysis)
• file system access: write access to t/ directory for test files, fixtures/ for test data, lib/ for modules under test
• environment variables (optional):
  • TEST_DB: set to enable database integration tests (default: skip)
  • PROVE_RC: path to .proverc config file (default: ~/.proverc or ./.proverc)
  • COVERAGE_THRESHOLD: minimum coverage % to enforce (default: 80)
• external commands: prove (test runner, ships with perl), cover (devel::cover report generator), perl (with -MDevel::Cover flag for instrumentation)
• optional ci integration: TAP (test anything protocol) formatters, JUnit XML output for jenkins/gitlab/github actions

procedure

step 1: set up tdd project structure

inputs: empty or existing perl project

outputs: t/, t/lib/, t/fixtures/ directories with placeholder files

1. create directory layout:

   • t/00-load.t (verify modules compile)
   • t/01-basic.t (core smoke tests)
   • t/unit/ (unit tests by module: config.t, user.t, util.t)
   • t/integration/ (integration tests: database.t, api.t)
   • t/lib/TestHelper.pm (shared test utilities and fixtures)
   • t/fixtures/ (test data: config.json, users.csv, etc.)
   • lib/ (production code)

2. create .proverc in project root with sensible defaults:

   -l
   --color
   --timer
   -r
   -j4
   --state=save
   

3. verify prove finds tests: run prove -l --dry-run t/

step 2: write red test (tdd phase 1)

inputs: feature requirement, module name (e.g., Calculator)

outputs: t/unit/calculator.t with failing assertions

1. open t/unit/calculator.t
2. add test skeleton with test2::v0:

   use v5.36;
   use Test2::V0;
   use lib 'lib';
   use Calculator;
   
   subtest 'addition' => sub {
       my $calc = Calculator->new;
       is($calc->add(2, 3), 5, 'adds two numbers');
       is($calc->add(-1, 1), 0, 'handles negatives');
   };
   
   done_testing;
   

3. run test: prove -lv t/unit/calculator.t
4. confirm it fails (module not found or assertion fails)

step 3: write green implementation (tdd phase 2)

inputs: failing test file, requirement spec

outputs: lib/Calculator.pm with minimal passing code

1. create lib/Calculator.pm with stub implementation:

   package Calculator;
   use v5.36;
   use Moo;
   
   sub add($self, $a, $b) {
       return $a + $b;
   }
   
   1;
   

2. run test: prove -lv t/unit/calculator.t
3. confirm it passes (all assertions green)

step 4: refactor (tdd phase 3)

inputs: passing test, code review checklist (naming, duplication, edge cases)

outputs: improved implementation, all tests still pass

1. identify code smells: long methods, magic numbers, duplicated logic, missing validation
2. refactor incrementally (change one thing per run)
3. run tests after each change: prove -lv t/unit/calculator.t
4. confirm tests still pass (if they break, revert and refactor differently)
5. run full suite to ensure no regressions: prove -l t/

step 5: add test assertions (test2::v0 builders)

inputs: test file, data structure to verify

outputs: enriched assertions with hash/array/bag builders

1. for object hashes, use hash builder with partial field matching:

   is(
       $user->to_hash,
       hash {
           field name  => 'Alice';
           field email => match(qr/\@example\.com$/);
           field age   => validator(sub { $_ >= 18 });
           etc();  # ignore other fields
       },
       'user has expected fields'
   );
   

2. for lists, use array builder:

   is(
       $result,
       array {
           item 'first';
           item match(qr/^second/);
           item DNE();  # does not exist, verify no extra items
       },
       'result matches expected list'
   );
   

3. for unordered collections, use bag builder:

   is(
       $tags,
       bag {
           item 'perl';
           item 'testing';
           item 'tdd';
       },
       'has all required tags regardless of order'
   );
   

4. for exceptions, use dies/lives:

   like(dies { divide(10, 0) }, qr/Division by zero/, 'dies on zero denominator');
   ok(lives { divide(10, 2) }, 'division succeeds');
   

step 6: organize tests with subtests

inputs: test file with multiple related assertions

outputs: grouped assertions in subtest blocks with isolated state

1. wrap related assertions in subtest:

   subtest 'User creation' => sub {
       my $user = User->new(name => 'Alice', email => 'alice@example.com');
       ok($user, 'user object created');
       is($user->name, 'Alice', 'name is set');
       is($user->email, 'alice@example.com', 'email is set');
   };
   

2. declare setup/teardown variables with my inside subtest to prevent state leakage:

   subtest 'file processing' => sub {
       my $dir = tempdir(CLEANUP => 1);
       my $file = path($dir, 'input.txt');
       $file->spew_utf8("line1\nline2\nline3\n");
       
       my $result = process_file("$file");
       is($result->{line_count}, 3, 'counts lines');
   };
   

3. ensure each subtest is independent: changes in one subtest must not affect another

step 7: mock external dependencies

inputs: test file with external API calls or database access

outputs: mocked methods that return controlled test data

1. use test::mockmodule to mock classes:

   my $mock = Test::MockModule->new('MyApp::API');
   $mock->mock(fetch_user => sub ($self, $id) {
       return { id => $id, name => 'Mock User', email => 'mock@test.com' };
   });
   
   my $api = MyApp::API->new;
   my $user = $api->fetch_user(42);
   is($user->{name}, 'Mock User', 'returns mocked user');
   

2. for method call verification, track call count inside the mock:

   my $call_count = 0;
   $mock->mock(fetch_user => sub { $call_count++; return {} });
   $api->fetch_user(1);
   $api->fetch_user(2);
   is($call_count, 2, 'fetch_user called twice');
   

3. mock scope is automatic: restore happens when $mock goes out of scope (no manual cleanup needed)

4. use test::mockobject for lightweight test doubles:

   my $user_double = Test::MockObject->new;
   $user_double->mock('is_active', sub { 1 });
   

5. never monkey-patch with *Package::method = sub { ... } outside of test::mockmodule: it leaks across tests

step 8: handle database integration tests

inputs: test file, database schema

outputs: in-memory sqlite database populated with test data

1. use in-memory sqlite for fast isolation:

   subtest 'database integration' => sub {
       my $dbh = DBI->connect('dbi:SQLite:dbname=:memory:', '', '', {
           RaiseError => 1,
       });
       $dbh->do('CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)');
       
       $dbh->prepare('INSERT INTO users (name) VALUES (?)')->execute('Alice');
       my $row = $dbh->selectrow_hashref('SELECT * FROM users WHERE name = ?', undef, 'Alice');
       is($row->{name}, 'Alice', 'inserted and retrieved user');
   };
   

2. wrap database setup in subtest with my variables to auto-cleanup on scope exit

3. for external database tests (TEST_DB env var), use dedicated test database, never production

step 9: skip and todo tests

inputs: test file, skip/todo conditions

outputs: conditionally skipped or marked-failing tests

1. skip tests conditionally based on environment:

   SKIP: {
       skip 'No database configured', 2 unless $ENV{TEST_DB};
       
       my $db = connect_db();
       ok($db->ping, 'database is reachable');
       is($db->version, '15', 'correct PostgreSQL version');
   }
   

2. mark expected failures (features not yet implemented):

   TODO: {
       local $TODO = 'Caching not yet implemented';
       is($cache->get('key'), 'value', 'cache returns value');
   }
   

3. always provide the skip count (2 in example above): ensures prove knows how many tests to expect

step 10: run tests with prove

inputs: t/ directory with .t test files

outputs: pass/fail report with timing and diagnostics

1. run all tests: prove -l t/
2. run verbose with color: prove -lv t/
3. run specific test file: prove -lv t/unit/user.t
4. run in parallel (8 jobs): prove -lr -j8 t/
5. run only tests that failed last time: prove -l --state=failed t/
6. run with timer to find slow tests: prove -l --timer t/
7. generate tap output for ci (jenkins, gitlab): prove -l --formatter TAP::Formatter::JUnit t/ > results.xml

step 11: measure coverage with devel::cover

inputs: test suite, lib/ directory

outputs: coverage report (text, html, or json)

1. run coverage instrumentation:

   cover -test
   

   (this runs all tests via prove under devel::cover instrumentation)

2. or step by step:

   perl -MDevel::Cover -Ilib t/unit/user.t
   cover
   

3. generate html report:

   cover -report html
   open cover_db/coverage.html
   

4. view text summary:

   cover -report text
   

5. check coverage threshold in ci:

   cover -test -report text -select '^lib/' \
     | perl -ne 'if (/Total.*?(\d+\.\d+)/) { exit 1 if $1 < 80 }'
   

6. clean up coverage data between runs: cover -delete

step 12: use shared test helpers

inputs: t/lib/TestHelper.pm

outputs: reusable fixtures and factory functions

1. create t/lib/TestHelper.pm with exporter:

   package TestHelper;
   use v5.36;
   use Exporter 'import';
   our @EXPORT = qw(create_test_db create_temp_dir fixture_path);
   
   sub create_test_db {
       my $dbh = DBI->connect('dbi:SQLite:dbname=:memory:', '', '', { RaiseError => 1 });
       # setup schema
       return $dbh;
   }
   
   sub create_temp_dir {
       return File::Temp::tempdir(CLEANUP => 1);
   }
   
   sub fixture_path {
       my ($name) = @_;
       return "t/fixtures/$name";
   }
   
   1;
   

2. in test files, use lib 't/lib' and import:

   use lib 't/lib';
   use TestHelper;
   
   my $db = create_test_db();
   

decision points

if using test::more (legacy codebase)

• migrate incrementally: write new tests in test2::v0, keep existing test::more tests running
• rewrite old tests when touching that code (refactoring opportunity)
• avoid mixing test2::v0 and test::more in the same file (import only one framework)

else (new project)

• start with test2::v0 exclusively: superior diagnostics, hash/array builders, modern api

if external api or network dependency exists

• mock with test::mockmodule: intercept method calls, return controlled data
• never make real http requests in unit tests: slow, flaky, fragile
• reserve integration tests for true external service calls (and mark with TODO or SKIP if service unavailable)

if database tests required

• use in-memory sqlite (fast, no setup): DBI->connect('dbi:SQLite:dbname=:memory:')
• if real database needed (integration test), check TEST_DB env var: skip unless explicitly enabled
• never use production database in tests

if test_db environment variable set

• run integration tests against real database
• else skip integration tests (SKIP block)

if devel::cover coverage < 80%

• identify untested code paths: review cover_db/coverage.html
• add test cases for missing branches (if/else, exceptions, edge cases)
• if coverage target cannot be reached due to external code: use cover -select to exclude those packages

if test failure in ci but passes locally

• check for state leakage: ensure subtests use my, not our
• check for timing issues: mock time-dependent functions, use in-memory databases
• check for environment assumptions: verify env vars match ci config
• run with prove -j1 to disable parallelization (isolate race conditions)

if test runs slowly

• identify slow tests: prove -l --timer t/ shows per-file timing
• replace real database with in-memory sqlite
• replace http calls with mocks
• run slow tests last: reorder t/01-basic.t before t/integration/api.t
• use prove -j4 to parallelize fast tests, disable -j for slow tests

output contract

test files must exist in t/ directory, named *.t:

• t/00-load.t: loads all modules without error, ends with done_testing
• t/unit/MODULE.t: unit tests for lib/Module.pm, all assertions pass, ends with done_testing
• t/integration/SERVICE.t: integration tests, may skip based on TEST_DB env var, ends with done_testing

prove output format (when run with -l t/):

• each test file shows pass/fail and execution time
• summary line shows total pass/fail counts and elapsed time
• exit code 0 on all pass, exit code 1+ on any failure

coverage report (when run with cover -test):

• cover_db/ directory created with instrumented data
• cover_db/coverage.html (html) or text output shows % coverage per file
• total coverage % summarized at bottom
• exit code 0 always (use text output to enforce threshold via perl script)

test names and diagnostics in tap output:

• each assertion generates "ok N - description" or "not ok N - description"
• failed assertions include "# Failed test 'description' at t/unit/file.t line N"
• subtest blocks show "# Subtest: Subtest Name" with indented results

shared test helpers (t/lib/TestHelper.pm):

• exports factory functions (create_test_db, create_temp_dir, fixture_path)
• no global state: each function call returns fresh instance
• cleanup happens automatically (my scope or CLEANUP => 1 flag)

outcome signal

you know perl-testing worked when:

1. test file runs without error: prove -lv t/unit/calculator.t outputs "ok 1 - adds two numbers", "ok 2 - handles negatives", "1..2 ok"

2. test fails first (red): before implementation, prove outputs "not ok 1 - adds two numbers" with diagnostic showing expected 5 got undef

3. test passes after implementation (green): after writing Calculator::add(), prove outputs "ok 1", "ok 2", "1..2 ok"

4. refactoring keeps tests green: after improving Calculator code, prove still outputs "1..2 ok"

5. coverage report generated: cover -test produces cover_db/ directory and cover -report text shows "Total 80.5%"

6. subtests isolate state: two subtests with conflicting setup (both