.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Test::Script::Run 3pm"
.TH Test::Script::Run 3pm "2018-01-29" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Script::Run \- test scripts with run
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    use Test::Script::Run;
\&    # customized names of bin dirs, default is qw/bin sbin script ./;
\&    @Test::Script::Run::BIN_DIRS = qw/bin/;
\&    run_ok( \*(Aqapp_name\*(Aq, [ app\*(Aqs args ], \*(Aqyou_app runs ok\*(Aq );
\&    my ( $return, $stdout, $stderr ) = run_script( \*(Aqapp_name\*(Aq, [ app\*(Aqs args ] );
\&    run_output_matches(
\&        \*(Aqapp_name\*(Aq, [app\*(Aqs args],
\&        [ \*(Aqout line 1\*(Aq, \*(Aqout line 2\*(Aq ],
\&        [ \*(Aqerr line 1\*(Aq, \*(Aqerr line 2\*(Aq ],
\&        \*(Aqrun_output_matches\*(Aq
\&    );
\&    run_output_matches_unordered(
\&        \*(Aqapp_name\*(Aq, [ app\*(Aqs args ],
\&        [ \*(Aqout line 2\*(Aq, \*(Aqout line 1\*(Aq ],
\&        [ \*(Aqerr line 2\*(Aq, \*(Aqerr line 1\*(Aq ],
\&        \*(Aqrun_output_matches_unordered\*(Aq
\&    );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module exports some subs to help test and run scripts in your dist's 
script directory( bin, sbin, script, etc ), if the script path is not absolute.
.PP
Nearly all the essential code is stolen from Prophet::Test, we think subs like
those should live below \f(CW\*(C`Test::\*(C'\fR namespace, that's why we packed them and
created this module.
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
.ie n .SS "run_script($script, $args, $stdout, $stderr)"
.el .SS "run_script($script, \f(CW$args\fP, \f(CW$stdout\fP, \f(CW$stderr\fP)"
.IX Subsection "run_script($script, $args, $stdout, $stderr)"
Runs the script \f(CW$script\fR as a perl script, setting the \f(CW@INC\fR to the same as
our caller.
.PP
\&\f(CW$script\fR is the name of the script to be run (such as 'prophet'). \f(CW$args\fR is a
reference to an array of arguments to pass to the script. \f(CW$stdout\fR and \f(CW$stderr\fR
are both optional; if passed in, they will be passed to IPC::Run3's run3
subroutine as its \f(CW$stdout\fR and \f(CW$stderr\fR args.  Otherwise, this subroutine will
create scalar references to pass to run3 instead (which are treated as strings
for \s-1STDOUT/STDERR\s0 to be written to).
.PP
Returns run3's return value and, if no \f(CW$stdout\fR and \f(CW$stderr\fR were passed in, the
\&\s-1STDOUT\s0 and \s-1STDERR\s0 of the script that was run.
.ie n .SS "run_ok($script, $args, $msg)"
.el .SS "run_ok($script, \f(CW$args\fP, \f(CW$msg\fP)"
.IX Subsection "run_ok($script, $args, $msg)"
Runs the script, checking that it didn't error out.
.PP
\&\f(CW$script\fR is the name of the script to be run (e.g. 'prophet'). \f(CW$args\fR
is an optional reference to an array of arguments to pass to the
script when it is run. \f(CW$msg\fR is an optional message to print with
the test. If \f(CW$args\fR is not specified, you can still pass in
a \f(CW$msg\fR.
.PP
Returns nothing of interest.
.ie n .SS "run_not_ok($script, $args, $msg)"
.el .SS "run_not_ok($script, \f(CW$args\fP, \f(CW$msg\fP)"
.IX Subsection "run_not_ok($script, $args, $msg)"
opposite of run_ok
.ie n .SS "get_perl_cmd($script, @ARGS)"
.el .SS "get_perl_cmd($script, \f(CW@ARGS\fP)"
.IX Subsection "get_perl_cmd($script, @ARGS)"
Returns a list suitable for passing to \f(CW\*(C`system\*(C'\fR, \f(CW\*(C`exec\*(C'\fR, etc. If you pass
\&\f(CW$script\fR then we will search upwards for it in \f(CW@BIN_DIRS\fR
.ie n .SS "is_script_output($scriptname \e@args, \e@stdout_match, \e@stderr_match, $msg)"
.el .SS "is_script_output($scriptname \e@args, \e@stdout_match, \e@stderr_match, \f(CW$msg\fP)"
.IX Subsection "is_script_output($scriptname @args, @stdout_match, @stderr_match, $msg)"
Runs \f(CW$scriptname\fR, checking to see that its output matches.
.PP
\&\f(CW$args\fR is an array reference of args to pass to the script. \f(CW$stdout_match\fR and
\&\f(CW$stderr_match\fR are references to arrays of expected lines. \f(CW$msg\fR is a string
message to display with the test. \f(CW$stderr_match\fR and \f(CW$msg\fR are optional. (As is
\&\f(CW$stdout_match\fR if for some reason you expect your script to have no output at
all. But that would be silly, wouldn't it?)
.PP
Allows regex matches as well as string equality (lines in \f(CW$stdout_match\fR and
\&\f(CW$stderr_match\fR may be Regexp objects).
.ie n .SS "run_output_matches($script, $args, $exp_stdout, $exp_stderr, $msg)"
.el .SS "run_output_matches($script, \f(CW$args\fP, \f(CW$exp_stdout\fP, \f(CW$exp_stderr\fP, \f(CW$msg\fP)"
.IX Subsection "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.
.ie n .SS "run_output_matches_unordered($script, $args, $exp_stdout, $exp_stderr, $msg)"
.el .SS "run_output_matches_unordered($script, \f(CW$args\fP, \f(CW$exp_stdout\fP, \f(CW$exp_stderr\fP, \f(CW$msg\fP)"
.IX Subsection "run_output_matches_unordered($script, $args, $exp_stdout, $exp_stderr, $msg)"
This subroutine has exactly the same functionality as run_output_matches, but
doesn't impose a line ordering when comparing the expected and received
outputs.
.SS "last_script_stdout"
.IX Subsection "last_script_stdout"
return last script's stdout
.SS "last_script_stderr"
.IX Subsection "last_script_stderr"
return last script's stderr
.SS "last_script_exit_code"
.IX Subsection "last_script_exit_code"
return last script's exit code
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Test::More, Test::Exception, IPC::Run3, File::Basename, File::Spec
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.SH "AUTHOR"
.IX Header "AUTHOR"
sunnavy <sunnavy@bestpractical.com>
.SH "LICENCE AND COPYRIGHT"
.IX Header "LICENCE AND COPYRIGHT"
Copyright 2009\-2013 Best Practical Solutions.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.