Provided by: libtest2-tools-command-perl_0.20-2_all 
NAME
Test2::Tools::Command - test simple unix commands
SYNOPSIS
use Test2::Tools::Command;
# test some typical unix tools; implicit checks are that status
# is 0, and that stdout and stderr are the empty string, unless
# otherwise specified
command { args => [ 'true' ] };
command { args => [ 'false' ], status => 1 };
command { args => [ 'echo', 'foo' ], stdout => "foo\n" };
# subsequent args are prefixed with this
local @Test2::Tools::Command::command = ( 'perl', '-E' );
# return values and a variety of the options available
my ($result, $exit_status, $stdout_ref, $stderr_ref) =
command { args => [ q{say "out";warn "err";kill TERM => $$} ],
chdir => '/some/dir',
env => { API_KEY => 42 },
stdin => "printed to program\n",
stdout => qr/out/,
stderr => qr/err/,
status => { code => 0, signal => 15, iscore => 0 },
timeout => 7 };
# check on a $? exit status word from somewhere
is_exit $?, 42;
is_exit $?, { code => 0, signal => 9, iscore => 0 };
DESCRIPTION
This module tests that commands given particular arguments result in particular outputs by
way of the exit status word, standard output, and standard error. Various parameters to
the command function alter exactly how this is done, in addition to variables that can be
set.
The commands are expected to be simple, for example filters that maybe accept standard
input and respond with some but not too much output. Interactive or otherwise complicated
commands will need some other module such as Expect to test them, as will programs that
generate too much output.
Also, is_exit is provided to check on the 16-bit exit status word from other code.
VARIABLES
These are not exported.
@command
Custom command to prefix any commands run by command with, for example to specify a
test program that will be used in many subsequent tests
local @Test2::Tools::Command::command = ($^X, '--', 'bin/foo');
command { args => [ 'bar', '-c', 'baz' ] };
will result in "perl -- bin/foo bar -c baz" being run.
If chdir is used, a command that uses a relative path may need to be fully qualified,
e.g. with "rel2abs" of File::Spec::Functions.
$timeout
Seconds after which commands will be timed out via "alarm" if a timeout is not given
to command. 30 by default.
FUNCTIONS
command is exported by default; this can be disabled by using this module with an empty
import list. The test keys are status, stdout, and stderr. The other keys influence how
the command is run or change test metadata.
command hashref
Runs a command and executes one or more tests on the results, depending on the
contents of hashref, which may contain:
args => arrayref
List of arguments to run the command with. The argument list will be prefixed by
the @command variable, if that is set.
binmode => layer
If set, layer will be set on the filehandles wired to the command via the
"binmode" function. See also open.
chdir => directory
Attempt to "chdir" into directory or failing that will throw an exception, by way
of File::chdir.
A command that uses a relative path may need to be fully qualified, e.g. with
"rel2abs" of File::Spec::Functions.
env => hashref
Set the environment for the command to include the keys and values present in
hashref. This is additive only; environment variables that must not be set must be
deleted from %ENV, or the command wrapped with a command that can reset the
environment, such as env(1).
name => string
Custom name for the tests. Otherwise, the full command executed is used in the
test name, which may not be ideal.
munge_signal => boolean
If the signal number of the 16-bit exit status word is not zero, the signal will
be munged to have the value 1.
munge_status => boolean
If the exit code of the 16-bit exit status word is not zero, the code will be
munged to have the value 1. Use this where the program being tested is
unpredictable as to what non-zero exit code it will use.
status => code-or-hashref
Expect the given value as the 16-bit exit status word. By default 0 for the exit
code is assumed. This can be specified in two different forms; the following two
are equivalent:
status => 42
status => { code => 42, iscore => 0, signal => 0 }
Obviously the 16-bit exit status word is decomposed into a hash reference. If the
program is instead expected to exit by a SIGPIPE, one might use:
status => { code => 0, iscore => 0, signal => 13 }
See also munge_signal and munge_status.
stdin => data
If present, data will be printed to the command and then standard input will be
closed. Otherwise, nothing is done with standard input.
stdout => qr-or-string
Expect that the standard output of the command exactly matches the given string,
or if the string is a "qr//" regular expression, that the output matches that
expression.
stderr => qr-or-string
Expect that the standard err of the command exactly matches the given string, or
if the string is a "qr//" regular expression, that the stderr matches that
expression.
timeout => seconds
Set a custom timeout for the "alarm" call that wraps the command. The variable
$timeout will be used if this is unset.
command returns a list consisting of the result of the tests, the original 16-bit exit
status word, and scalar references to strings that contain the standard output and
standard error of the test program, if any.
my ($result, $status, $out_ref, $err_ref) = command { ...
is_exit status [ code-or-hashref [ test-name ] ]
This routine checks that a 16-bit exit status word (usually by way of the $? variable)
conforms to some code or hash reference. The hash reference may contain mungle_signal
and munge_status that will turn non-zero signal or codes into 1.
is_exit $?, 42;
is_exit $?, { code => 0, signal => 9, iscore => 0 };
BUGS
None known. There are probably portability problems if you stray from the unix path.
SEE ALSO
Test2::Suite
Expect may be necessary to test complicated programs.
IPC::Open3 is used to run programs; this may run into portability problems on systems that
stray from the way of unix?
COPYRIGHT AND LICENSE
Copyright 2022 Jeremy Mates
This program is distributed under the (Revised) BSD License:
<https://opensource.org/licenses/BSD-3-Clause>