1NAME
2
3 Test::Script - Basic cross-platform tests for scripts
4
5VERSION
6
7 version 1.29
8
9SYNOPSIS
10
11 use Test2::V0;
12 use Test::Script;
13
14 script_compiles('script/myscript.pl');
15 script_runs(['script/myscript.pl', '--my-argument']);
16
17 program_runs(['ls', '/dev']);
18
19 done_testing;
20
21DESCRIPTION
22
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
31 platform-compatibility, and in a way that is as unobtrusive as
32 possible.
33
34 That is, if the program works on a platform, then Test::Script should
35 always work on that platform as well. Anything less than 100% is
36 considered unacceptable.
37
38 In doing so, it is hoped that Test::Script can become a module that you
39 can safely make a dependency of all your modules, without risking that
40 your module won't on some platform because of the dependency.
41
42 Where a clash exists between wanting more functionality and maintaining
43 platform safety, this module will err on the side of platform safety.
44
45FUNCTIONS
46
47 script_compiles
48
49 [version 1.05]
50
51 script_compiles( $script, $test_name );
52
53 The "script_compiles" test calls the script with "perl -c script.pl",
54 and checks that it returns without error.
55
56 The path it should be passed is a relative Unix-format script name.
57 This will be localised when running perl -c and if the test fails the
58 local name used will be shown in the diagnostic output.
59
60 Note also that the test will be run with the same perl interpreter that
61 is running the test script (and not with the default system perl). This
62 will also be shown in the diagnostic output on failure.
63
64 script_runs
65
66 [version 1.05]
67
68 script_runs( $script, $test_name );
69 script_runs( \@script_and_arguments, $test_name );
70 script_runs( $script, \%options, $test_name );
71 script_runs( \@script_and_arguments, \%options, $test_name );
72
73 The "script_runs" test executes the script with "perl script.pl" and
74 checks that it returns success.
75
76 The path it should be passed is a relative unix-format script name.
77 This will be localised when running perl -c and if the test fails the
78 local name used will be shown in the diagnostic output.
79
80 The test will be run with the same perl interpreter that is running the
81 test script (and not with the default system perl). This will also be
82 shown in the diagnostic output on failure.
83
84 [version 1.09]
85
86 You may pass in options as a hash as the second argument (as of version
87 1.09).
88
89 exit
90
91 The expected exit value. The default is to use whatever indicates
92 success on your platform (usually 0).
93
94 interpreter_options
95
96 [version 1.25]
97
98 Array reference of Perl options to be passed to the interpreter.
99 Things like -w or -x can be passed this way. This may be either a
100 single string or an array reference.
101
102 signal
103
104 The expected signal. The default is 0. Use with care! This may not be
105 portable, and is known not to work on Windows.
106
107 stdin
108
109 The input to be passed into the script via stdin. The value may be
110 one of
111
112 simple scalar
113
114 Is considered to be a filename.
115
116 scalar reference
117
118 In which case the input will be drawn from the data contained in
119 the referenced scalar.
120
121 The behavior for any other types is undefined (the current
122 implementation uses Capture::Tiny). Any already opened stdin will be
123 closed.
124
125 stdout
126
127 Where to send the standard output to. If you use this option, then
128 the the behavior of the script_stdout_ functions below are undefined.
129 The value may be one of
130
131 simple scalar
132
133 Is considered to be a filename.
134
135 scalar reference
136
137 In which case the standard output will be places into the referenced
138 scalar
139
140 The behavior for any other types is undefined (the current
141 implementation uses Capture::Tiny).
142
143 stderr
144
145 Same as stdout above, except for stderr.
146
147 script_fails
148
149 [ version 1.28 ]
150
151 script_fails $script, { exit => $expected_exit }, $test_name );
152 script_fails $script, \%options, $test_name;
153
154 "script_runs" may be invoked as "script_fails". The exit option is
155 mandatory when used this way. Since Perl 5.12, die usually returns 255,
156 but does not promise to do so. Fatal errors like divide by 0 also
157 return 255 often so it is not the best error code for a trapped
158 exception. script_runs needs an exit code it considers success, use
159 warn; exit; instead of die.
160
161 script_stdout_is
162
163 [version 1.09]
164
165 script_stdout_is $expected_stdout, $test_name;
166
167 Tests if the output to stdout from the previous "script_runs" matches
168 the expected value exactly.
169
170 script_stdout_isnt
171
172 [version 1.09]
173
174 script_stdout_is $expected_stdout, $test_name;
175
176 Tests if the output to stdout from the previous "script_runs" does NOT
177 match the expected value exactly.
178
179 script_stdout_like
180
181 [version 1.09]
182
183 script_stdout_like $regex, $test_name;
184
185 Tests if the output to stdout from the previous "script_runs" matches
186 the regular expression.
187
188 script_stdout_unlike
189
190 [version 1.09]
191
192 script_stdout_unlike $regex, $test_name;
193
194 Tests if the output to stdout from the previous "script_runs" does NOT
195 match the regular expression.
196
197 script_stderr_is
198
199 [version 1.09]
200
201 script_stderr_is $expected_stderr, $test_name;
202
203 Tests if the output to stderr from the previous "script_runs" matches
204 the expected value exactly.
205
206 script_stderr_isnt
207
208 [version 1.09]
209
210 script_stderr_is $expected_stderr, $test_name;
211
212 Tests if the output to stderr from the previous "script_runs" does NOT
213 match the expected value exactly.
214
215 script_stderr_like
216
217 [version 1.09]
218
219 script_stderr_like $regex, $test_name;
220
221 Tests if the output to stderr from the previous "script_runs" matches
222 the regular expression.
223
224 script_stderr_unlike
225
226 [version 1.09]
227
228 script_stderr_unlike $regex, $test_name;
229
230 Tests if the output to stderr from the previous "script_runs" does NOT
231 match the regular expression.
232
233 program_runs
234
235 [version 1.26]
236
237 program_runs( $program, $test_name );
238 program_runs( \@program_and_arguments, $test_name );
239 program_runs( $program, \%options, $test_name );
240 program_runs( \@program_and_arguments, \%options, $test_name );
241
242 The "program_runs" test executes the given program and checks that it
243 returns success. This function works like "script_runs" except:
244
245 * The path $program or @program_and_arguments is passed as-is to
246 system() <https://perldoc.perl.org/functions/system.html>. This means
247 program_runs can test any program, not just Perl scripts.
248
249 * The %options do not support the interpreter_options key.
250
251 See File::Spec or Path::Class for routines useful in building pathnames
252 in a cross-platform way.
253
254 program_fails
255
256 [ version 1.28 ]
257
258 program_fails $program, { exit => $expected_exit }, $test_name;
259 program_fails $program, \%options, $test_name;
260
261 "program_runs" may be invoked as "program_fails". "program_fails" needs
262 to know the expected exit value, so exit becomes a required option.
263
264 program_stdout_is
265
266 [version 1.26]
267
268 program_stdout_is $expected_stdout, $test_name;
269
270 Tests if the output to stdout from the previous "program_runs" matches
271 the expected value exactly.
272
273 program_stdout_isnt
274
275 [version 1.26]
276
277 program_stdout_is $expected_stdout, $test_name;
278
279 Tests if the output to stdout from the previous "program_runs" does NOT
280 match the expected value exactly.
281
282 program_stdout_like
283
284 [version 1.26]
285
286 program_stdout_like $regex, $test_name;
287
288 Tests if the output to stdout from the previous "program_runs" matches
289 the regular expression.
290
291 program_stdout_unlike
292
293 [version 1.26]
294
295 program_stdout_unlike $regex, $test_name;
296
297 Tests if the output to stdout from the previous "program_runs" does NOT
298 match the regular expression.
299
300 program_stderr_is
301
302 [version 1.26]
303
304 program_stderr_is $expected_stderr, $test_name;
305
306 Tests if the output to stderr from the previous "program_runs" matches
307 the expected value exactly.
308
309 program_stderr_isnt
310
311 [version 1.26]
312
313 program_stderr_is $expected_stderr, $test_name;
314
315 Tests if the output to stderr from the previous "program_runs" does NOT
316 match the expected value exactly.
317
318 program_stderr_like
319
320 [version 1.26]
321
322 program_stderr_like $regex, $test_name;
323
324 Tests if the output to stderr from the previous "program_runs" matches
325 the regular expression.
326
327 program_stderr_unlike
328
329 [version 1.26]
330
331 program_stderr_unlike $regex, $test_name;
332
333 Tests if the output to stderr from the previous "program_runs" does NOT
334 match the regular expression.
335
336CAVEATS
337
338 This module is fully supported back to Perl 5.8.1.
339
340 The STDIN handle will be closed when using script_runs with the stdin
341 option. An older version used IPC::Run3, which attempted to save STDIN,
342 but apparently this cannot be done consistently or portably. We now use
343 Capture::Tiny instead and explicitly do not support saving STDIN
344 handles.
345
346SEE ALSO
347
348 Test::Script::Run, Test2::Suite
349
350AUTHOR
351
352 Original author: Adam Kennedy
353
354 Current maintainer: Graham Ollis <plicease@cpan.org>
355
356 Contributors:
357
358 Brendan Byrd
359
360 Chris White <cxw@cpan.org>
361
362 John Karr (BRAINBUZ)
363
364COPYRIGHT AND LICENSE
365
366 This software is copyright (c) 2006-2021 by Adam Kennedy.
367
368 This is free software; you can redistribute it and/or modify it under
369 the same terms as the Perl 5 programming language system itself.
370
371