unit-test-wizard— agent skill

<instructions> You help an OSADO developer write and review unit tests for Perl library modules. Tests follow established patterns documented in references/ut_rules.md -- read it when you need the full pattern catalog.

Tools

Script paths are relative to this skill's installed directory.

• scripts/scaffold_test.pl -- Analyzes a .pm module and generates a

complete .t test file skeleton with proper imports, mocking, and subtests.

• scripts/review_test.pl -- Audits an existing .t file against the

best practices checklist and reports pass/fail per item.

Both scripts accept --repo, --json, --verbose, and --help.

Generate Mode

Use when the user asks to write tests for a library module.

1. Identify the module path. Ask if unclear. Must be relative to the

OSADO repo root (e.g., lib/mypackage/module.pm).

1. Run the scaffold script:

   perl scripts/scaffold_test.pl --repo /path/to/osado lib/mypackage/module.pm

This outputs a complete .t file to stdout. Use --output to write directly to a file, or --json to get structured module info.

1. Review and customize the output. The skeleton is a starting point:

• Verify the fake values are distinctive and traceable.
• Add conditional script_output mocks if the function branches on

command output.

• Add assertions specific to the function's behavior (not just argument

presence).

• Ensure optional args have their own subtests.

1. Write the file to t/NN_<module_name>.t (the script suggests the

next available number).

1. Run the test:

   prove -v -l -Ios-autoinst/ t/NN_<module_name>.t

Review Mode

Use when the user asks to review or audit an existing test file.

1. Run the review script:

   perl scripts/review_test.pl --repo /path/to/osado t/NN_foo.t

1. Present findings grouped as PASS/FAIL/WARN.
2. For each failure, explain what's wrong and propose the fix, citing

the relevant section from references/ut_rules.md.

1. Optionally re-run after applying fixes to confirm the check passes.

Key Patterns (quick reference)

File skeleton

use strict;
use warnings;
use Test::More;
use Test::Exception;
use Test::Warnings;
use Test::MockModule;
use Test::Mock::Time;
use List::Util qw(any none uniq all)

use mypackage::module_name;

subtest '[function_name]' => sub { ... };

done_testing;

The @calls capture pattern

subtest '[function_name]' => sub {
    my @calls;
    my $mock = Test::MockModule->new('mypackage::module_name', no_auto => 1);
    $mock->redefine(assert_script_run => sub { push @calls, $_[0]; return; });
    $mock->redefine(record_info => sub { note(join(' ', 'RECORD_INFO -->', @_)); });

    function_name(arg1 => 'Agamemnon', arg2 => 'Mycenaeans');

    note("\n  -->  " . join("\n  -->  ", @calls));
    ok((any { /expected_pattern/ } @calls), 'Descriptive assertion message');
};

Mandatory arg testing

subtest '[function_name] missing arguments' => sub {
    dies_ok { function_name(arg2 => 'X') } 'Die for missing argument arg1';
    dies_ok { function_name(arg1 => 'X') } 'Die for missing argument arg2';
};

Rules

• Always use no_auto => 1 in Test::MockModule constructors.
• Always use redefine(), never mock().
• Each subtest must be self-contained: own @calls, own mocks, no shared state.
• Always mock record_info (redirect to note).
• Clean up set_var with undef at end of subtests.
• Use distinctive fake values (mythology, Italian, mushrooms) -- never

"foo", "bar", "test".

• Test behavior (what commands are generated), not implementation (internal

call order).

• Assertion messages must be specific, unique, and informative on failure.
• Use regex matching (any { /pattern/ } @calls) not exact string equality

for command assertions.

• Do NOT modify the library code -- this skill only creates/edits test files.
• After generating tests, suggest running them via local-lint-test or

directly with prove. </instructions>