Test::Script(3pm)

1Test::Script(3)       User Contributed Perl Documentation      Test::Script(3)
2
3
4

NAME

6       Test::Script - Basic cross-platform tests for scripts
7

VERSION

9       version 1.25
10

SYNOPSIS

12        use Test2::V0;
13        use Test::Script;
14
15        script_compiles('script/myscript.pl');
16        script_runs(['script/myscript.pl', '--my-argument']);
17
18        done_testing;
19

DESCRIPTION

21       The intent of this module is to provide a series of basic tests for 80%
22       of the testing you will need to do for scripts in the script (or bin as
23       is also commonly used) paths of your Perl distribution.
24
25       Further, it aims to provide this functionality with perfect platform-
26       compatibility, and in a way that is as unobtrusive as possible.
27
28       That is, if the program works on a platform, then Test::Script should
29       always work on that platform as well. Anything less than 100% is
30       considered unacceptable.
31
32       In doing so, it is hoped that Test::Script can become a module that you
33       can safely make a dependency of all your modules, without risking that
34       your module won't on some platform because of the dependency.
35
36       Where a clash exists between wanting more functionality and maintaining
37       platform safety, this module will err on the side of platform safety.
38

FUNCTIONS

40   script_compiles
41        script_compiles( $script, $test_name );
42
43       The "script_compiles" test calls the script with "perl -c script.pl",
44       and checks that it returns without error.
45
46       The path it should be passed is a relative Unix-format script name.
47       This will be localised when running "perl -c" and if the test fails the
48       local name used will be shown in the diagnostic output.
49
50       Note also that the test will be run with the same perl interpreter that
51       is running the test script (and not with the default system perl). This
52       will also be shown in the diagnostic output on failure.
53
54   script_runs
55        script_runs( $script, $test_name );
56        script_runs( \@script_and_arguments, $test_name );
57        script_runs( $script, \%options, $test_name );
58        script_runs( \@script_and_arguments, \%options, $test_name );
59
60       The "script_runs" test executes the script with "perl script.pl" and
61       checks that it returns success.
62
63       The path it should be passed is a relative unix-format script name.
64       This will be localised when running "perl -c" and if the test fails the
65       local name used will be shown in the diagnostic output.
66
67       The test will be run with the same perl interpreter that is running the
68       test script (and not with the default system perl). This will also be
69       shown in the diagnostic output on failure.
70
71       You may pass in options as a hash as the second argument.
72
73       exit
74           The expected exit value.  The default is to use whatever indicates
75           success on your platform (usually 0).
76
77       interpreter_options
78           Array reference of Perl options to be passed to the interpreter.
79           Things like "-w" or "-x" can be passed this way.  This may be
80           either a single string or an array reference.
81
82       signal
83           The expected signal.  The default is 0.  Use with care!  This may
84           not be portable, and is known not to work on Windows.
85
86       stdin
87           The input to be passed into the script via stdin.  The value may be
88           one of
89
90           simple scalar
91               Is considered to be a filename.
92
93           scalar reference
94               In which case the input will be drawn from the data contained
95               in the referenced scalar.
96
97           The behavior for any other types is undefined (the current
98           implementation uses Capture::Tiny).  Any already opened stdin will
99           be closed.
100
101       stdout
102           Where to send the standard output to.  If you use this option, then
103           the the behavior of the "script_stdout_" functions below are
104           undefined.  The value may be one of
105
106           simple scalar
107               Is considered to be a filename.
108
109           scalar reference
110
111           In which case the standard output will be places into the
112           referenced scalar
113
114           The behavior for any other types is undefined (the current
115           implementation uses Capture::Tiny).
116
117       stderr
118           Same as "stdout" above, except for stderr.
119
120   script_stdout_is
121        script_stdout_is $expected_stdout, $test_name;
122
123       Tests if the output to stdout from the previous "script_runs" matches
124       the expected value exactly.
125
126   script_stdout_isnt
127        script_stdout_is $expected_stdout, $test_name;
128
129       Tests if the output to stdout from the previous "script_runs" does NOT
130       match the expected value exactly.
131
132   script_stdout_like
133        script_stdout_like $regex, $test_name;
134
135       Tests if the output to stdout from the previous "script_runs" matches
136       the regular expression.
137
138   script_stdout_unlike
139        script_stdout_unlike $regex, $test_name;
140
141       Tests if the output to stdout from the previous "script_runs" does NOT
142       match the regular expression.
143
144   script_stderr_is
145        script_stderr_is $expected_stderr, $test_name;
146
147       Tests if the output to stderr from the previous "script_runs" matches
148       the expected value exactly.
149
150   script_stderr_isnt
151        script_stderr_is $expected_stderr, $test_name;
152
153       Tests if the output to stderr from the previous "script_runs" does NOT
154       match the expected value exactly.
155
156   script_stderr_like
157        script_stderr_like $regex, $test_name;
158
159       Tests if the output to stderr from the previous "script_runs" matches
160       the regular expression.
161
162   script_stderr_unlike
163        script_stderr_unlike $regex, $test_name;
164
165       Tests if the output to stderr from the previous "script_runs" does NOT
166       match the regular expression.
167

CAVEATS

169       This module is fully supported back to Perl 5.8.1.  In the near future,
170       support for the older pre-Test2 Test::Builer will be dropped.
171
172       The STDIN handle will be closed when using script_runs with the stdin
173       option.  An older version used IPC::Run3, which attempted to save
174       STDIN, but apparently this cannot be done consistently or portably.  We
175       now use Capture::Tiny instead and explicitly do not support saving
176       STDIN handles.
177

AUTHOR

182       Original author: Adam Kennedy
183
184       Current maintainer: Graham Ollis <plicease@cpan.org>
185
186       Contributors:
187
188       Brendan Byrd
189

COPYRIGHT AND LICENSE

191       This software is copyright (c) 2017 by Adam Kennedy.
192
193       This is free software; you can redistribute it and/or modify it under
194       the same terms as the Perl 5 programming language system itself.
195
196
197
198perl v5.28.0                      2018-09-27                   Test::Script(3)