Skip to main content
Agent skill

Perl Testing

Perl testing patterns using Test2::V0, Test::More, prove runner, mocking, coverage with Devel::Cover, and TDD methodology. Use when writing Perl tests with Test2::V0 or Test::More, or measuring coverage.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Perl Testing when an AI agent needs a reusable SKILL.md workflow for this job: Perl testing patterns using Test2::V0, Test::More, prove runner, mocking, coverage with Devel::Cover, and TDD methodology. Use when writing Perl tests with Test2::V0 or Test::More, or measuring coverage.

When not to use it

Skip Perl Testing when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/perl-testing
# Save SKILL.md to ~/.claude/skills/perl-testing/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/perl-testing/SKILL.md. For a shared project, commit the folder at .claude/skills/perl-testing/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Perl Testing skill for this task: Use Perl Testing when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

71/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
77/100
Practical detail
68/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Perl Testing Patterns

Comprehensive testing strategies for Perl applications using Test2::V0, Test::More, prove, and TDD methodology.

## When to Activate

- Writing new Perl code (follow TDD: red, green, refactor) - Designing test suites for Perl modules or applications - Reviewing Perl test coverage - Setting up Perl testing infrastructure - Migrating tests from Test::More to Test2::V0 - Debugging failing Perl tests

## TDD Workflow

Always follow the RED-GREEN-REFACTOR cycle.

```perl # Step 1: RED — Write a failing test # t/unit/calculator.t 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;

# Step 2: GREEN — Write minimal implementation # lib/Calculator.pm package Calculator; use v5.36; use Moo;

sub add($self, $a, $b) { return $a + $b; }

1;

# Step 3: REFACTOR — Improve while tests stay green # Run: prove -lv t/unit/calculator.t ```

## Test::More Fundamentals

The standard Perl testing module — widely used, ships with core.

### Basic Assertions

```perl use v5.36; use Test::More;

# Plan upfront or use done_testing # plan tests => 5; # Fixed plan (optional)

# Equality is($result, 42, 'returns correct value'); isnt($result, 0, 'not zero');

# Boolean ok($user->is_active, 'user is active'); ok(!$user->is_banned, 'user is not banned');

# Deep comparison is_deeply( $got, { name => 'Alice', roles => ['admin'] }, 'returns expected structure' );

# Pattern matching like($error, qr/not found/i, 'error mentions not found'); unlike($output, qr/password/, 'output hides password');

# Type check isa_ok($obj, 'MyApp::User'); can_ok($obj, 'save', 'delete');

done_testing; ```

### SKIP and TODO

```perl use v5.36; use Test::More;

# Skip tests conditionally 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'); }

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

done_testing; ```

## Test2::V0 Modern Framework

Test2::V0 is the modern replacement for Test::More — richer assertions, better diagnostics, and extensible.

### Why Test2?

- Superior deep comparison with hash/array builders - Better diagnostic output on failures - Subtests with cleaner scoping - Extensible via Test2::Tools::* plugins - Backward-compatible with Test::More tests

### Deep Comparison with Builders

```perl use v5.36; use Test2::V0;

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

# Array builder is( $result, array { item 'first'; item match(qr/^second/); item DNE(); # Does Not Exist — verify no extra items }, 'result matches expected list' );

# Bag — order-independent comparison is( $tags, bag { item 'perl'; item 'testing'; item 'tdd'; }, 'has all required tags regardless of order' ); ```

### Subtests

```perl use v5.36; use Test2::V0;

subtest 'User creation' => sub { my $user = User->new(name => 'Alice', email => '[email protected]'); ok($user, 'user object created'); is($user->name, 'Alice', 'name is set'); is($user->email, '[email protected]', 'email is set'); };

subtest 'User validation' => sub { my $warnings = warns { User->new(name => '', email => 'bad'); }; ok($warnings, 'warns on invalid data'); };

done_testing; ```

### Exception Testing with Test2

```perl use v5.36; use Test2::V0;

# Test that code dies like( dies { divide(10, 0) }, qr/Division by zero/, 'dies on division by zero' );

# Test that code lives ok(lives { divide(10, 2) }, 'division succeeds') or note($@);

# Combined pattern subtest 'error handling' => sub { ok(lives { parse_config('valid.json') }, 'valid config parses'); like( dies { parse_config('missing.json') }, qr/Cannot open/, 'missing file dies with message' ); };

done_testing; ```

## Test Organization and prove

### Directory Structure

```text t/ ├── 00-load.t # Verify modules compile ├── 01-basic.t # Core functionality ├── unit/ │ ├── config.t # Unit tests by module │ ├── user.t │ └── util.t ├── integration/ │ ├── database.t │ └── api.t ├── lib/ │ └── TestHelper.pm # Shared test utilities └── fixtures/ ├── config.json # Test data files └── users.csv ```

### prove Commands

```bash # Run all tests prove -l t/

# Verbose output prove -lv t/

# Run specific test prove -lv t/unit/user.t

# Recursive search prove -lr t/

# Parallel execution (8 jobs) prove -lr -j8 t/

# Run only failing tests from last run prove -l --state=failed t/

# Colored output with timer prove -l --color --timer t/

# TAP output for CI prove -l --formatter TAP::Formatter::JUnit t/ > results.xml ```

