Test::Script(3)

📦
version 1.31 · 12 versions
, in alpine 3.23

🎀 Test::Script — the Perl one, section 3, from the User Contributed Perl Documentation corner of the man pages 🎀

okay so bestie, buckle in — this is Test::Script, and it's lowkey the most "i just want my script tests to work everywhere" module ever. 💅

✨ NAME ✨

Test::Script — basic cross-platform tests for scripts. that's it, that's the whole vibe. 🦋

🌸 VERSION 🌸

version 1.31 — yes she's got receipts.

⭐ SYNOPSIS ⭐

like, here's the whole thing in action:

 use Test2::V0;
 use Test::Script;

 script_compiles('script/myscript.pl');
 script_runs(['script/myscript.pl', '--my-argument']);

 program_runs(['ls', '/dev']);

 done_testing;

that's literally it. that's the group chat. 🫶

💖 DESCRIPTION 💖

so the whole intent of this module (their words, i'm just hyping them) is to give you a series of basic tests covering 80% of the testing you'll actually need for scripts living in the script path (or bin, which is also super commonly used, iykyk) of your Perl distribution.

it also hands you similar functions for testing programs that are not Perl scripts. slay, versatile queen. 👑

and more than that? it aims to give you all this with perfect platform-compatibility, in a way that's as unobtrusive as possible. no cap.

like — if the program works on a platform, then Test::Script should always work on that platform too. anything less than 100% is considered unacceptable. not 99%. not "close enough". 100. periodt. 💀

by doing all that, the hope is Test::Script can become a module you can safely make a dependency of all your modules, without that scary risk of your module refusing to install on some platform just because of the dependency. no more install drama, we're done with that era. 🙈

and when there's a clash between "i want more functionality" and "i want to keep platform safety"? this module errs on the side of platform safety. safety first, always. 🧚

🔥 FUNCTIONS 🔥

script_compiles — [version 1.05] 🦋

 script_compiles( $script, $test_name );

so the script_compiles test calls the script with perl -c script.pl, and then checks that it returns without error. basically a syntax vibe check. ✨

the path you pass it should be a relative Unix-format script name. this gets localised when running perl -c, and if the test fails, the local name that was used gets shown in the diagnostic output. so you're never left guessing which path it was actually on about. 💖

also note — the test is run with the same perl interpreter that's running the test script, not with the default system perl. and yeah, that's shown in the diagnostic output on failure too. transparency icon. 🌈

script_runs — [version 1.05] 🎀

 script_runs( $script, $test_name );
 script_runs( \@script_and_arguments, $test_name );
 script_runs( $script, \%options, $test_name );
 script_runs( \@script_and_arguments, \%options, $test_name );

the script_runs test executes the script with perl script.pl and checks that it returns success. that's the whole job. 💅

the path you pass should be a relative unix-format script name. it gets localised when running perl -c, and if the test fails, the local name used is shown in the diagnostic output. 👀

the test is run with the same perl interpreter that's running the test script (not the default system perl), and this also shows up in the diagnostic output on failure.

[version 1.09] — you can pass in options as a hash as the second argument (as of version 1.09). and the options are:

  • exit — the expected exit value. default is whatever indicates success on your platform (usually 0). 💚
  • interpreter_options — [version 1.25] — an array reference of Perl options to pass to the interpreter. stuff like -w or -x can go this way. it may be either a single string or an array reference. 🧚
  • signal — the expected signal. default is 0. use with care! this may not be portable, and it's known not to work on Windows. you've been warned, bestie. ⚠️
  • stdin — the input passed into the script via stdin. the value may be one of:
    • simple scalar — is considered to be a filename. 🍓
    • scalar reference — in which case the input will be drawn from the data contained in the referenced scalar.

the behavior for any other types is undefined (the current implementation uses Capture::Tiny). any already opened stdin will be closed. 😭

  • stdout — where to send the standard output to. if you use this option, then the behavior of the script_stdout_ functions below are undefined. the value may be one of:
    • simple scalar — is considered to be a filename. 🍓
    • scalar reference — in which case the standard output will be placed into the referenced scalar.

the behavior for any other types is undefined (the current implementation uses Capture::Tiny).

  • stderr — same as stdout above, except for stderr. 💜

script_fails — [ version 1.28 ] 💀

 script_fails $script, { exit => $expected_exit }, $test_name );
 script_fails $script, \%options, $test_name;

script_runs may be invoked as script_fails. the exit option is mandatory when you use it this way. 🚨

since Perl 5.12, die usually returns 255, but it doesn't promise to do so. fatal errors like divide by 0 also return 255 often, so it's not the best error code for a trapped exception. script_runs needs an exit code it considers success — so use warn; exit; instead of die. noted, bestie. 📝

script_stdout_is — [version 1.09] 🌸

 script_stdout_is $expected_stdout, $test_name;

