Author image thrig
and 1 contributors


Test::UnixCmdWrap - test unix commands with various assumptions


in ./t/echo.t and assuming that an ./echo exists...

  use Test::More;
  use Test::UnixCmdWrap;

  # create testor for ./echo
  my $echo = Test::UnixCmdWrap->new;

  # the program being tested

  # tests stdout, and that there is no stderr, and that the exit
  # status word is 0
    args   => 'foo bar',
    stdout => qr/^foo bar$/,

  # illustration of various possible parameters, and the array
  # test form for stdout
    chdir  => '/etc',
    env    => { PATH => '/foo', MANPATH => '/bar', },
    stdin  => 'some input',
    stdout => [ '' ],
    stderr => qr/^$/,

  # custom 'cmd' constructor instead of the default
  Test::UnixCmdWrap->new( cmd => './script/echo' );
  # same, only being even more verbose
  Test::UnixCmdWrap->new( cmd =>
    Test::Cmd->new(prog => './script/echo', workdir => '')



Test::UnixCmdWrap wraps Test::Cmd and provides automatic filename detection of the program being tested, and tests the exit status word, stdout, and stderr of each program run. Various other parameters can be used to customize individual program runs.

These are very specific tests for unix commands that behave in specific ways (known exit status word for given inputs, etc) so this module will not suit more generic needs (which is what more generic modules like Test::Cmd are for).



Read-only attribute containing the Test::Cmd object associated with the command being tested. This is created by default from $0 on the assumption that t/foo.t contains tests for the program ./foo, unless you specify otherwise when calling new.


Read-only program name being tested. May or may not be a fully qualified path to the program.


new [ cmd => ... ]

Makes a new object. Supply a custom cmd attribute if the default for cmd does not work for you.

run ...

Runs the command. Various parameters can be added to adjust the inputs to the command and expected results. By default the command is assumed to exit with status code 0, and emit nothing to stdout, and nothing to stderr. Parameters:


Optional directory to chdir into prior to the test (passed to Test::Cmd as chdir flag for run).


Optional hash reference with local elements to add to %ENV during the test. Other envrionment variables may need to be deleted from %ENV prior to the tests, this only adds.


Optional unix exit status word, by default 0. See Test::UnixExit for the more complicated forms this value supports.


Optional regular expression to check the standard error of the command against, empty string by default.


Optional input to pipe to the program.


Optional regular expression or array reference to check the standard output of the command against, empty string by default.

run returns the Test::Cmd object, if subsequent tests need to do more with that object. Each call to run runs three tests, if you are keeping track for done_testing.


Patches might best be applied towards:

Known Issues

Need to standardize on whether the program name is always qualified or not (complicated by the user possibly passing in a Test::Cmd object with something else set).


Test::Cmd, Test::Differences, Test::More, Test::UnixExit


thrig - Jeremy Mates (cpan:JMATES) <jmates at>


Copyright (C) 2019 by Jeremy Mates

This program is distributed under the (Revised) BSD License: