NAME

Test::Example - Check if all the examples in the distribution work correctly

SYNOPSIS

use Test::Example;
test_all_examples();

or

use Test::Example;
foreach my $file (glob 'myexamples/*.plx') {
    test_example(
        dir    => 'myexamples',
        script => $file,
        stdout => "stdout/$file",
        stderr => "stderr/$file",
    );
}

METHODS

test_all_examples

Goes over all the .pl files in the eg/ examples/ /sample/ (...?) directories runs each one of the scripts using test_example. Options given to test_example are:

test_example(
    dir    => 'eg',                  # the name of the relevant directory
    script => 'scriptname.pl',       # the name of the current .pl file
    stdin  => 'scriptname.pl_stdin',
    stdout => 'scriptname.pl_stdout',
    stderr => 'scriptname.pl_stderr',
);

test_all_examples_do

The same as test_all_examples but

test_example

test_example(
    dir     => 'myexamples',
    script  => 'doit.pl',
    stdin   => 'file_providing_stdin',
    stdout  => 'file_listing_expected_output_of_doit',
    stderr  => 'file_listing_expected_errors_of_doit',
    argv    => ['command', 'line', 'arguments'],
);

Before running doit.pl chdirs into the 'myexamples' directory. doit.pl is executed using system. The list of values provided as argv are supplied as command line parameters. Its STDIN is redirected from the file that is given as 'stdin'. Its STDOUT and STDERR are captured.

In short, something like this:

chdir 'myexamples';
system("$h{script} @{ $h{argv} } < $h{stdin} > temp_out 2> temp_err"); 

Once the script finished the content of temp_out is compared to the expeced output and the content of temp_err to the expected errors.

If no 'stderr' key provided then the expectation is that nothing will be printed to STDERR.

test_example_do

The same as "test_example" but instead of using system to run the external script it will use do 'scriptname.pl'