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

CAVEATS

240       This module is fully supported back to Perl 5.8.1.
241
242       The STDIN handle will be closed when using script_runs with the stdin
243       option.  An older version used IPC::Run3, which attempted to save
244       STDIN, but apparently this cannot be done consistently or portably.  We
245       now use Capture::Tiny instead and explicitly do not support saving
246       STDIN handles.
247

AUTHOR

252       Original author: Adam Kennedy
253
254       Current maintainer: Graham Ollis <plicease@cpan.org>
255
256       Contributors:
257
258       Brendan Byrd
259
260       Chris White <cxw@cpan.org>
261

COPYRIGHT AND LICENSE

263       This software is copyright (c) 2019 by Adam Kennedy.
264
265       This is free software; you can redistribute it and/or modify it under
266       the same terms as the Perl 5 programming language system itself.
267
268
269
270perl v5.30.1                      2020-01-30                   Test::Script(3)