Scroll to navigation

Test2::Tools::Command(3pm) User Contributed Perl Documentation Test2::Tools::Command(3pm)

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.

Runs a command and executes one or more tests on the results, depending on the contents of hashref, which may contain:
List of arguments to run the command with. The argument list will be prefixed by the @command variable, if that is set.
If set, layer will be set on the filehandles wired to the command via the "binmode" function. See also open.
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.

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).
Custom name for the tests. Otherwise, the full command executed is used in the test name, which may not be ideal.
If the signal number of the 16-bit exit status word is not zero, the signal will be munged to have the value 1.
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.
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.

If present, data will be printed to the command and then standard input will be closed. Otherwise, nothing is done with standard input.
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.
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.
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 { ...
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>

2023-01-09 perl v5.36.0