README 8.45 KB
Newer Older
1
NAME
2

3
    Test::Script - Basic cross-platform tests for scripts
4

5 6
VERSION

7
    version 1.26
8 9 10

SYNOPSIS

11
     use Test2::V0;
12 13
     use Test::Script;
     
14 15
     script_compiles('script/myscript.pl');
     script_runs(['script/myscript.pl', '--my-argument']);
16
     
17 18
     program_runs(['ls', '/dev']);
     
19
     done_testing;
20

21
DESCRIPTION
22

23 24 25
    The intent of this module is to provide a series of basic tests for 80%
    of the testing you will need to do for scripts in the script (or bin as
    is also commonly used) paths of your Perl distribution.
26

27 28 29
    It also provides similar functions for testing programs that are not
    Perl scripts.

30
    Further, it aims to provide this functionality with perfect
31 32
    platform-compatibility, and in a way that is as unobtrusive as
    possible.
33 34

    That is, if the program works on a platform, then Test::Script should
35 36
    always work on that platform as well. Anything less than 100% is
    considered unacceptable.
37 38

    In doing so, it is hoped that Test::Script can become a module that you
39 40
    can safely make a dependency of all your modules, without risking that
    your module won't on some platform because of the dependency.
41 42 43 44 45

    Where a clash exists between wanting more functionality and maintaining
    platform safety, this module will err on the side of platform safety.

FUNCTIONS
46 47 48 49

 script_compiles

     script_compiles( $script, $test_name );
50

51 52
    The "script_compiles" test calls the script with "perl -c script.pl",
    and checks that it returns without error.
53

54
    The path it should be passed is a relative Unix-format script name.
55 56
    This will be localised when running perl -c and if the test fails the
    local name used will be shown in the diagnostic output.
57

58 59 60 61
    Note also that the test will be run with the same perl interpreter that
    is running the test script (and not with the default system perl). This
    will also be shown in the diagnostic output on failure.

62 63 64 65 66 67
 script_runs

     script_runs( $script, $test_name );
     script_runs( \@script_and_arguments, $test_name );
     script_runs( $script, \%options, $test_name );
     script_runs( \@script_and_arguments, \%options, $test_name );
68 69 70 71

    The "script_runs" test executes the script with "perl script.pl" and
    checks that it returns success.

72 73 74
    The path it should be passed is a relative unix-format script name.
    This will be localised when running perl -c and if the test fails the
    local name used will be shown in the diagnostic output.
75 76 77 78

    The test will be run with the same perl interpreter that is running the
    test script (and not with the default system perl). This will also be
    shown in the diagnostic output on failure.
79

80
    You may pass in options as a hash as the second argument.
81

82
    exit
83

84 85
      The expected exit value. The default is to use whatever indicates
      success on your platform (usually 0).
86

87 88 89 90 91 92
    interpreter_options

      Array reference of Perl options to be passed to the interpreter.
      Things like -w or -x can be passed this way. This may be either a
      single string or an array reference.

93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112
    signal

      The expected signal. The default is 0. Use with care! This may not be
      portable, and is known not to work on Windows.

    stdin

      The input to be passed into the script via stdin. The value may be
      one of

      simple scalar

	Is considered to be a filename.

      scalar reference

	In which case the input will be drawn from the data contained in
	the referenced scalar.

      The behavior for any other types is undefined (the current
113 114
      implementation uses Capture::Tiny). Any already opened stdin will be
      closed.
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131

    stdout

      Where to send the standard output to. If you use this option, then
      the the behavior of the script_stdout_ functions below are undefined.
      The value may be one of

      simple scalar

	Is considered to be a filename.

      scalar reference

      In which case the standard output will be places into the referenced
      scalar

      The behavior for any other types is undefined (the current
132
      implementation uses Capture::Tiny).
