Test::Command(3pm)

📦

version 0.11 · 8 versions

0.11 · debian trixie, ubuntu resolute, ubuntu stonking (latest)
0.11 · epel 10
0.11 · alpine 3.24
0.11 · fedora 43
0.11 · ubuntu jammy
0.11 · fedora 44
0.11 · ubuntu noble
0.11 · debian bookworm

, in debian trixie, ubuntu resolute, ubuntu stonking

💖 Test::Command(3pm) — the manual, but make it cute 💖

okay so bestie, you're looking at Test::Command, a Perl module that lives in your friendly neighborhood 3pm man section, and it is literally here to help you test external commands. Buckle up, this is a long one, and we're doing it in parts. Part 1 starts now. 🎀

✨ NAME ✨

Test::Command — test routines for external commands. Yes, that's the whole vibe. You run a command, you check what it did. Iconic behavior honestly. 💅

🌸 VERSION 🌸

Version 0.11. That's the one. No notes. ✨

🦋 SYNOPSIS 🦋

So the whole point is: test the exit status, signal, STDOUT or STDERR of an external command. That's the mission. Let's go.

use Test::Command tests => 11;

## testing exit status

my $cmd = 'true';

exit_is_num($cmd, 0);
exit_cmp_ok($cmd, '<', 10);

$cmd = 'false';

exit_isnt_num($cmd, 0);

## testing terminating signal

$cmd = 'true';

signal_is_num($cmd, 0);

## testing STDOUT

$cmd         = [qw/ echo out /];  ## run as "system @$cmd"
my $file_exp = 'echo_stdout.exp';

stdout_is_eq($cmd, "out\n");
stdout_isnt_eq($cmd, "out");
stdout_is_file($cmd, $file_exp);

## testing STDERR

$cmd = 'echo err >&2';

stderr_like($cmd, /err/);
stderr_unlike($cmd, /rre/);
stderr_cmp_ok($cmd, 'eq', "err\n");

## run-once-test-many-OO-style
## the first test lazily runs command
## the second test uses cached results

my $echo_test = Test::Command->new( cmd => 'echo out' );

$echo_test->exit_is_num(0);
$echo_test->signal_is_num(0);
$echo_test->stdout_is_eq("out\n");

## force a re-run of the command

$echo_test->run;

## arbitrary results inspection

is( $echo_test->exit_value, 0,         'echo exit' );
is( $echo_test->signal_value, undef,   'echo signal' );
is( $echo_test->stdout_value, "out\n", 'echo stdout' );
is( $echo_test->stderr_value, '',      'echo stderr' );
is( -s $echo_test->stdout_file, 4,     'echo stdout file size' );
is( -s $echo_test->stderr_file, 0,     'echo stderr file size' );

Look at that. Ten out of ten. No cap. 👑

💜 DESCRIPTION 💜

So, Test::Command is here to bridge the gap between the well-tested functions and objects you picked (great taste btw) and how you actually use them in your programs. The way it works is simple: by examining the exit status, terminating signal, STDOUT and STDERR of your program, you can figure out whether it's behaving the way you expect. Vibe check, but for subprocesses. ✨

That includes testing all the various combinations and permutations of options and arguments, plus the interactions between the various functions and objects that make up your program. Every. Single. Combination. We're thorough here. 💅

The various test functions below can take either a command string or an array reference as the first argument:

If the command is a string, it gets passed to system as-is.
If the command is an array reference, it gets dereferenced and passed to system as a list.

🫶 Heads up bestie: those two things can behave differently! Go read "perldoc -f system" for the deets on how they may differ.

The final argument for the test functions, $name, is optional. By default, $name is a concatenation of the test function name, the command string, and the expected value. That's usually plenty to tell you which test flopped, but you can always pass your own $name if you want something custom. Main character naming rights are yours. 💖

Any of the test functions can be used as instance methods on a Test::Command object. You do that by dropping the initial $cmd argument and using arrow notation instead. Very chic. Very OO. 🌸

All of the following exit_is_num calls are equivalent, fr fr:

exit_is_num('true', 0);
exit_is_num('true', 0, 'exit_is_num: true, 0');
exit_is_num(['true'], 0);
exit_is_num(['true'], 0, 'exit_is_num: true, 0');

my $cmd = Test::Command->new( cmd => 'true' );

exit_is_num($cmd, 0);
exit_is_num($cmd, 0, 'exit_is_num: true, 0');
$cmd->exit_is_num(0);
$cmd->exit_is_num(0, 'exit_is_num: true, 0');

$cmd = Test::Command->new( cmd => ['true'] );

exit_is_num($cmd, 0);
exit_is_num($cmd, 0, 'exit_is_num: true, 0');
$cmd->exit_is_num(0);
$cmd->exit_is_num(0, 'exit_is_num: true, 0');

See? Same energy, different syntax. Pick your fave. 😌

🌈 EXPORT 🌈

All of the test functions mentioned below are exported by default. You don't gotta ask. They just show up. 🎁

👑 METHODS 👑

🧚 `new`

