1Test2::Tools::Command(3U)ser Contributed Perl DocumentatiToenst2::Tools::Command(3)
2
6 Test2::Tools::Command - test simple unix commands
7
9 use Test2::Tools::Command;
10 # test some typical unix tools; implicit checks are that status
12 # is 0, and that stdout and stderr are the empty string, unless
13 # otherwise specified
14 command { args => [ 'true' ] };
15 command { args => [ 'false' ], status => 1 };
16 command { args => [ 'echo', 'foo' ], stdout => "foo\n" };
17 # subsequent args are prefixed with this
19 local @Test2::Tools::Command::command = ( 'perl', '-E' );
20 # return values and a variety of the options available
22 my ($result, $exit_status, $stdout_ref, $stderr_ref) =
23 command { args => [ q{say "out";warn "err";kill TERM => $$} ],
24 chdir => '/some/dir',
25 env => { API_KEY => 42 },
26 stdin => "printed to program\n",
27 stdout => qr/out/,
28 stderr => qr/err/,
29 status => { code => 0, signal => 15, iscore => 0 },
30 timeout => 7 };
31 # check on a $? exit status word from somewhere
33 is_exit $?, 42;
34 is_exit $?, { code => 0, signal => 9, iscore => 0 };
35
37 This module tests that commands given particular arguments result in
38 particular outputs by way of the exit status word, standard output, and
39 standard error. Various parameters to the command function alter
40 exactly how this is done, in addition to variables that can be set.
41 The commands are expected to be simple, for example filters that maybe
43 accept standard input and respond with some but not too much output.
44 Interactive or otherwise complicated commands will need some other
45 module such as Expect to test them, as will programs that generate too
46 much output.
47 Also, is_exit is provided to check on the 16-bit exit status word from
49 other code.
50
52 These are not exported.
53 @command
55 Custom command to prefix any commands run by command with, for
56 example to specify a test program that will be used in many
57 subsequent tests
58 local @Test2::Tools::Command::command = ($^X, '--', 'bin/foo');
60 command { args => [ 'bar', '-c', 'baz' ] };
61 will result in "perl -- bin/foo bar -c baz" being run.
63 If chdir is used, a command that uses a relative path may need to
65 be fully qualified, e.g. with "rel2abs" of File::Spec::Functions.
66 $timeout
68 Seconds after which commands will be timed out via "alarm" if a
69 timeout is not given to command. 30 by default.
70
72 command is exported by default; this can be disabled by using this
73 module with an empty import list. The test keys are status, stdout, and
74 stderr. The other keys influence how the command is run or change test
75 metadata.
76 command hashref
78 Runs a command and executes one or more tests on the results,
79 depending on the contents of hashref, which may contain:
80 args => arrayref
82 List of arguments to run the command with. The argument list
83 will be prefixed by the @command variable, if that is set.
84 binmode => layer
86 If set, layer will be set on the filehandles wired to the
87 command via the "binmode" function. See also open.
88 chdir => directory
90 Attempt to "chdir" into directory or failing that will throw an
91 exception, by way of File::chdir.
92 A command that uses a relative path may need to be fully
94 qualified, e.g. with "rel2abs" of File::Spec::Functions.
95 env => hashref
97 Set the environment for the command to include the keys and
98 values present in hashref. This is additive only; environment
99 variables that must not be set must be deleted from %ENV, or
100 the command wrapped with a command that can reset the
101 environment, such as env(1).
102 name => string
104 Custom name for the tests. Otherwise, the full command executed
105 is used in the test name, which may not be ideal.
106 munge_signal => boolean
108 If the signal number of the 16-bit exit status word is not
109 zero, the signal will be munged to have the value 1.
110 munge_status => boolean
112 If the exit code of the 16-bit exit status word is not zero,
113 the code will be munged to have the value 1. Use this where the
114 program being tested is unpredictable as to what non-zero exit
115 code it will use.
116 status => code-or-hashref
118 Expect the given value as the 16-bit exit status word. By
119 default 0 for the exit code is assumed. This can be specified
120 in two different forms; the following two are equivalent:
121 status => 42
123 status => { code => 42, iscore => 0, signal => 0 }
124 Obviously the 16-bit exit status word is decomposed into a hash
126 reference. If the program is instead expected to exit by a
127 SIGPIPE, one might use:
128 status => { code => 0, iscore => 0, signal => 13 }
130 See also munge_signal and munge_status.
132 stdin => data
134 If present, data will be printed to the command and then
135 standard input will be closed. Otherwise, nothing is done with
136 standard input.
137 stdout => qr-or-string
139 Expect that the standard output of the command exactly matches
140 the given string, or if the string is a "qr//" regular
141 expression, that the output matches that expression.
142 stderr => qr-or-string
144 Expect that the standard err of the command exactly matches the
145 given string, or if the string is a "qr//" regular expression,
146 that the stderr matches that expression.
147 timeout => seconds
149 Set a custom timeout for the "alarm" call that wraps the
150 command. The variable $timeout will be used if this is unset.
151 command returns a list consisting of the result of the tests, the
153 original 16-bit exit status word, and scalar references to strings
154 that contain the standard output and standard error of the test
155 program, if any.
156 my ($result, $status, $out_ref, $err_ref) = command { ...
158 is_exit status [ code-or-hashref [ test-name ] ]
160 This routine checks that a 16-bit exit status word (usually by way
161 of the $? variable) conforms to some code or hash reference. The
162 hash reference may contain mungle_signal and munge_status that will
163 turn non-zero signal or codes into 1.
164 is_exit $?, 42;
166 is_exit $?, { code => 0, signal => 9, iscore => 0 };
167
169 None known. There are probably portability problems if you stray from
170 the unix path.
171
173 Test2::Suite
174 Expect may be necessary to test complicated programs.
176 IPC::Open3 is used to run programs; this may run into portability
178 problems on systems that stray from the way of unix?
179
181 Copyright 2022 Jeremy Mates
182 This program is distributed under the (Revised) BSD License:
184 <https://opensource.org/licenses/BSD-3-Clause>
185perl v5.36.0 2023-01-29 Test2::Tools::Command(3)