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

CAVEATS

265       This module is fully supported back to Perl 5.8.1.
266
267       The STDIN handle will be closed when using script_runs with the stdin
268       option.  An older version used IPC::Run3, which attempted to save
269       STDIN, but apparently this cannot be done consistently or portably.  We
270       now use Capture::Tiny instead and explicitly do not support saving
271       STDIN handles.
272

AUTHOR

277       Original author: Adam Kennedy
278
279       Current maintainer: Graham Ollis <plicease@cpan.org>
280
281       Contributors:
282
283       Brendan Byrd
284
285       Chris White <cxw@cpan.org>
286

COPYRIGHT AND LICENSE

288       This software is copyright (c) 2019 by Adam Kennedy.
289
290       This is free software; you can redistribute it and/or modify it under
291       the same terms as the Perl 5 programming language system itself.
292
293
294
295perl v5.32.1                      2021-03-13                   Test::Script(3)