1Test::Script(3) User Contributed Perl Documentation Test::Script(3)
2
3
4
6 Test::Script - Basic cross-platform tests for scripts
7
9 version 1.25
10
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
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
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
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
179 Test::Script::Run, Test2::Suite
180
182 Original author: Adam Kennedy
183
184 Current maintainer: Graham Ollis <plicease@cpan.org>
185
186 Contributors:
187
188 Brendan Byrd
189
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.30.0 2019-07-26 Test::Script(3)