NAME

pod-example-tester - Generate round-trip tests from POD code examples

SYNOPSIS

pod-example-tester [options] <module.pm>

Options:
  --output FILE   Write test file to FILE (default: t/pod_examples.t)
  --no-annotated  Skip annotated single-line examples; only use verbatim blocks
  --help          Show this help message
  --man           Show full documentation

Examples:
  pod-example-tester lib/My/Module.pm
  pod-example-tester --output t/synopsis.t lib/My/Module.pm

DESCRIPTION

Reads a Perl module, extracts code examples from its POD (from =head1 SYNOPSIS, =head2 SYNOPSIS, =for example begin/=for example end blocks, and annotated inline examples), and generates a Test::Most-based .t file that runs every example as a subtest.

Each subtest:

• Wraps the example code in eval { ... }

• Asserts the example does not die

• If the example has a # returns value or # => value annotation, additionally asserts the return value with is()

Running this test suite after any code change ensures that all documented examples still work — the "round-trip" between documentation and code.

ANNOTATION FORMAT

Append # = value> or # returns value to any indented line in the POD to document the expected return value:

my $status = $obj->validate_score(75.5);  # returns 'Pass'
my $x      = add(2, 3);                   # => 5

The generated test will assert is($result, 'Pass', ...) etc.

EXAMPLES

Generate tests for a single module

pod-example-tester lib/My/Module.pm

Custom output path

pod-example-tester --output t/my_pod_roundtrip.t lib/My/Module.pm

Verbatim blocks only (skip annotated single-liners)

pod-example-tester --no-annotated lib/My/Module.pm

SEE ALSO

App::Test::Generator::PodExampleExtractor, App::Test::Generator

AUTHOR

Nigel Horne