1Test::Toolbox(3)      User Contributed Perl Documentation     Test::Toolbox(3)
2
3
4

NAME

6       Test::Toolbox - tools for testing
7

SYNOPSIS

9        # load module
10        use Test::Toolbox;
11
12        # plan tests
13        rtplan 43;
14
15        # or, plan tests, but die on the first failure
16        rtplan 43, autodie=>1;
17
18        # basic test
19        rtok 'my test name', $success;
20
21        # test for failure if you prefer
22        rtok 'test name', $success, should=>0;
23
24        # two values should equal each other
25        rtcomp 'test name', $val, $other_val;
26
27        # two values should not equal each other
28        rtcomp 'test name', $val, $other_val, should=>0;
29
30        # run some code which should succeed
31        # note that the second param is undef
32        rteval 'test name', undef, sub { mysub() };
33
34        # run some code which should cause a specific error code
35        rteval 'test name', 'file-open-failed', sub { mysub() };
36
37        # check that $@ has a specific error code
38        rtid 'test name', $@, 'missing-keys';
39
40        # much more
41

OVERVIEW

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
48       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
53        rtcomp 'test name', $val, $other_val;
54
55       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
59        rtcomp 'test name', $val, $other_val, should=>0;
60
61       All test commands require a test name as the first param.
62

Meta commands

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
69        go_script_dir();
70
71   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
77        rtplan 43;
78
79       You might prefer that your script dies on the first failure. In that
80       case add the "autodie" option:
81
82        rtplan 43, autodie=>1;
83
84   rtcounts()
85       rtcounts() returns a hashref of the test counts so far. The hashref has
86       the following elements:
87
88       •   success: number of successful tests so far.
89
90       •   fail: number of failed tests so far.
91
92       •   sofar: total number of tests so far.
93
94       •   planned: total number of planned tests.
95

Test commands

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
102        rtok 'my test', 1;
103
104       You might prefer to flip the logic, so that false indicates success.
105       For that, use the "should" option:
106
107        rtok 'my test', $val, should=>0;
108
109       All other test command call rtok().
110
111   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
116        rtcomp 'my test', $first, $second;
117
118       As with other commands, you can flip the logic of the command so that
119       success is if they are not the same:
120
121        rtcomp 'my test', $first, $second, should=>0;
122
123       rtcomp() interprets undef as matching undef, so the following test
124       would would be successful.
125
126        rtcomp 'my test', undef, undef;
127
128       rtcomp() takes several options.
129
130       •   collapse
131
132           If this option is true, then the strings are collapsed before they
133           are compared. So, for example, the following test would succeed:
134
135            rtcomp 'my test', ' Fred ', 'Fred', collapse=>1;
136
137       •   nospace
138
139           nospace removes all spaces before comparing strings. So this test
140           would succeed:
141
142            rtcomp 'my test', 'Fr   ed', 'Fred', nospace=>1;
143
144       •   case_insensitive
145
146           The case_insensitive option indicates to compare the values case
147           insensitively.  So, the following test would be successful.
148
149   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
154        rtelcount 'my test', 3, \@arr;
155
156   rtarr
157       rtarr compares two arrays. In its simplest use, the test passes if they
158       are identical:
159
160        @first = qw{Larry Curly Moe};
161        @second = qw{Larry Curly Moe};
162        rtarr 'my test', \@first, \@second;
163
164       Like with rtcomp, two undefs are considered the same, so the following
165       test would pass.
166
167        @first = ('Larry', 'Moe', 'Curly', undef);
168        @second = ('Larry', 'Moe', 'Curly', undef);
169        rtarr 'my test', \@first, \@second;
170
171       rtarr takes several options.
172
173       •   order_insensitive
174
175           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
179            @first = ('Curly', 'Larry', 'Moe');
180            @second = ('Larry', 'Moe', 'Curly');
181            rtarr 'my test', \@first, \@second, order_insensitive=>1;
182
183       •   case_insensitive
184
185           If the case_insensitive option is true, then the elements are
186           compared case insensitively. So the following test would pass:
187
188            @first = ('CURLY', 'LARRY', undef, 'MOE');
189            @second = ('Curly', 'Larry', undef, 'Moe');
190            rtarr 'my test', \@first, \@second, case_insensitive=>1;
191
192   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
198        %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
202       rthash doesn't currently have a case_insensitive option. That will
203       probably be added in future releases.
204
205   rtisa
206       rtisa tests if a given value is of the given class. For example, the
207       following test would pass.
208
209        $val = [];
210        rtisa 'my test', $val, 'ARRAY';
211
212       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
215        $val = [];
216        rtisa 'my test', $val, [];
217
218       If the class is undef or an empty string, then rtisa returns true if
219       the given object is not a reference.
220
221        $val = 'whatever';
222        rtisa 'my test', $val, '';
223
224   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
230        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
235   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
240        rtdef 'my test', 'hello', 1;
241        rtdef 'my test', undef, 0;
242
243       The third param must be defined.
244
245   rtrx
246       rtrx tests if the given value matches the given regular expression. The
247       following test would pass.
248
249        rtrx 'my test', 'Fred', 'red';
250
251       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
255        rtrx 'my test', 'Fred', qr/RED$/i;
256
257   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
261        rtfile 'my test', '/tmp/log.txt';
262
263       You can use the "should" option to test if the file doesn't exist:
264
265        rtfile 'my test', '/tmp/log.txt', should=>0;
266

Message ID tests

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
271        croak 'error-opening-log-file: error opening log file';
272
273       Note that the error ID must be followed by a colon.
274
275   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
280        rtid 'my test', $!, 'error-opening-log-file';
281
282   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
287        rteval
288          'my test',
289          sub { die 'error-opening-log-file: whatever' },
290          'error-opening-log-file';
291
292       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
298        rteval
299          'my test',
300          'error-opening-log-file',
301          sub { die 'error-opening-log-file: whatever' };
302
303       If the sub is supposed to work, you can put undef for the expected
304       code:
305
306        rteval
307          'my test',
308          sub { my $val = 1 },
309          undef;
310

TERMS AND CONDITIONS

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

AUTHOR

318       Miko O'Sullivan miko@idocs.com
319

VERSION

321       Version: 0.04
322

HISTORY

324       •   Version 0.01 Aug 21, 2016
325
326           Initial release.
327
328       •   Version 0.02 Aug 23, 2016
329
330           Fixed dependency problem. Should not have been using String::Util.
331
332       •   Version 0.03 Aug 25, 2016
333
334           Added private sub collapse() which should have been in there all
335           along.
336
337       •   Version 0.04 Aug 26, 2016
338
339           Added private subs define(), rtrim(), ltrim() which should have
340           been there all along.
341
342           Added rtdiag().  Not sure how to test rtdiag(), so for now no tests
343           for that.
344
345           May have fixed test for rtfile().
346
347
348
349perl v5.36.0                      2023-01-20                  Test::Toolbox(3)
Impressum