Slay::Makefile::Gress(3p)

NAME
Slay::Makefile::Gress - Use Slay::Makefile for software regression testing

DESCRIPTION
This module provides support for running a set of regression tests from a .t file by doing builds with a "Slay::Makefile" file.

USAGE
To use this module, the .t file calling it should contain something like:

  use Slay::Makefile::Gress qw(do_tests);
  do_tests("SlayMakefile", @ARGV);

OVERVIEW
The basic functionality of this module is to take an initialization subdirectory (by default ending ".init") and copy it over to a run directory (by default ending ".dir"), doing a "chdir" into the run directory, and then parsing a "Slay::Makefile" to define and run the tests. A reasonable way to accomplish this is to have the "Slay::Makefile" create a file with extension ".ok" that is empty if the test passes; frequently this file can be the output of a diff between the test's output and an expect file. The "Slay::Makefile" can be in a parent directory so it can be shared by more than one suite of tests (.t file). A shared "Slay::Makefile" can use the include mechanism to bring in a local "Slay::Makefile" files in the run directory. You can even use this methodology for developing families of suites of tests, etc.

ROUTINES

"do_tests($makefile[, @tests] [, \%options ])"
    Runs a series of tests using $makefile as the "Slay::Makefile" input. If @tests are specified, it contains the list of tests, each of which is a target that is built in order; otherwise the dependencies of the "test" target will be built as the list of tests. The following options are recognized:

    init
        The extension for the initialization directory. Default is '.init'.

    opts
        A hash reference to be passed to Slay::Makefile::new as its options list.

    pretest
        The name of the target to be built prior to running tests to set everything up. Default is 'pretest'.

    run The extension for the run directory. Default is '.run'.

    skip
        The name for perl scripts to run to check whether all tests should be skipped. The name is also used as an extension for a test's base name to see if an individual tests should be skipped.

    test
        The name of the target whose dependencies gives the list of tests. Default is 'test'.

PROCESSING
Processing proceeds by the following steps:

1.  Search for an initialization directory with the same base name as the .t file invoking "do_tests" and extension equal to the "init" option. Croaks if there is no such directory. For example, if the file invoking c<do_tests> is "cmdline.t" and the default initialization extension is used, it looks for directory "cmdline.init".

2.  Copy the initialization directory to a run directory and "cd" into that directory.

3.  Check for a script with the name of the "skip" option. If it exists, execute it. If it returns a non-zero exit code, skip all the tests. The text this script prints becomes the reason for skipping the tests.

4.  Use "Slay::Makefile" to parse the $makefile file. Note that the working directory is the run directory when this file is processed.

5.  Do a "Slay::Makefile::make" of the "pretest" target, if it exists. The name of the "pretest" target is 'pretest' unless specified in the options.

6.  If @tests is empty, create a list of tests to execute by getting the dependencies of the "test" target. The name of the "test" target is 'test' unless specified in the options.

7.  For each test "t",

    a.  Check for a script with the same base name as "t" and the extension "." and the name of the "skip" option.. For example, if the default value of the "skip" option is used, then a test "algebra.ok" would use a script called "algebra.skip.pl". If the script exists, execute it and skip the test if it returns a non-zero exit code. The text this script prints becomes the reason for skipping the test.

    b.  Run "Slay::Makefile::make" for target "t".

    c.  If no file "t" was generated, report a failed test as failing to build the file. If "t" was generated, then it should be empty for a passing test. Any text in the file is returned as the reason for the tests's failure.