NAME
Mnet::Test - Record, replay, and test script inputs and outputs
SYNOPSIS
# sample test script
#
# first create an Mnet::Test file with --record <file>
# next replay the test with --test --replay <file>
# add a print statement to cause test replay to fail
# required for this sample
# refer to TESTING perldoc in other Mnet modules
use Mnet::Expect::Cli;
use Mnet::Opts::Cli;
use Mnet::Test;
# other cli options could be defined and recorded in tests
my $cli = Mnet::Opts::Cli->new;
# the Mnet::Expect::Cli modules can record session command outputs
my $expect = Mnet::Expect::Cli({ spawn => "ssh 1.2.3.4" });
my $output = $expect->command("whoami");
# stdout and stderr are captures for tests
print "$output\n";DESCRIPTION
Mnet::Test can be used to allow script inputs and output to be recorded to a file, which can be replayed later to show any changes.
Other Mnet modules are designed to detect and make use of Mnet::Test, if it is being used by a script. Refer to the perldoc TESTING sections of the other modules for explanations of how each module supports Mnet::Test usage. Also refer to the --test, --record, and --replay options for more information.
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.
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 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 optional environment variable that can be specified when creating a new Mnet::Opts::Cli object 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 diff 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.