### .proverc Configuration

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

## Fixtures and Setup/Teardown

### Subtest Isolation

```perl use v5.36; use Test2::V0; use File::Temp qw(tempdir); use Path::Tiny;

subtest 'file processing' => sub { # Setup my $dir = tempdir(CLEANUP => 1); my $file = path($dir, 'input.txt'); $file->spew_utf8("line1\nline2\nline3\n");

# Test my $result = process_file("$file"); is($result->{line_count}, 3, 'counts lines');

# Teardown happens automatically (CLEANUP => 1) }; ```

### Shared Test Helpers

Place reusable helpers in `t/lib/TestHelper.pm` and load with `use lib 't/lib'`. Export factory functions like `create_test_db()`, `create_temp_dir()`, and `fixture_path()` via `Exporter`.

## Mocking

### Test::MockModule

```perl use v5.36; use Test2::V0; use Test::MockModule;

subtest 'mock external API' => sub { my $mock = Test::MockModule->new('MyApp::API');

# Good: Mock returns controlled data $mock->mock(fetch_user => sub ($self, $id) { return { id => $id, name => 'Mock User', email => '[email protected]' }; });

my $api = MyApp::API->new; my $user = $api->fetch_user(42); is($user->{name}, 'Mock User', 'returns mocked user');

# Verify call count 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');

# Mock is automatically restored when $mock goes out of scope };

# Bad: Monkey-patching without restoration # *MyApp::API::fetch_user = sub { ... }; # NEVER — leaks across tests ```

For lightweight mock objects, use `Test::MockObject` to create injectable test doubles with `->mock()` and verify calls with `->called_ok()`.

## Coverage with Devel::Cover

### Running Coverage

```bash # Basic coverage report cover -test

# Or step by step perl -MDevel::Cover -Ilib t/unit/user.t cover

# HTML report cover -report html open cover_db/coverage.html

# Specific thresholds cover -test -report text | grep 'Total'

# CI-friendly: fail under threshold cover -test && cover -report text -select '^lib/' \ | perl -ne 'if (/Total.*?(\d+\.\d+)/) { exit 1 if $1 < 80 }' ```

### Integration Testing

Use in-memory SQLite for database tests, mock HTTP::Tiny for API tests.

```perl use v5.36; use Test2::V0; use DBI;

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'); };

done_testing; ```

## Best Practices

### DO

- **Follow TDD**: Write tests before implementation (red-green-refactor) - **Use Test2::V0**: Modern assertions, better diagnostics - **Use subtests**: Group related assertions, isolate state - **Mock external dependencies**: Network, database, file system - **Use `prove -l`**: Always include lib/ in `@INC` - **Name tests clearly**: `'user login with invalid password fails'` - **Test edge cases**: Empty strings, undef, zero, boundary values - **Aim for 80%+ coverage**: Focus on business logic paths - **Keep tests fast**: Mock I/O, use in-memory databases

### DON'T

- **Don't test implementation**: Test behavior and output, not internals - **Don't share state between subtests**: Each subtest should be independent - **Don't skip `done_testing`**: Ensures all planned tests ran - **Don't over-mock**: Mock boundaries only, not the code under test - **Don't use `Test::More` for new projects**: Prefer Test2::V0 - **Don't ignore test failures**: All tests must pass before merge - **Don't test CPAN modules**: Trust libraries to work correctly - **Don't write brittle tests**: Avoid over-specific string matching

## Quick Reference

| Task | Command / Pattern | |---|---| | Run all tests | `prove -lr t/` | | Run one test verbose | `prove -lv t/unit/user.t` | | Parallel test run | `prove -lr -j8 t/` | | Coverage report | `cover -test && cover -report html` | | Test equality | `is($got, $expected, 'label')` | | Deep comparison | `is($got, hash { field k => 'v'; etc() }, 'label')` | | Test exception | `like(dies { ... }, qr/msg/, 'label')` | | Test no exception | `ok(lives { ... }, 'label')` | | Mock a method | `Test::MockModule->new('Pkg')->mock(m => sub { ... })` | | Skip tests | `SKIP: { skip 'reason', $count unless $cond; ... }` | | TODO tests | `TODO: { local $TODO = 'reason'; ... }` |

## Common Pitfalls

### Forgetting `done_testing`

```perl # Bad: Test file runs but doesn't verify all tests executed use Test2::V0; is(1, 1, 'works'); # Missing done_testing — silent bugs if test code is skipped

# Good: Always end with done_testing use Test2::V0; is(1, 1, 'works'); done_testing; ```

### Missing `-l` Flag

```bash # Bad: Modules in lib/ not found prove t/unit/user.t # Can't locate MyApp/User.pm in @INC

# Good: Include lib/ in @INC prove -l t/unit/user.t ```

### Over-Mocking

Mock the *dependency*, not the code under test. If your test only verifies that a mock returns what you told it to, it tests nothing.

### Test Pollution

Use `my` variables inside subtests — never `our` — to prevent state leaking between tests.

**Remember**: Tests are your safety net. Keep them fast, focused, and independent. Use Test2::V0 for new projects, prove for running, and Devel::Cover for accountability.

Intended uses

  • Use Perl Testing when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.