1Test::Toolbox(3) User Contributed Perl Documentation Test::Toolbox(3)
2
6 Test::Toolbox - tools for testing
7
9 # load module
10 use Test::Toolbox;
11 # plan tests
13 rtplan 43;
14 # or, plan tests, but die on the first failure
16 rtplan 43, autodie=>1;
17 # basic test
19 rtok 'my test name', $success;
20 # test for failure if you prefer
22 rtok 'test name', $success, should=>0;
23 # two values should equal each other
25 rtcomp 'test name', $val, $other_val;
26 # two values should not equal each other
28 rtcomp 'test name', $val, $other_val, should=>0;
29 # run some code which should succeed
31 # note that the second param is undef
32 rteval 'test name', undef, sub { mysub() };
33 # run some code which should cause a specific error code
35 rteval 'test name', 'file-open-failed', sub { mysub() };
36 # check that $@ has a specific error code
38 rtid 'test name', $@, 'missing-keys';
39 # much more
41
43 Test::Toolbox provides (as you might guess) tools for automated
44 testing. Test::Toolbox is much like some other testing modules, such
45 as Test::More and Test::Simple. Test::Toolbox provides a different
46 flavor of tests which may or may not actually be to your preference.
47 The tools in Test::Toolbox have a standard format. Commands start with
49 (the command (of course), followed by the test name. Then there is
50 usually the value being tested, or values being compared, then other
51 options. So, for example, this command checks compares two values:
52 rtcomp 'test name', $val, $other_val;
54 In some cases it's preferable to flip the logic of the test, so that,
56 for example, two values should not be the same. In that case, you can
57 add the "should" option:
58 rtcomp 'test name', $val, $other_val, should=>0;
60 All test commands require a test name as the first param.
62
64 go_script_dir()
65 go_script_dir() changes to the directory that the script is running in.
66 This can be handy of your test script needs to read files that are part
67 of your tests. go_script_dir() takes no params:
68 go_script_dir();
70 rtplan()
72 rtplan() indicates how many tests you plan on running. Like with other
73 test modules, failing to run exactly that many tests is itself
74 considered on error. So, this command plans on running exactly 43
75 tests.
76 rtplan 43;
78 You might prefer that your script dies on the first failure. In that
80 case add the "autodie" option:
81 rtplan 43, autodie=>1;
83 rtcounts()
85 rtcounts() returns a hashref of the test counts so far. The hashref has
86 the following elements:
87 • success: number of successful tests so far.
89 • fail: number of failed tests so far.
91 • sofar: total number of tests so far.
93 • planned: total number of planned tests.
95
97 rtok()
98 rtok() is the basic command of Test::Toolbox. It requires two params,
99 the name of the test, and a scalar indicating success (true) or failure
100 (false). So, this simple command indicates a successful test:
101 rtok 'my test', 1;
103 You might prefer to flip the logic, so that false indicates success.
105 For that, use the "should" option:
106 rtok 'my test', $val, should=>0;
108 All other test command call rtok().
110 rtcomp()
112 rtcomp() compares the string value of two values. It sets success if
113 they are the same, failure if thet are different. Its simplest use
114 would be like this:
115 rtcomp 'my test', $first, $second;
117 As with other commands, you can flip the logic of the command so that
119 success is if they are not the same:
120 rtcomp 'my test', $first, $second, should=>0;
122 rtcomp() interprets undef as matching undef, so the following test
124 would would be successful.
125 rtcomp 'my test', undef, undef;
127 rtcomp() takes several options.
129 • collapse
131 If this option is true, then the strings are collapsed before they
133 are compared. So, for example, the following test would succeed:
134 rtcomp 'my test', ' Fred ', 'Fred', collapse=>1;
136 • nospace
138 nospace removes all spaces before comparing strings. So this test
140 would succeed:
141 rtcomp 'my test', 'Fr ed', 'Fred', nospace=>1;
143 • case_insensitive
145 The case_insensitive option indicates to compare the values case
147 insensitively. So, the following test would be successful.
148 rtelcount
150 Checks if an array has the correct number of elements. The first param
151 is an integer 0 or greater. The second param is an array reference. So,
152 the following test would pass:
153 rtelcount 'my test', 3, \@arr;
155 rtarr
157 rtarr compares two arrays. In its simplest use, the test passes if they
158 are identical:
159 @first = qw{Larry Curly Moe};
161 @second = qw{Larry Curly Moe};
162 rtarr 'my test', \@first, \@second;
163 Like with rtcomp, two undefs are considered the same, so the following
165 test would pass.
166 @first = ('Larry', 'Moe', 'Curly', undef);
168 @second = ('Larry', 'Moe', 'Curly', undef);
169 rtarr 'my test', \@first, \@second;
170 rtarr takes several options.
172 • order_insensitive
174 If the order_insensitive option is true, then the arrays are
176 considered the same even if the elements are not in the same order.
177 So the following test would pass:
178 @first = ('Curly', 'Larry', 'Moe');
180 @second = ('Larry', 'Moe', 'Curly');
181 rtarr 'my test', \@first, \@second, order_insensitive=>1;
182 • case_insensitive
184 If the case_insensitive option is true, then the elements are
186 compared case insensitively. So the following test would pass:
187 @first = ('CURLY', 'LARRY', undef, 'MOE');
189 @second = ('Curly', 'Larry', undef, 'Moe');
190 rtarr 'my test', \@first, \@second, case_insensitive=>1;
191 rthash
193 rthash checks is two hashes contain the same keys and values. The
194 following test would pass. Keep in mind that hashes don't have the
195 concept of order, so it doesn't matter that the hashes are created with
196 differently ordered keys.
197 %first = ( Curly=>'big hair', Moe=>'flat hair', Schemp=>undef);
199 %second = ( Moe=>'flat hair', Schemp=>undef, Curly=>'big hair');
200 rthash 'my test', \%first, \%second;
201 rthash doesn't currently have a case_insensitive option. That will
203 probably be added in future releases.
204 rtisa
206 rtisa tests if a given value is of the given class. For example, the
207 following test would pass.
208 $val = [];
210 rtisa 'my test', $val, 'ARRAY';
211 The second value can be either the name of the class or an example of
213 the class, so the following test would also pass.
214 $val = [];
216 rtisa 'my test', $val, [];
217 If the class is undef or an empty string, then rtisa returns true if
219 the given object is not a reference.
220 $val = 'whatever';
222 rtisa 'my test', $val, '';
223 rtbool
225 rtbool checks if two values have the same boolean value, that is, if
226 they are both true or both false. Booleans are checked in the perlish
227 sense, so the values don't have to be the same, they just have to have
228 the same perlish boolean values. Here are some examples.
229 rtbool 'my test', 'whatever', 'dude'; # passes
231 rtbool 'my test', 'whatever', 1; # passes
232 rtbool 'my test', 'whatever', undef; # fails
233 rtbool 'my test', 0, undef; # passes
234 rtdef
236 rtdef tests if the given value is defined. The second param is the
237 value being tested, the third param is if the value should be defined
238 or not. So, the following tests would pass.
239 rtdef 'my test', 'hello', 1;
241 rtdef 'my test', undef, 0;
242 The third param must be defined.
244 rtrx
246 rtrx tests if the given value matches the given regular expression. The
247 following test would pass.
248 rtrx 'my test', 'Fred', 'red';
250 If you want to get fancy with your regular expressions, use qr// to
252 create the regexes as you pass them in. The following test is an
253 example.
254 rtrx 'my test', 'Fred', qr/RED$/i;
256 rtfile
258 rtfile tests if the given file path exists. In its simplest use, rtfile
259 takes just the name of the file and the path:
260 rtfile 'my test', '/tmp/log.txt';
262 You can use the "should" option to test if the file doesn't exist:
264 rtfile 'my test', '/tmp/log.txt', should=>0;
266
268 The following tests checking for errors that begin with an error code,
269 followed by a colon, followed by plain language. For example:
270 croak 'error-opening-log-file: error opening log file';
272 Note that the error ID must be followed by a colon.
274 rtid()
276 rtid() checks if the given string starts with the given id. For
277 example, to test is $! starts with the id 'error-opening-log-file' you
278 would use this command:
279 rtid 'my test', $!, 'error-opening-log-file';
281 rteval()
283 rteval() allows you to test some code then check for an error id, all
284 in one easy command. rteval runs the given subroutine in an eval{}
285 block, then tests Here's an (admittedly contrived) example:
286 rteval
288 'my test',
289 sub { die 'error-opening-log-file: whatever' },
290 'error-opening-log-file';
291 If your subroutine is really long, you might prefer to put the id as
293 the first param, then the sub. rteval() provides some forgivness in
294 that regard: if the second param is a sub, then the first param is
295 assumed to be the id. So the following example works the same as the
296 above example:
297 rteval
299 'my test',
300 'error-opening-log-file',
301 sub { die 'error-opening-log-file: whatever' };
302 If the sub is supposed to work, you can put undef for the expected
304 code:
305 rteval
307 'my test',
308 sub { my $val = 1 },
309 undef;
310
312 Copyright (c) 2016 by Miko O'Sullivan. All rights reserved. This
313 program is free software; you can redistribute it and/or modify it
314 under the same terms as Perl itself. This software comes with NO
315 WARRANTY of any kind.
316
318 Miko O'Sullivan miko@idocs.com
319
321 Version: 0.04
322
324 • Version 0.01 Aug 21, 2016
325 Initial release.
327 • Version 0.02 Aug 23, 2016
329 Fixed dependency problem. Should not have been using String::Util.
331 • Version 0.03 Aug 25, 2016
333 Added private sub collapse() which should have been in there all
335 along.
336 • Version 0.04 Aug 26, 2016
338 Added private subs define(), rtrim(), ltrim() which should have
340 been there all along.
341 Added rtdiag(). Not sure how to test rtdiag(), so for now no tests
343 for that.
344 May have fixed test for rtfile().
346perl v5.36.0 2023-01-20 Test::Toolbox(3)