Test::...:Simple(3pm)

📦
version 0.05 · 5 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

🦋 Test::Command::Simple — the manual page, but make it cute

okay bestie, so you know how this whole thing is officially part of the User Contributed Perl Documentation for Test::...:Simple(3pm)? Yeah. That's the vibe. It's a Perl module manual page. Let's get into it 💅

✨ NAME ✨

Test::Command::Simple — test external commands (nearly) as easily as loaded modules. No cap, that's the whole pitch 🫶

🌸 VERSION 🌸

Version 0.05. Iconic. Slightly vintage. We love her.

💖 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');

look at that. gorgeous. so clean. ✨

🎀 PURPOSE 🎀

okay so literally the whole point of this test module is to make testing external commands easier. Like, simpler than it has any right to be.

How does it do it? She runs your command under IPC::Open3, immediately closes the stdin, and then reads everything off the command's stdout and stderr. Then she hands you all that output so you can poke at it with tests. that's it. that's the job 🫶

She is not (yet?) as feature-rich as Test::Cmd — but lowkey the interface here is way simpler. And the tests plug directly into the Test::Builder framework, so it plays super nice with Test::More. friendship goals honestly.

Now, compared to Test::Command, this module is simpler: it relies on you to feed rc, stdout and stderr into whatever other tests you want — presumably in Test::More, but like, not necessarily, do your thing. And that's genuinely powerful, because it means you can, for example, 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');

And yeah, technically you could do that with Test::Command's stdout_like, but some regexes get so awkward and honestly it becomes way better to just do it in multiple steps. it's giving ✨divide and conquer✨

Also, heads up: Test::Command saves stdout and stderr to files. That's a real advantage when you're saving a lot of text. But this module prefers to slurp everything in using IPC::Open3, IO::Select, and sysread. And most of the time, the commands being tested don't produce significant amounts of output, so there's literally no reason to use temporary files and drag the disk into it. leave the disk alone she's resting 😭

👑 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. So 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, ngl.

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.

💜 rc

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. three for the price of one, she's efficient.

🌈 AUTHOR 🌈

Darin McBride, "<dmcbride at cpan.org>" — thank you for your service 🫡

🙈 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. bestie we're in this together fr fr 💖

🧚 SUPPORT 🧚

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

perldoc Test::Command::Simple

You can also look for information at:

⭐ ACKNOWLEDGEMENTS ⭐

...okay so this section is literally empty in the original. nothing here. a blank canvas. she said "no thoughts, head empty" 🌸 (still a whole section though, so we're keeping it, periodt.)

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.

okay that's the whole page, you're fully caught up bestie 💖

this has been perl v5.36.0, dated 2022-10-13, and it lives at Test::...:Simple(3pm) — slay, go write some tests, you got this 👑✨

📦 where this page comes from