tests if the output to stdout from the previous script_runs matches the expected value exactly. exact match only, no wiggle room. 💅

script_stdout_isnt — [version 1.09] 🌸

 script_stdout_is $expected_stdout, $test_name;

tests if the output to stdout from the previous script_runs does NOT match the expected value exactly. the hater version of the one above. 😌

script_stdout_like — [version 1.09] 🌸

 script_stdout_like $regex, $test_name;

tests if the output to stdout from the previous script_runs matches the regular expression. regex girlies rise. 🔥

script_stdout_unlike — [version 1.09] 🌸

 script_stdout_unlike $regex, $test_name;

tests if the output to stdout from the previous script_runs does NOT match the regular expression.

script_stderr_is — [version 1.09] 🦋

 script_stderr_is $expected_stderr, $test_name;

tests if the output to stderr from the previous script_runs matches the expected value exactly.

script_stderr_isnt — [version 1.09] 🦋

 script_stderr_is $expected_stderr, $test_name;

tests if the output to stderr from the previous script_runs does NOT match the expected value exactly.

script_stderr_like — [version 1.09] 🦋

 script_stderr_like $regex, $test_name;

tests if the output to stderr from the previous script_runs matches the regular expression.

script_stderr_unlike — [version 1.09] 🦋

 script_stderr_unlike $regex, $test_name;

tests if the output to stderr from the previous script_runs does NOT match the regular expression.

program_runs — [version 1.26] 👑

 program_runs( $program, $test_name );
 program_runs( \@program_and_arguments, $test_name );
 program_runs( $program, \%options, $test_name );
 program_runs( \@program_and_arguments, \%options, $test_name );

the program_runs test executes the given program and checks that it returns success. this one works like script_runs except:

  • the path $program or @program_and_arguments is passed as-is to [system()](https://perldoc.perl.org/functions/system.html). this means program_runs can test any program, not just Perl scripts. iconic, honestly. ✨
  • the %options do not support the interpreter_options key. nope, not a thing here. 🙅

see File::Spec or Path::Class for routines useful in building pathnames in a cross-platform way. 🛠️

program_fails — [ version 1.28 ] 💀

 program_fails $program, { exit => $expected_exit }, $test_name;
 program_fails $program, \%options, $test_name;

program_runs may be invoked as program_fails. program_fails needs to know the expected exit value, so exit becomes a required option. mandatory. non-negotiable. 💅

program_stdout_is — [version 1.26] 🌈

 program_stdout_is $expected_stdout, $test_name;

tests if the output to stdout from the previous program_runs matches the expected value exactly.

program_stdout_isnt — [version 1.26] 🌈

 program_stdout_isnt $expected_stdout, $test_name;

tests if the output to stdout from the previous program_runs does NOT match the expected value exactly.

program_stdout_like — [version 1.26] 🌈

 program_stdout_like $regex, $test_name;

tests if the output to stdout from the previous program_runs matches the regular expression.

program_stdout_unlike — [version 1.26] 🌈

 program_stdout_unlike $regex, $test_name;

tests if the output to stdout from the previous program_runs does NOT match the regular expression.

program_stderr_is — [version 1.26] ⭐

 program_stderr_is $expected_stderr, $test_name;

tests if the output to stderr from the previous program_runs matches the expected value exactly.

program_stderr_isnt — [version 1.26] ⭐

 program_stderr_isnt $expected_stderr, $test_name;

tests if the output to stderr from the previous program_runs does NOT match the expected value exactly.

program_stderr_like — [version 1.26] ⭐

 program_stderr_like $regex, $test_name;

tests if the output to stderr from the previous program_runs matches the regular expression.

program_stderr_unlike — [version 1.26] ⭐

 program_stderr_unlike $regex, $test_name;

tests if the output to stderr from the previous program_runs does NOT match the regular expression.

⚠️ CAVEATS ⚠️

this module is fully supported back to Perl 5.8.1. old-school legend. 🫶

the STDIN handle will be closed when using script_runs with the stdin option. an older version used IPC::Run3, which attempted to save STDIN, but apparently that can't be done consistently or portably. we now use Capture::Tiny instead and explicitly do not support saving STDIN handles. so like, don't come for her about it. 😭

💜 SEE ALSO 💜

  • Test::Script::Run
  • Test2::Suite

🧚 AUTHOR 🧚

  • original author: Adam Kennedy
  • current maintainer: Graham Ollis <plicease@cpan.org>
  • contributors:
    • Brendan Byrd
    • Chris White <cxw@cpan.org>
    • **John Karr (BRAINBUZ)`

this software is copyright (c) 2006-2024 by Adam Kennedy.

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

and that's the whole page, bestie — brought to you by perl v5.42.0, dated 2025-08-13, aka the Test::Script(3) era. go forth and test your scripts cross-platform, mwah 💋🌸🦋

📦 where this page comes from