Test::RRA::Automake

(Automake-aware support functions for Perl tests)

SYNOPSIS

    use Test::RRA::Automake qw(automake_setup perl_dirs test_file_path);
    automake_setup({ chdir_build => 1 });

    # Paths to directories that may contain Perl scripts.
    my @dirs = perl_dirs({ skip => [qw(lib)] });

    # Configuration for Kerberos tests.
    my $keytab = test_file_path('config/keytab');

This module collects utility functions that are useful for test scripts written in Perl and included in a C Automake-based package. They assume the layout of a package that uses rra-c-util and C TAP Harness for the test structure.

Loading this module will also add the directories perl/blib/arch and perl/blib/lib to the Perl library search path, relative to C_TAP_BUILD if that environment variable is set. This is harmless for C Automake projects that don't contain an embedded Perl module, and for those projects that do, this will allow subsequent use calls to find modules that are built as part of the package build process.

The automake_setup() function should be called before calling any other functions provided by this module.

FUNCTIONS

None of these functions are imported by default. The ones used by a script should be explicitly imported. On failure, all of these functions call BAIL_OUT (from Test::More).

all_files()

Returns a list of all "interesting" files in the distribution that a test suite may want to look at. This excludes various products of the build system, the build directory if it's under the source directory, and a few other uninteresting directories like .git. The returned paths will be paths relative to the root of the package.

automake_setup([ARGS])

Verifies that the C_TAP_BUILD and C_TAP_SOURCE environment variables are set and then changes directory to the top of the source tree (which is one directory up from the C_TAP_SOURCE path, since C_TAP_SOURCE points to the top of the tests directory).

If ARGS is given, it should be a reference to a hash of configuration options. Only one option is supported: chdir_build. If it is set to a true value, automake_setup() changes directories to the top of the build tree instead.

perl_dirs([ARGS])

Returns a list of directories that may contain Perl scripts that should be tested by test scripts that test all Perl in the source tree (such as syntax or coding style checks). The paths will be simple directory names relative to the current directory or two-part directory names under the tests directory. (Directories under tests are broken out separately since it's common to want to apply different policies to different subdirectories of tests.)

If ARGS is given, it should be a reference to a hash of configuration options. Only one option is supported: skip, whose value should be a reference to an array of additional top-level directories or directories starting with tests/ that should be skipped.

test_file_path(FILE)

Given FILE, which should be a relative path, locates that file relative to the test directory in either the source or build tree. FILE will be checked for relative to the environment variable C_TAP_BUILD first, and then relative to C_TAP_SOURCE. test_file_path() returns the full path to FILE or calls BAIL_OUT if FILE could not be found.

test_tmpdir()

Create a temporary directory for tests to use for transient files and return the path to that directory. The directory is created relative to the C_TAP_BUILD environment variable, which must be set. Permissions on the directory are set using the current umask. test_tmpdir() returns the full path to the temporary directory or calls BAIL_OUT if it could not be created.

The directory is automatically removed if possible on program exit. Failure to remove the directory on exit is reported with diag() and otherwise ignored.

ENVIRONMENT

C_TAP_BUILD: The root of the tests directory in Automake build directory for this package, used to find files as documented above.
C_TAP_SOURCE: The root of the tests directory in the source tree for this package, used to find files as documented above.

AUTHOR

Russ Allbery <eagle@eyrie.org>

COPYRIGHT AND LICENSE

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.