NAME

Test2::Tools::Command - run unix commands

SYNOPSIS

use Test2::V0;
use Test2::Tools::Command;

command { args   => [ 'perl', '-E', q{say "out"; exit 42} ],
          chdir  => '/some/dir',
          stdin  => "printed to program\n",
          stdout => qr/out/,
          status => 42 };

# subsequent args are prefixed with this command
local @Test2::Tools::Command::command = ( 'perl', '-E' );

like dies { command { args    => [ 'sleep 99' ],
                      timeout => 1 }
          }, qr/timeout/;

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.

VARIABLES

@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. 3600 by default.

FUNCTIONS

command is exported by default.

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 (or failing to restore the previous directory) will throw an exception.

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 local environment to the keys and values present in hashref. This is additive only; environment variables that must not be set must be deleted from %ENV prior, or the command wrapped with a command that can reset the environment, possibly such as env(1).

munge_status => boolean

If the exit code of the exit status word is not zero, it will be munged to have the value of 1. Use this where the program being tested is unpredictable as to what (non-zero, non-signal) exit code it will use.

status => code-or-hashref

Expect the given value as the 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 }

If the program is instead expected to exit by a SIGPIPE, one might use:

status => { code => 0, iscore => 0, signal => 13 }

See also munge_status.

stdin => data

If present, data will be printed to the command and then standard input will be closed.

timeout => seconds

Set a custom timeout for the alarm call that wraps the command to be run. The variable $timeout will be used if this is unset.

want_fh => boolean

If true, filehandles will be returned from command and the usual stdin and stderr tests will not be run.

command returns stdout, stderr, and the exit status word. stdout and stderr will either be filehandles (if want_fh is true) or scalar references to strings that contain all of standard output and standard error from the program.

BUGS

None known. There are probably portability problems if you stray from the unix path.

SEE ALSO

Test2::Suite

IPC::Open3 is used to run programs; this may run into portability problems on systems that stray from the way of unix?

Test::UnixCmdWrap is older and has similar functionality; probably more portable at the cost of probably being slower.

Test::UnixExit has specific tests for the unix exit status word; similar functionality is present in this module.

COPYRIGHT AND LICENSE

Copyright 2022 Jeremy Mates

This program is distributed under the (Revised) BSD License: https://opensource.org/licenses/BSD-3-Clause