Test::...pt::Run(3pm)

✨ NAME ✨

Test::Script::Run — test scripts with run 💖

okay so real talk, this whole page lives inside the perl docs as Test::...pt::Run(3pm) (yes the name got squished, it's the truncated short name of the page, and the section is User Contributed Perl Documentation, so you know it's a community bop 🫶). Main character of this page: Test::Script::Run. It tests your scripts. With run. Slay.

---

🌸 SYNOPSIS 🌸

use Test::Script::Run;
# customized names of bin dirs, default is qw/bin sbin script ./;
@Test::Script::Run::BIN_DIRS = qw/bin/;
run_ok( 'app_name', [ app's args ], 'you_app runs ok' );
my ( $return, $stdout, $stderr ) = run_script( 'app_name', [ app's args ] );
run_output_matches(
    'app_name', [app's args],
    [ 'out line 1', 'out line 2' ],
    [ 'err line 1', 'err line 2' ],
    'run_output_matches'
);
run_output_matches_unordered(
    'app_name', [ app's args ],
    [ 'out line 2', 'out line 1' ],
    [ 'err line 2', 'err line 1' ],
    'run_output_matches_unordered'
);

---

💜 DESCRIPTION 💜

So this module exports a bunch of subs that help you test and run scripts sitting in your dist's script directory (think bin, sbin, script, etc) — but only if the script path isn't absolute. Absolute paths just do their own thing, no search party needed 💅

Fun little lore drop: nearly all the essential code here is stolen from Prophet::Test 😭 The authors were like "hmm these subs really should live under the Test:: namespace," so they packed them up and created this module. Respect the hustle fr fr.

---

🦋 FUNCTIONS 🦋

run_script($script, $args, $stdout, $stderr)

Runs the script $script as a perl script, and sets @INC to be exactly the same as our caller's. No cap, it matches your caller's @INC.

• $script — the name of the script to be run (such as 'prophet').
• $args — a reference to an array of arguments to pass to the script.
• $stdout and $stderr — both optional. If you pass them in, they get handed straight to IPC::Run3's run3 subroutine as its $stdout and $stderr args. If you don't pass them, this subroutine makes its own scalar references to pass to run3 instead (and those get treated as strings for STDOUT/STDERR to be written to).

Returns run3's return value, and — if no $stdout and $stderr were passed in — the STDOUT and STDERR of the script that was run. It's giving "you get the receipts back" 🧾

run_ok($script, $args, $msg)

Runs the script and checks that it didn't error out. Vibe check on your script, basically.

• $script — the name of the script to be run (e.g. 'prophet').
• $args — an optional reference to an array of arguments to pass to the script when it is run.
• $msg — an optional message to print with the test.

Little tip: if $args is not specified, you can still pass in a $msg. So don't let the optional-ness stress you out 💅

Returns nothing of interest. Like, genuinely nothing. Move along.

run_not_ok($script, $args, $msg)

opposite of run_ok 🙃

get_perl_cmd($script, @ARGS)

Returns a list suitable for passing to "system", "exec", etc. And if you pass $script, we will search upwards for it in @BIN_DIRS 🔍

is_script_output($scriptname \@args, \@stdout_match, \@stderr_match, $msg)

Runs $scriptname and checks to see that its output matches. The moment of truth ✨

• $args — an array reference of args to pass to the script.
• $stdout_match and $stderr_match — references to arrays of expected lines.
• $msg — a string message to display with the test.

Now the optionality tea ☕: $stderr_match and $msg are optional. (As is $stdout_match if for some reason you expect your script to have no output at all. But that would be silly, wouldn't it? 😭)

And yes, this allows regex matches as well as string equality — lines in $stdout_match and $stderr_match may be Regexp objects. Iconic.

run_output_matches($script, $args, $exp_stdout, $exp_stderr, $msg)

A wrapper around is_script_output that also checks to make sure the test runs without throwing an exception. Double protection, we love to see it 🛡️

run_output_matches_unordered($script, $args, $exp_stdout, $exp_stderr, $msg)

This subroutine has exactly the same functionality as run_output_matches, but it doesn't impose a line ordering when comparing the expected and received outputs. Chaos-friendly. Order is a social construct 💅

last_script_stdout

return last script's stdout 📤

last_script_stderr

return last script's stderr 📥

last_script_exit_code

return last script's exit code 🚪

---

🎀 DEPENDENCIES 🎀

Test::More, Test::Exception, IPC::Run3, File::Basename, File::Spec

The squad. The whole squad. 👑

---

💀 BUGS AND LIMITATIONS 💀

No bugs have been reported.

(Translation: zero bugs reported, which is either flawless code or everyone's too shy. We don't know. We simply don't know. 🙈)

---

⭐ AUTHOR ⭐

sunnavy <sunnavy@bestpractical.com>

---

👑 LICENCE AND COPYRIGHT 👑

Copyright 2009-2013 Best Practical Solutions.

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

---

okay bestie that's the whole page, go forth and test your scripts, you absolute legend 🫶✨

this page came to you courtesy of the User Contributed Perl Documentation for Test::...pt::Run(3pm), generated by perl v5.36.0 on 2022-12-08 — mwah, no notes 💅🌈