= USAGE =

== Standard case ==

Put the following into the source section of debian/control:

    Testsuite: autopkgtest-pkg-perl

This will activate an implicit test control file in autopkgtest that
will run all "standard" tests in /usr/share/pkg-perl-autopkgtest/*.d/*.
An explicit 'debian/tests/control' file does not need to be provided.

== Custom cases ==

In case you want other tests, or need other dependencies or
restrictions, you can add an explicit test control file
and list them according the the spec manually. You can use
/usr/share/doc/pkg-perl-autopkgtest/examples/default-tests-control as
a starting point.

== Skipping tests ==

If one of the standard tests has an expected failure, you can tell the
test runner to ignore it by listing it in 'debian/tests/pkg-perl/SKIP'.
The file can contain empty lines and comment lines starting with the '#' sign.

== Configuration ==

If your test suite needs files other than the contents of directory 't/' for
running prove, then you should list all files or directories to be copied to
the test running directory in the file 'debian/tests/pkg-perl/smoke-files'.
Empty lines and #-style comment lines are supported.

If there are just a few test files in the main test suite that
fail the smoke test, you can ignore those by adding them to
'debian/tests/pkg-perl/smoke-skip', one per line. Empty lines and
#-style comments are supported. Note that various normally useless tests
(including syntax checks, perlcritic, author and POD tests along with
some more specific ones like t/boilerplate.t and $TDIR/t/97_meta.t)
are skipped automatically unless you provide a skip list.

If the runtime-deps.d/use.t test fails to get the main module of your
package right, you can customize that by putting the right name in
'debian/tests/pkg-perl/use-name'.

If a module intentionally produces output when used, you can whitelist
that output as a regexp in 'debian/tests/pkg-perl/use-whitelist'.

If there are just a few modules that fail syntax.t, you can ignore those
by adding them to 'debian/tests/pkg-perl/syntax-skip'. The lines are
matched as fixed substrings (not regular expressions.) Empty lines and
#-style comments are supported.

If a package has a Suggests in debian/control, the actual syntax check
in syntax.t is skipped on the assumption that some prerequisites
will be missing for some modules, unless 'debian/tests/pkg-perl/syntax-skip'
exists (which can be empty or only contain comments to check all files).

If there are additional files besides those matching '/\.pm$/'
that you'd like to check, you can specify a list of those in
'debian/tests/pkg-perl/syntax-extra'. The lines are matched as regular
expressions; don't include the match delimiters (//).  Empty lines and
#-style comments are supported.

The environment variables AUTOMATED_TESTING=1 and NONINTERACTIVE_TESTING=1
are set by default for the smoke test. You can override these and add
others in 'debian/tests/pkg-perl/smoke-env'.

You can use 'debian/tests/pkg-perl/smoke-tests' to declare which files should
be used instead of all *.t files under t/. (Prior to version 0.37 only
the tests in the first directory level under t/ were used, but nowadays
prove is invoked with the --recurse option.)

If the file 'debian/tests/pkg-perl/smoke-setup' exists and is executable,
it will be executed right before running the tests, with the working
directory set to the package source and $TDIR set to the test running
directory. The testing gets aborted if this program returns a nonzero
value. Please use this facility responsibly and only as a last resort
if the other hooks don't work for you.

If the file 'debian/tests/pkg-perl/smoke-cleanup' exists and is executable, it 
will be executed when the smoke tests exit, with the working directory set to 
the package source and $TDIR set to the test running directory.
