NAME

Test::Podlators - Helper functions for podlators tests

SYNOPSIS

use Test::Podlators qw(read_test_data);

# Read the next block of test data, including options.
my $data = read_test_data(\*DATA, { options => 1 });

DESCRIPTION

This module collects various utility functions that are useful for writing test cases for the podlators distribution. It is not intended to be, and probably isn't, useful outside of the test suite for that module.

FUNCTIONS

None of these functions are imported by default. The ones used by a script should be explicitly imported.

read_snippet(PATH)

Read one test snippet from the provided relative file name and return it. The path should be relative to t/data/snippets. For the format, see t/data/snippets/README.

The result will be a hash with the following keys:

name

The name of the test, for reporting purposes.

options

A hash of any options to values, if any options were specified.

input

Input POD to try formatting.

output

The expected output.

errors

Expected errors from the POD formatter.

exception

An expected exception from the POD formatter, with the file and line information stripped from the end of the exception.

read_test_data(FH, FORMAT)

Reads a block of test data from FH, looking for test information according to the description provided in FORMAT. All data prior to the first line consisting of only ### will be ignored. Then, the test data must consist of two or more blocks separated by ### and ending in a final ### line.

FORMAT is optional, in which case the block of test data should be just input text and output text. If provided, it should be a reference to a hash with one or more of the following keys:

options

If set, the first block of data in the test description is a set of options in the form of a key, whitespace, and a value, one per line. The value may be missing, in which case the value associated with the key is the empty string.

The return value is a hash with at least some of the following keys:

input

The input data for the test. This is always present.

options

If options is set in the FORMAT argument, this is the hash of keys and values in the options section of the test data.

output

The output data for the test. This is always present.

slurp(FILE[, STRIP])

Read the contents of FILE and return it as a string. If STRIP is set to man, strip off any Pod::Man header from the file before returning it.

test_snippet(CLASS, SNIPPET[, OPTIONS])

Test a formatter on a particular POD snippet. This does all the work of loading the snippet, creating the formatter by instantiating CLASS, running it, and checking the results. Results are reported with Test::More.

OPTIONS, if present, is a reference to a hash of options. Currently, only one key is supported: encoding, which, if set, specifies the encoding of the output portion of the snippet.

test_snippet_with_io(CLASS, SNIPPET[, OPTIONS])

The same as test_snippet(), except, rather than parsing the input into a string buffer, this function uses real, temporary input and output files. This can be used to test I/O layer handling and proper encoding. It also does additional tests for the preamble to the *roff output.

OPTIONS, if present, is a reference to a hash of options chosen from the following:

encoding

The encoding to expect from the snippet file. Default if not specified is UTF-8.

output

The encoding to expect from the output. Default if not specified is UTF-8.

perlio_iso

If set to true, set a PerlIO ISO-8859-1 encoding layer on the output file before writing to it.

perlio_utf8

If set to true, set a PerlIO UTF-8 encoding layer on the output file before writing to it.

AUTHOR

Russ Allbery <rra@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2015-2016, 2018-2020, 2022, 2024 Russ Allbery <rra@cpan.org>

This program is free software; you may redistribute it and/or modify it under the same terms as Perl itself.