NAME

Test::UnixCmdWrap - test unix commands with various assumptions

SYNOPSIS

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;

# enable coverage of the (presumably Perl) program via
#`cover -delete`
#$ENV{PERL5OPT} = '-MDevel::Cover';

# the program being tested
$echo->prog;

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

# illustration of various possible parameters, and the array
# test form for stdout
$echo->run(
  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 => '')
);

# additional tests via underlying object
my $o = $cmd->run( ... );
ok( $o->stdout =~ m/.../ );

DESCRIPTION

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).

ATTRIBUTES

cmd

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.

prog

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

METHODS

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:

chdir

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

env

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.

munge_status

This will transform any non-zero exit code to 1. Probably should be paired with status => 1 and a program that is expected to die with some random non-zero exit code.

status

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

stderr

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

stdin

Optional input to pipe to the program.

stdout

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.

BUGS

Patches might best be applied towards:

https://github.com/thrig/Test-UnixCmdWrap

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).

BUILD

Must be excluded from the Devel::Cover based Pod::Coverage checks somehow.

SEE ALSO

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

https://github.com/thrig/scripts/

AUTHOR

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

COPYRIGHT AND LICENSE

Copyright (C) 2019 by Jeremy Mates

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