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.29
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        program_runs(['ls', '/dev']);
19
20        done_testing;
21

DESCRIPTION

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

FUNCTIONS

45   script_compiles
46       [version 1.05]
47
48        script_compiles( $script, $test_name );
49
50       The "script_compiles" test calls the script with "perl -c script.pl",
51       and checks that it returns without error.
52
53       The path it should be passed is a relative Unix-format script name.
54       This will be localised when running "perl -c" and if the test fails the
55       local name used will be shown in the diagnostic output.
56
57       Note also that the test will be run with the same perl interpreter that
58       is running the test script (and not with the default system perl). This
59       will also be shown in the diagnostic output on failure.
60
61   script_runs
62       [version 1.05]
63
64        script_runs( $script, $test_name );
65        script_runs( \@script_and_arguments, $test_name );
66        script_runs( $script, \%options, $test_name );
67        script_runs( \@script_and_arguments, \%options, $test_name );
68
69       The "script_runs" test executes the script with "perl script.pl" and
70       checks that it returns success.
71
72       The path it should be passed is a relative unix-format script name.
73       This will be localised when running "perl -c" and if the test fails the
74       local name used will be shown in the diagnostic output.
75
76       The test will be run with the same perl interpreter that is running the
77       test script (and not with the default system perl). This will also be
78       shown in the diagnostic output on failure.
79
80       [version 1.09]
81
82       You may pass in options as a hash as the second argument (as of version
83       1.09).
84
85       exit
86           The expected exit value.  The default is to use whatever indicates
87           success on your platform (usually 0).
88
89       interpreter_options
90           [version 1.25]
91
92           Array reference of Perl options to be passed to the interpreter.
93           Things like "-w" or "-x" can be passed this way.  This may be
94           either a single string or an array reference.
95
96       signal
97           The expected signal.  The default is 0.  Use with care!  This may
98           not be portable, and is known not to work on Windows.
99
100       stdin
101           The input to be passed into the script via stdin.  The value may be
102           one of
103
104           simple scalar
105               Is considered to be a filename.
106
107           scalar reference
108               In which case the input will be drawn from the data contained
109               in the referenced scalar.
110
111           The behavior for any other types is undefined (the current
112           implementation uses Capture::Tiny).  Any already opened stdin will
113           be closed.
114
115       stdout
116           Where to send the standard output to.  If you use this option, then
117           the the behavior of the "script_stdout_" functions below are
118           undefined.  The value may be one of
119
120           simple scalar
121               Is considered to be a filename.
122
123           scalar reference
124
125           In which case the standard output will be places into the
126           referenced scalar
127
128           The behavior for any other types is undefined (the current
129           implementation uses Capture::Tiny).
130
131       stderr
132           Same as "stdout" above, except for stderr.
133
134   script_fails
135       [ version 1.28 ]
136
137        script_fails $script, { exit => $expected_exit }, $test_name );
138        script_fails $script, \%options, $test_name;
139
140       "script_runs" may be invoked as "script_fails". The exit option is
141       mandatory when used this way. Since Perl 5.12, "die" usually returns
142       255, but does not promise to do so. Fatal errors like divide by 0 also
143       return 255 often so it is not the best error code for a trapped
144       exception.  script_runs needs an exit code it considers success, use
145       "warn; exit;" instead of die.
146
147   script_stdout_is
148       [version 1.09]
149
150        script_stdout_is $expected_stdout, $test_name;
151
152       Tests if the output to stdout from the previous "script_runs" matches
153       the expected value exactly.
154
155   script_stdout_isnt
156       [version 1.09]
157
158        script_stdout_is $expected_stdout, $test_name;
159
160       Tests if the output to stdout from the previous "script_runs" does NOT
161       match the expected value exactly.
162
163   script_stdout_like
164       [version 1.09]
165
166        script_stdout_like $regex, $test_name;
167
168       Tests if the output to stdout from the previous "script_runs" matches
169       the regular expression.
170
171   script_stdout_unlike
172       [version 1.09]
173
174        script_stdout_unlike $regex, $test_name;
175
176       Tests if the output to stdout from the previous "script_runs" does NOT
177       match the regular expression.
178
179   script_stderr_is
180       [version 1.09]
181
182        script_stderr_is $expected_stderr, $test_name;
183
184       Tests if the output to stderr from the previous "script_runs" matches
185       the expected value exactly.
186
187   script_stderr_isnt
188       [version 1.09]
189
190        script_stderr_is $expected_stderr, $test_name;
191
192       Tests if the output to stderr from the previous "script_runs" does NOT
193       match the expected value exactly.
194
195   script_stderr_like
196       [version 1.09]
197
198        script_stderr_like $regex, $test_name;
199
200       Tests if the output to stderr from the previous "script_runs" matches
201       the regular expression.
202
203   script_stderr_unlike
204       [version 1.09]
205
206        script_stderr_unlike $regex, $test_name;
207
208       Tests if the output to stderr from the previous "script_runs" does NOT
209       match the regular expression.
210
211   program_runs
212       [version 1.26]
213
214        program_runs( $program, $test_name );
215        program_runs( \@program_and_arguments, $test_name );
216        program_runs( $program, \%options, $test_name );
217        program_runs( \@program_and_arguments, \%options, $test_name );
218
219       The "program_runs" test executes the given program and checks that it
220       returns success.  This function works like "script_runs" except:
221
222       •   The path $program or @program_and_arguments is passed as-is to
223           system() <https://perldoc.perl.org/functions/system.html>.  This
224           means "program_runs" can test any program, not just Perl scripts.
225
226       •   The %options do not support the "interpreter_options" key.
227
228       See File::Spec or Path::Class for routines useful in building pathnames
229       in a cross-platform way.
230
231   program_fails
232       [ version 1.28 ]
233
234        program_fails $program, { exit => $expected_exit }, $test_name;
235        program_fails $program, \%options, $test_name;
236
237       "program_runs" may be invoked as "program_fails". "program_fails" needs
238       to know the expected exit value, so exit becomes a required option.
239
240   program_stdout_is
241       [version 1.26]
242
243        program_stdout_is $expected_stdout, $test_name;
244
245       Tests if the output to stdout from the previous "program_runs" matches
246       the expected value exactly.
247
248   program_stdout_isnt
249       [version 1.26]
250
251        program_stdout_is $expected_stdout, $test_name;
252
253       Tests if the output to stdout from the previous "program_runs" does NOT
254       match the expected value exactly.
255
256   program_stdout_like
257       [version 1.26]
258
259        program_stdout_like $regex, $test_name;
260
261       Tests if the output to stdout from the previous "program_runs" matches
262       the regular expression.
263
264   program_stdout_unlike
265       [version 1.26]
266
267        program_stdout_unlike $regex, $test_name;
268
269       Tests if the output to stdout from the previous "program_runs" does NOT
270       match the regular expression.
271
272   program_stderr_is
273       [version 1.26]
274
275        program_stderr_is $expected_stderr, $test_name;
276
277       Tests if the output to stderr from the previous "program_runs" matches
278       the expected value exactly.
279
280   program_stderr_isnt
281       [version 1.26]
282
283        program_stderr_is $expected_stderr, $test_name;
284
285       Tests if the output to stderr from the previous "program_runs" does NOT
286       match the expected value exactly.
287
288   program_stderr_like
289       [version 1.26]
290
291        program_stderr_like $regex, $test_name;
292
293       Tests if the output to stderr from the previous "program_runs" matches
294       the regular expression.
295
296   program_stderr_unlike
297       [version 1.26]
298
299        program_stderr_unlike $regex, $test_name;
300
301       Tests if the output to stderr from the previous "program_runs" does NOT
302       match the regular expression.
303

CAVEATS

305       This module is fully supported back to Perl 5.8.1.
306
307       The STDIN handle will be closed when using script_runs with the stdin
308       option.  An older version used IPC::Run3, which attempted to save
309       STDIN, but apparently this cannot be done consistently or portably.  We
310       now use Capture::Tiny instead and explicitly do not support saving
311       STDIN handles.
312

AUTHOR

317       Original author: Adam Kennedy
318
319       Current maintainer: Graham Ollis <plicease@cpan.org>
320
321       Contributors:
322
323       Brendan Byrd
324
325       Chris White <cxw@cpan.org>
326
327       John Karr (BRAINBUZ)
328

COPYRIGHT AND LICENSE

330       This software is copyright (c) 2006-2021 by Adam Kennedy.
331
332       This is free software; you can redistribute it and/or modify it under
333       the same terms as the Perl 5 programming language system itself.
334
335
336
337perl v5.38.0                      2023-07-21                   Test::Script(3)