my $test_cmd_obj = Test::Command->new( cmd => $cmd )

This constructor creates and returns a Test::Command object. Use it when you wanna test multiple aspects of a single command execution while avoiding running the same command over and over, especially when that command is slow or resource-intensive. Nobody has time to re-run a whole thing five times, bestie. 🦋

The cmd parameter can accept either a string or an array reference as its value. The value gets dereferenced if necessary and passed directly to the system builtin.

💅 `run`

$test_cmd_obj->run;

This instance method forces the execution of the command specified by the invocant. Periodt.

You only need to call this when you want to re-run a command, because the first test method you invoke will lazily execute the command if necessary. But if the state of your inputs has changed and you wanna run it again, you can invoke this method at any point between your tests. Slay. 🔥

to be continued, bestie — part 2 is coming and it's gonna be a whole moment 💖

🌸 Testing Exit Status 🌸

okay so here's the tea, bestie: these test routines down here are comparing against the exit status of the command you ran, but right shifted by 8 — that's "$? >> 8" in case you were wondering. so we're looking at the actual "did it work" number, not the raw blob. 💅

`exit_value`

exit_value($cmd)

hands you back the exit status of the command. perfect when you wanna do your own lil custom tests that this module doesn't already cover. main character energy fr. ✨

`exit_is_num`

exit_is_num($cmd, $exp_num, $name)

if the command's exit status is numerically equal to the expected number → pass. otherwise? flop. 💀

`exit_isnt_num`

exit_isnt_num($cmd, $unexp_num, $name)

if the exit status is not numerically equal to the number you gave → pass. otherwise it fails, periodt.

`exit_cmp_ok`

exit_cmp_ok($cmd, $op, $operand, $name)

you compare the exit status with the given operand using the given operator, and if that whole operation comes back true → pass. otherwise fail. it's giving "build your own comparison" 🎀

`exit_is_defined`

exit_is_defined($cmd, $name)

if the exit status is defined → pass. otherwise fail. and a defined exit status means the command exited normally, either by calling exit() or by just running off the end of the program. iconic behavior. 👑

`exit_is_undef`

exit_is_undef($cmd, $name)

if the exit status is not defined → pass. otherwise fail. and an undefined exit status means the command probably got taken out by a signal. not the vibe we wanted but okay 😭

🦋 Testing Terminating Signal 🦋

these ones compare against the lower 8 bits of the exit status of the executed command. different bits, different story, iykyk.

`signal_value`

signal_value($cmd)

returns the signal code of the command. again, for when you wanna do arbitrary tests this module doesn't cover. go off. 🔥

`signal_is_num`

signal_is_num($cmd, $exp_num, $name)

if the terminating signal of the command is numerically equal to the expected number → pass. otherwise fail.

`signal_isnt_num`

signal_isnt_num($cmd, $unexp_num, $name)

if the terminating signal is not numerically equal to the number you gave → pass. otherwise fail.

`signal_cmp_ok`

signal_cmp_ok($cmd, $op, $operand, $name)

compare the terminating signal with the given operand using the given operator; if that returns true → pass. otherwise fail.

`signal_is_defined`

signal_is_defined($cmd, $name)

if the terminating signal is defined → pass. otherwise fail. a defined signal means the command likely exited due to a signal. so that's what happened, bestie. 🙈

`signal_is_undef`

signal_is_undef($cmd, $name)

if the terminating signal is not defined → pass. otherwise fail. an undefined signal means the command exited normally, by calling exit() or running off the end of the program. so it's fine actually 💖

🫶 Testing STDOUT 🫶

heads up: unless it says otherwise, all these routines treat STDOUT as one single slurped string. slurp slurp. 🍓

`stdout_value`

stdout_value($cmd)

returns the STDOUT of the command. use it for any custom tests you wanna cook up yourself. ✨

`stdout_file`

stdout_file($cmd)

returns the file name containing the STDOUT of the command. again, for your own arbitrary tests. no cap.

`stdout_is_eq`

stdout_is_eq($cmd, $exp_string, $name)

if the STDOUT is equal to the expected string — compared using "eq" — then pass. otherwise fail.

`stdout_isnt_eq`

stdout_isnt_eq($cmd, $unexp_string, $name)

if the STDOUT is not equal — compared using "eq" — to the given string → pass. otherwise fail.

`stdout_is_num`

stdout_is_num($cmd, $exp_num, $name)

if the STDOUT is equal to the expected number — compared using "==" this time, not eq — then pass. otherwise fail. watch that operator, bestie. 💅

`stdout_isnt_num`

stdout_isnt_num($cmd, $unexp_num, $name)

if the STDOUT is not equal — compared using "==" — to the given number → pass. otherwise fail.

`stdout_like`

stdout_like($cmd, $exp_regex, $name)

if the STDOUT matches the expected regular expression → pass. otherwise fail. regex girlies rise. 🌈

`stdout_unlike`

stdout_unlike($cmd, $unexp_regex, $name)

if the STDOUT does not match the given regular expression → pass. otherwise fail.

