NAME¶
Test::Command - Test external commands (nearly) as easily as loaded modules.
VERSION¶
Version 0.04
SYNOPSIS¶
use Test::Command::Simple;
run('echo', 'has this output'); # only tests that the command can be started, not checking rc
is(rc,0,'Returned successfully')
like(stdout,qr/has this output/,'Testing stdout');
is(length stderr, 0,'No stderr');
PURPOSE¶
This test module is intended to simplify testing of external commands. It does
so by running the command under IPC::Open3, closing the stdin immediately, and
reading everything from the command's stdout and stderr. It then makes the
output available to be tested.
It is not (yet?) as feature-rich as Test::Cmd, but I think the interface to this
is much simpler. Tests also plug directly into the Test::Builder framework,
which plays nice with Test::More.
As compared to Test::Command, this module is simpler, relying on the user to
feed rc, stdout, and stderr to the appropriate other tests, presumably in
Test::More, but not necessarily. This makes it possible, for example, to test
line 3 of the output:
my (undef, undef, $line) = split /\r?\n/, stdout;
is($line, 'This is the third line', 'Test the third line');
While this is possible to do with Test::Command's stdout_like, some regex's can
get very awkward, and it becomes better to do this in multiple steps.
Also, Test::Command saves stdout and stderr to files. That has an advantage when
you're saving a lot of text. However, this module prefers to slurp everything
in using IPC::Open3, IO::Select, and sysread. Most of the time, commands being
tested do not produce significant amounts of output, so there becomes no
reason to use temporary files and involve the disk at all.
EXPORTS¶
run¶
Runs the given command. It will return when the command is done.
This will also reinitialise all of the states for stdout, stderr, and rc. If you
need to keep the values of a previous
run() after a later one, you will
need to store it. This should be mostly pretty rare.
Counts as one test: whether the IPC::Open3 call to open3 succeeded. That is not
returned in a meaningful way to the user, though. To check if that's the case
for purposes of SKIPping, rc will be set to -1.
stdout¶
Returns the last run's stdout
stderr¶
Returns the last run's stderr
Returns the last run's full $?, suitable for passing to POSIX's :sys_wait_h
macros (WIFEXITED, WEXITSTATUS, etc.)
exit_status¶
Returns the exit status of the last run
run_ok¶
Shortcut for checking that the return from a command is 0. Will still set stdout
and stderr for further testing.
If the first parameter is an integer 0-255, then that is the expected return
code instead. Remember: $? has both a return code (0-255) and a reason for
exit embedded. This function must make the assumption that you want a
"normal" exit only. If any signal is given, this will treat that as
a failure.
Note that this becomes
three tests: one that IPC::Open3 could create the
subprocess with the command, the next is the test that the process exited
normally, and the last is the test of the rc.
AUTHOR¶
Darin McBride, "<dmcbride at cpan.org>"
BUGS¶
Please report any bugs or feature requests to "bug-test-command at
rt.cpan.org", or through the web interface at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Command-Simple>. I
will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
SUPPORT¶
You can find documentation for this module with the perldoc command.
perldoc Test::Command::Simple
You can also look for information at:
- •
- RT: CPAN's request tracker
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Command-Simple>
- •
- AnnoCPAN: Annotated CPAN documentation
<http://annocpan.org/dist/Test-Command-Simple>
- •
- CPAN Ratings
<http://cpanratings.perl.org/d/Test-Command-Simple>
- •
- Search CPAN
<http://search.cpan.org/dist/Test-Command-Simple/>
ACKNOWLEDGEMENTS¶
LICENSE AND COPYRIGHT¶
Copyright 2010 Darin McBride.
This program is free software; you can redistribute it and/or modify it under
the terms of either: the GNU General Public License as published by the Free
Software Foundation; or the Artistic License.
See
http://dev.perl.org/licenses/ for more information.