NAME

Test::MockCommand::Result - stores and emulates commands

SYNOPSIS

# as called by Test::MockCommand::Recorder
my %args = (
    command     => 'ls -l',
    function    => 'readpipe', # or 'exec', 'system' or 'open',
    arguments   => \@_,
    caller      => [ caller() ]
);
my $result = Test::MockCommand::Result->new(%args);

# as called by Test::MockCommand
my $matches = $result->matches(%args);
my $return_value = $result->handle(
    %args,
    all_results => [ $all, $results, $matched, $including, $yourself ]
);

DESCRIPTION

This class which is the 'result' class used, created by Test::MockCommand::Recorder and queried by Test::MockCommand. It stores and replays the results of commands.

A result class should support any special features of the recorder class that creates it.

CONSTRUCTOR

new(%args)

This is called by Test::MockCommand::Recorder as part of its handle method. It passes on all the same arguments it was given by the main Test::MockCommand framework. See "handle" in Test::MockCommand::Recorder for details of each argument.

METHODS

$match_score = $result->matches(%args)

This method takes a list of criteria and returns a score of how well this object matches those critera. It's called by Test::MockCommand, both as part of its search for the right command to emulate, and also via the front-end find method. As such it may contain zero or more criteria. If no criteria are provided, the result should always be "this matches".

Return 0 to indicate no match, 1 to indicate a match, and higher numbers mean the result "matches better". If more than one result matches the given criteria, they will be sorted by this match score, highest first, and in the case of picking a result to emulate a command, the first in the list will be chosen.

The criteria are the same as listed in "handle" in Test::MockCommand::Recorder, however you can presume that the criteria function and command, if they are present, have been used to filter out results which don't match.

$return_value = $result->handle(%args)

This should emulate the function detailed in the arguments and return the value that the function itself is expected to return. The arguments are the same as listed in "handle" in Test::MockCommand::Recorder, and as with that method, any results for readpipe should be returned as a scalar, not a list, as the framework will break them into a list if needed.

$result->append_input_data($string)

Appends more text to the input_data attribute. Called by the tied filehandle's WRITE method while emulating an open call.

$result->append_output_data($string)

Appends more text to the output_data attribute. Called by the tied filehandle's WRITE method while emulating an open call.

$result->create_tied_fh()

Creates a Test::MockCommand::TiedFH filehandle attached to this object.

ATTRIBUTES

$attribute_value = $result->attribute_name()
$result->attribute_name($new_attribute_value)

Each result object can store a number of attributes, which you can get and set via accessor methods as shown above. The attributes are as follows:

command

Roughly the command being run. Use the function and arguments attributes for a completely accurate version. For example system('ls', 'foo', 'bar'); and system('ls', 'foo bar') will generate the same command attribute, "ls foo bar".

function

The function that generated this result. This will be exec, open, readpipe or system.

arguments

An arrayref to the original arguments of the function. However, the first argument to open() is always turned to undef, to allow for the result to be saved and loaded into another program where a named filehandle reference might not exist.

return_value

The return value originally captured from this function

cwd

The current working directory at the time this function was called.

input_data

Any input data sent into the command. (open only)

output_data

The output generated by the command (open only)

exit_code

The value of $? after running the command.

all_results

Available only while handle is being called. It's a list of all possible candidates for execution, including this result.