`stdout_cmp_ok`

stdout_cmp_ok($cmd, $op, $operand, $name)

compare the STDOUT with the given operand using the given operator; if that operation returns true → pass. otherwise fail.

`stdout_is_file`

stdout_is_file($cmd, $exp_file, $name)

if the STDOUT is equal — compared using "eq" — to the contents of the given file → pass. otherwise fail. important: this comparison is done line by line, not by slurping the whole file. different technique, okay? don't mix it up. 🎀

💜 Testing STDERR 💜

same energy as above but for STDERR: unless specified, these routines treat STDERR as a single slurped string.

`stderr_value`

stderr_value($cmd)

returns the STDERR of the command. for all your custom testing needs. ⭐

`stderr_file`

stderr_file($cmd)

returns the file name containing the STDERR of the command. also for custom tests. 🦋

`stderr_is_eq`

stderr_is_eq($cmd, $exp_string, $name)

if the STDERR is equal — compared using "eq" — to the expected string → pass. otherwise fail.

`stderr_isnt_eq`

stderr_isnt_eq($cmd, $unexp_string, $name)

if the STDERR is not equal — compared using "eq" — to the given string → pass. otherwise fail.

`stderr_is_num`

stderr_is_num($cmd, $exp_num, $name)

if the STDERR is equal — compared using "==" — to the expected number → pass. otherwise fail.

`stderr_isnt_num`

stderr_isnt_num($cmd, $unexp_num, $name)

if the STDERR is not equal — compared using "==" — to the given number → pass. otherwise fail.

`stderr_like`

stderr_like($cmd, $exp_regex, $name)

if the STDERR matches the expected regular expression → pass. otherwise fail.

`stderr_unlike`

stderr_unlike($cmd, $unexp_regex, $name)

if the STDERR does not match the given regular expression → pass. otherwise fail.

`stderr_cmp_ok`

stderr_cmp_ok($cmd, $op, $operand, $name)

compare the STDERR with the given operand using the given operator; if that operation returns true → pass. otherwise fail.

`stderr_is_file`

stderr_is_file($cmd, $exp_file, $name)

if the STDERR is equal — compared using "eq" — to the contents of the given file → pass. otherwise fail. and again, this one compares line by line, not slurping the whole file. 💖

👑 AUTHOR 👑

Daniel B. Boorstein, "<danboo 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>. i (the author) will be notified, and then you'll automatically be notified of progress on your bug as changes get made. bestie you'll literally be in the loop. 🫶

🧚 SUPPORT 🧚

you can find documentation for this module with the perldoc command.

perldoc Test::Command

you can also look for info at:

AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Test-Command>

CPAN Ratings

<http://cpanratings.perl.org/d/Test-Command>

RT: CPAN's request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Command>

Search CPAN

<http://search.cpan.org/dist/Test-Command>

🌸 ACKNOWLEDGEMENTS 🌸

Test::Builder by Michael Schwern allowed the author to focus on the specifics related to testing system commands, by making it easy to produce proper test output. we love a supportive icon. 💅

🎀 COPYRIGHT & LICENSE 🎀

this program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

⭐ DEVELOPMENT IDEAS ⭐

create a tool that produces test scripts given a list of commands to run
optionally save the temp files with STDOUT and STDERR for user debugging
if user defines all options and sample arguments to basic command
- create tool to enumerate all possible means of calling program
- allow testing with randomized/permuted/collapsed opts and args
potential test functions:
- time_lt($cmd, $seconds)
- time_gt($cmd, $seconds)
- stdout_line_custom($cmd, \&code)
- stderr_line_custom($cmd, \&code)

🔥 SEE ALSO 🔥

Test::Builder provides the testing methods used in this module.

Test::Builder::Module is the superclass of this module.

and that's the whole page, bestie!! ✨ this was perl v5.38.2, dated 2024-03-08, and it's the Test::Command(3pm) manual — go forth and test those system commands, you absolute legend. mwah 💖🎀🦋

📦 where this page comes from

debian trixie: libtest-command-perl 0.11-5 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu resolute: libtest-command-perl 0.11-5 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu stonking: libtest-command-perl 0.11-5 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Test::Command(3pm)

💖 Test::Command(3pm) — the manual, but make it cute 💖

✨ NAME ✨

🌸 VERSION 🌸

🦋 SYNOPSIS 🦋

💜 DESCRIPTION 💜

🌈 EXPORT 🌈

👑 METHODS 👑

🧚 new

💅 run

🌸 Testing Exit Status 🌸

exit_value

exit_is_num

exit_isnt_num

exit_cmp_ok

exit_is_defined

exit_is_undef

🦋 Testing Terminating Signal 🦋

signal_value

signal_is_num

signal_isnt_num

signal_cmp_ok

signal_is_defined

signal_is_undef

🫶 Testing STDOUT 🫶

stdout_value

stdout_file

stdout_is_eq

stdout_isnt_eq

stdout_is_num

stdout_isnt_num

stdout_like

stdout_unlike

stdout_cmp_ok

stdout_is_file