133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192

    stderr

      Same as stdout above, except for stderr.

 script_stdout_is

     script_stdout_is $expected_stdout, $test_name;

    Tests if the output to stdout from the previous "script_runs" matches
    the expected value exactly.

 script_stdout_isnt

     script_stdout_is $expected_stdout, $test_name;

    Tests if the output to stdout from the previous "script_runs" does NOT
    match the expected value exactly.

 script_stdout_like

     script_stdout_like $regex, $test_name;

    Tests if the output to stdout from the previous "script_runs" matches
    the regular expression.

 script_stdout_unlike

     script_stdout_unlike $regex, $test_name;

    Tests if the output to stdout from the previous "script_runs" does NOT
    match the regular expression.

 script_stderr_is

     script_stderr_is $expected_stderr, $test_name;

    Tests if the output to stderr from the previous "script_runs" matches
    the expected value exactly.

 script_stderr_isnt

     script_stderr_is $expected_stderr, $test_name;

    Tests if the output to stderr from the previous "script_runs" does NOT
    match the expected value exactly.

 script_stderr_like

     script_stderr_like $regex, $test_name;

    Tests if the output to stderr from the previous "script_runs" matches
    the regular expression.

 script_stderr_unlike

     script_stderr_unlike $regex, $test_name;

    Tests if the output to stderr from the previous "script_runs" does NOT
    match the regular expression.
193

194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268
 program_runs

     program_runs( $program, $test_name );
     program_runs( \@program_and_arguments, $test_name );
     program_runs( $program, \%options, $test_name );
     program_runs( \@program_and_arguments, \%options, $test_name );

    The "program_runs" test executes the given program and checks that it
    returns success. This function works like "script_runs" except:

      * The path $program or @program_and_arguments is passed as-is to
      system() <https://perldoc.perl.org/functions/system.html>. This means
      program_runs can test any program, not just Perl scripts.

      * The %options do not support the interpreter_options key.

    See File::Spec or Path::Class for routines useful in building pathnames
    in a cross-platform way.

 program_stdout_is

     program_stdout_is $expected_stdout, $test_name;

    Tests if the output to stdout from the previous "program_runs" matches
    the expected value exactly.

 program_stdout_isnt

     program_stdout_is $expected_stdout, $test_name;

    Tests if the output to stdout from the previous "program_runs" does NOT
    match the expected value exactly.

 program_stdout_like

     program_stdout_like $regex, $test_name;

    Tests if the output to stdout from the previous "program_runs" matches
    the regular expression.

 program_stdout_unlike

     program_stdout_unlike $regex, $test_name;

    Tests if the output to stdout from the previous "program_runs" does NOT
    match the regular expression.

 program_stderr_is

     program_stderr_is $expected_stderr, $test_name;

    Tests if the output to stderr from the previous "program_runs" matches
    the expected value exactly.

 program_stderr_isnt

     program_stderr_is $expected_stderr, $test_name;

    Tests if the output to stderr from the previous "program_runs" does NOT
    match the expected value exactly.

 program_stderr_like

     program_stderr_like $regex, $test_name;

    Tests if the output to stderr from the previous "program_runs" matches
    the regular expression.

 program_stderr_unlike

     program_stderr_unlike $regex, $test_name;

    Tests if the output to stderr from the previous "program_runs" does NOT
    match the regular expression.

269 270
CAVEATS

271
    This module is fully supported back to Perl 5.8.1.
272

273 274 275 276 277
    The STDIN handle will be closed when using script_runs with the stdin
    option. An older version used IPC::Run3, which attempted to save STDIN,
    but apparently this cannot be done consistently or portably. We now use
    Capture::Tiny instead and explicitly do not support saving STDIN
    handles.
278

279 280
SEE ALSO

281
    Test::Script::Run, Test2::Suite
282 283 284 285 286 287 288

AUTHOR

    Original author: Adam Kennedy

    Current maintainer: Graham Ollis <plicease@cpan.org>

289 290 291 292
    Contributors:

    Brendan Byrd

293 294
    Chris White <cxw@cpan.org>

295
COPYRIGHT AND LICENSE
296

297
    This software is copyright (c) 2019 by Adam Kennedy.
298

299 300
    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.
301