NAME

Mnet::Test - Record, replay, and test script inputs and outputs

SYNOPSIS

    use Mnet::Test;
    use Mnet::Opts::Cli;
    my $cli = Mnet::Opts::Cli->new;

DESCRIPTION

Mnet::Test can be used to allow script inputs and output to be recorded to a file, which can be replayed later to test that the outputs are still the same.

Other Mnet modules are designed to detect and make use of Mnet::Test, if it is being used by the current script. For example, the Mnet::Log start, finish, and debug entries are not saved with stdout, and Mnet::Opts::Cli allows for command line options and arguments to be recorded and replayed with Mnet::Test files.

Refer to the perldoc TESTING sections in other Mnet modules for explanations of how each module supports the Mnet::Test test, record, and replay options.

This module uses the Mnet::Tee module to capture all stdout and stderr outputs from an executing script and can record, replay, and test for changes in those outputs.

When --test is used the exit status of the script will reflect whether output matched what is in the specified --replay file.

Scripts that use these modules may not need to do anything else to benefit from Mnet::Test support. At its most basic a script using this module can create a test data file with the --record option which will contain all the stdout and stderr output from the script. The --replay and --test options can be used to execute the script again and alert the user to any change in output.

Also note that the Mnet::Test::time function can be used to return repeatable sequences of outputs from the perl time command during --test execution. This helps to avoid changing timestamps causing test failures. The Mnet::Log module automatically normalizes timestamps when running tests.

Scripts or modules that need to save additional data to --record test data files can call the Mnet::Test::data function to get a referenced hash key that can be used to store data for the current script or module. The --record option will save this data to a file at the end of script execution, and the --replay option can be used to load that data back from the file into the Mnet::Test::data hash.

Scripts that do not use Mnet::Opts::Cli to parse command line options can pass the replay file as an argument to the Mnet::Test::data function and call the Mnet::Test::done function at the end of script execution.

Note that the Mnet environment variable is not parsed if the --test option is set on the command line, since the value of this envrionment variable may change over time, between users, systems, etc.

FUNCTIONS

Mnet::Test implements the functions listed below.

Mnet::Test::data

    \%data = Mnet::Test::data(\%opts);

This function returns a hash reference containing test/record/replay data for the calling module or the main script. It is up to the calling module or main script to manage its own test/record/replay data.

The opts hash ref argument is optional, and may be used if desired to specify a replay file. Otherwise the --replay cli option will be checked if the Mnet::Opts::Cli module is used to parse command line options.

Note that care must be taken to use the hash reference returned from this function properly. You want to save data in the returned hash reference, not accidently create a new hash reference. For example:

    ok:     my $data = Mnet::Test::data();
            $data->{sub_hash}->{key} = $value;

    ok:     my $data = Mnet::Test::data();
            my $sub_hash = \%{$data->{sub_hash}};
            $sub_hash->{key} = $value;

    ok:     my $sub_hash = \%{Mnet::Test::data()->{sub_hash}};
            $sub_hash->{key} = $value;

    bad:    Mnet::Test::data()->{sub_hash}->{key} = $value;

    bad:    my $data = Mnet::Test::data();
            my $sub_hash = $data->{sub_hash};
            $sub_hash->{key} = $value;

Refer to the DESCRIPTION section of this document for more information on how modules or scripts should use this function for test/record/replay data.

Mnet::Test::done

    $diff = Mnet::Test::done(\%opts)

This function does one or two things, depending on the how the record, replay, and test options are set.

If the --replay and --test options are set a diff of test output will be returned, or a value of undefined if there was no replay data.

If the --record option is set then the Mnet::Test data captured from the current script execution will be saved to the specified file.

This function is called automatically at script exit using the --record, --replay, and --test options parsed from a prior Mnet::Opts::Cli->new call. You do not need to call this function unless you are not using Mnet::Opts::Cli to parse command line options or if you want to examine your own test diff data.

If the test output has changed a fiff will be presented using the Text::Diff module.

Refer to the DESCRIPTION section of this document for more information.

Mnet::Test::time

    $unixtime = Mnet::Test::time($incrememt)
    or $unixtime = Mnet::Test::time(\%opts, $increment)

This function can be used by project scripts to get repeatable unixtime output during executions with the --test, --record, or --replay cli options set, and real time from the perl time command otherwise.

An optional incrememnt value can be specified in seconds, and defauls to the returned time being incremented by one second for each call to this function.

This function can be called with an opts hash ref, which can have record and replay keys set to indicate test output is needed. Otherwise these options are expected to be set via the Mnet::Opts::Cli module.

SEE ALSO

Mnet

Mnet::Log

Mnet::Opts::Cli

Mnet::Tee

Text::Diff

cpanm Mnet

perl -MCPAN -e shell
install Mnet