| Subject: | automate testing of sample code |
| Date: | Wed, 23 Jan 2019 15:23:31 +1100 |
| To: | bug-Imager [...] rt.cpan.org |
| From: | Tony Cook <tony [...] develop-help.com> |
The documentation contains a lot of sample code.
To prevent typos causing users to get frustrated downstream, this code
should be tested if possible.
Ideally we'd test both the syntax and function, but testing just the
syntax is a good first step.
This would require two parts:
1) test files containing the test code with required infrastructure
and a little markup.
2) tests that check that every sample snippet is tested.
So for example this code from Imager::Files:
my $img = Imager->new;
$img->read(file=>$filename, type=>$type)
or die "Cannot read $filename: ", $img->errstr;
for syntax tests would end up in a test like:
my $filename = "testimg/penguin.ppm";
my $type = "pnm";
#begin snippet
my $img = Imager->new;
$img->read(file=>$filename, type=>$type)
or die "Cannot read $filename: ", $img->errstr;
#end snippet
for functional tests it might become:
sub f_readfile {
my ($filename, $type) = @_;
#begin snippet
my $img = Imager->new;
$img->read(file=>$filename, type=>$type)
or die "Cannot read $filename: ", $img->errstr;
#end snippet
$img
}
my $im;
ok(eval { $im = f_readfile("testimg/penguin.ppm", "pnm"); 1 },
"test successful read");
ok($im, "got an image object");
# possible compare to the source file
ok(!eval { $im = f_readfile("testimg/penguin.ppm", "bmp") 1 },
"fail to read in wrong format");
my $msg = $@;
like($msg, /Cannot read/, "and got the thrown message");
Because the SYNOPSIS often throws a bunch of unrelated code together,
the checking mechanism might split that on blank lines (or all such
code blocks) or search for the blocks incrementally if the full block
of code isn't found.