1Test::Inter(3) User Contributed Perl Documentation Test::Inter(3)
2
6 Test::Inter - framework for more readable interactive test scripts
7
9 This is another framework for writing test scripts. It is loosely
10 inspired by Test::More, and has most of it's functionality, but it is
11 not a drop-in replacement.
12 Test::More (and other existing test frameworks) suffer from two
14 weaknesses, both of which have prevented me from ever using them:
15 None offer the ability to access specific tests in
17 a reasonably interactive fashion
18 None offer the ability to write the tests in
20 whatever format would make the tests the most
21 readable
22 The way I write and use test scripts, existing Test::* modules are not
24 nearly as useful as they could be. Test scripts written using
25 Test::More work fine when running as part of the test suite, but
26 debugging an individual test requires extra steps, and the tests
27 themselves are not as readable as they should be.
28 I do most of my debugging using test scripts. When I find a bug, I
30 write a test case for it, debug it using the test script, and then
31 leave the test there so the bug won't come back (hopefully).
32 Since I use test scripts in two ways (part of a standard test suite and
34 to run the scripts in some interactive way to debug problems), I want
35 to be able to do the follwing trivially:
36 Easy access to a specific test or tests
38 If I'm running the test script interactively (perhaps in the
39 debugger), there are several common functions that I want to have
40 available, including:
41 Run only a single test, or a subset of tests
43 Set a breakpoint in the debugger to run
45 up to the start of the Nth test
46 Better diagnostics
48 When running a test script as part of a test suite, the pass/fail
49 status is really the only thing of interest. You just want to know
50 if the module passes all the tests.
51 When running interactively, additional information may allow me to
53 quickly track down the problem without even resorting to a
54 debugger.
55 If a test fails, I almost always want to see why it failed if I'm
57 running it interactively. If reasonable, I want to see a list of
58 what was input, what was output, and what was expected.
59 The other feature that I wanted in a test suite is the ability to
61 define the tests in a readable format. In almost every case, it is best
62 to think of a test script as consisting of two separate parts: a script
63 part, and a test part, and the more you can keep the two separate, the
64 better.
65 The script part of a test script is the least important part! It's
67 usually fairly trivial, rarely needs to be changed, and is quite simply
68 not the focus of the test script.
69 The tests part of the script IS the important part, and these should be
71 expressed in a form that is easy to maintain, easy to read, and easy to
72 modify, and none of these should involve modifying the script portion
73 of the test script in general. As a general rule, if the script portion
74 of the test script obscures the tests in any way, it's not written
75 correctly!
76 Compare this to any other systems where you are mixing two "languages".
78 For example, a PHP script where you have a mixture of PHP and HTML or a
79 templating system consisting of text and template commands. The more
80 the two languages are interwoven, the less readable both are, and the
81 harder it is to maintain.
82 As often as possible, I want the tests to be written in some sort of
84 text format which can be easily read as a table with no perl commands
85 interspersed. I want to the freedom to define the tests in one big
86 string (perhaps a DATA section, or even in a separate file) which is
87 easily readable. This may introduce the necessity of parsing it, but it
88 makes it significantly easier to maintain the tests.
89 This flexibilty makes it much easier to read the tests (as opposed to
91 the script) which is the fundamental content of a test script.
92 To illustrate some of this, in Test::More, a series of tests might be
94 specified as:
95 # test 1
97 $result = func("apples","bushels");
98 is($result, "enough");
99 # test 2
101 $result = func("grapefruit","tons");
102 is($result, "enough");
103 # test 3
105 $result = func("oranges","boatloads");
106 is($result, "insufficient");
107 Thinking about the features I want that I listed above, there are
109 several difficulties with this.
110 Debugging the script is tedious
112 To debug the 3rd test, I've got to do the following steps:
113 get the line number of the 3rd func call
115 set a breakpoint for it
116 run the program
117 wait for the first two tests to complete
118 step into the function
119 None of these steps are hard of course, but even so, getting to the
121 first line of the test requires several steps which tend to break
122 up your chain of thought when you want to be thinking exclusively
123 about debugging the test.
124 How much better to be able to say:
126 break in func when testnum==3
128 Way too much perl interspersed with the tests
130 It's difficult to read the tests individually in this script
131 because there is too much perl code among them, and virtually
132 impossible to look at them as a whole.
133 It is true that looking at this as a perl script, it is very
135 simple... but the script ISN'T the content you're interested in.
136 The REAL content of this script are the tests, which consist of the
137 function arguments and the expected result. Although it's not
138 impossible to see each of these in the script above, it's not in a
139 format that is conducive to studying the tests, and especially not
140 for examing the list of tests as a whole.
141 Now, look at an alternate way of specifying the tests using this
143 module:
144 $tests = "
146 apples bushels => enough
148 grapefruit tons => enough
150 oranges boatloads => insufficient
152 ";
154 $o->tests(tests => $tests,
156 func => \&func);
157 Here, it's easy to see the list of tests, and adding additional tests
159 is a breeze.
160 This module supports a number of methods for defining tests, so you can
162 use whichever one is most convenient (including methods that are
163 identical to Test::More).
164 In addition, the following debugger command works as desired:
166 b func ($::TI_NUM==3)
168 and you're ready to debug.
170
172 Every test may have several pieces of information:
173 A name
175 Every test is automatically assigned a number, but it may be useful
176 to specify a name of a test (which is actually a short description
177 of the test). Whenever a test result is reported, the name will be
178 given (if one was specified).
179 The name may not have a '#' in it.
181 The name is completely optional, but makes the results more
183 readable.
184 An expected result
186 In order to test something, you need to know what result was
187 expected (or in some cases, what result was NOT expected).
188 A function and arguments OR a result
190 You also need to know the results that you're comparing to the
191 expected results.
192 This can be obtained by simply working with a set of results, or a
194 function name and a set of arguments to pass to it.
195 Conditions
197 It is useful to be able to specify state information at the start
198 of the test suite (for example, to see if certain features are
199 available), and some tests may only run if those conditions are
200 met.
201 If no conditions are set for a test, it will always run.
203 Todo tests
205 Some tests may be marked as 'todo' tests. These are test which are
206 allowed to fail (meaning that they have been put in place for an
207 as-yet unimplemented feature). Since it is expected that the test
208 will fail, the test suite will still pass, even if these tests
209 fail.
210 The tests will still run and if they pass, a message is issued
212 saying that the feature is now implemented, and the tests should be
213 graduated to non-todo state.
214
216 new
217 $o = new Test::Inter [$name] [%options];
218 This creates a new test framework. There are several options which
220 may be used to specify which tests are run, how they are run, and
221 what output is given.
222 The entire test script can be named by passing in $name. Options
224 can be passed in as a hash of ($opt,$val) pairs.
225 Options can be set in four different ways. First, you can pass in
227 an ($opt,$val) pair in the new method. Second, you can set an
228 environment variable (which overrides any value passed to the new
229 method). Third, you can set a global variable (which overrides both
230 the environment variable and options passed to the new method).
231 Fouth, you can call the appropriate method to set the option. This
232 overrides all other methods.
233 Each of the allowed options are described below in the following
235 base methods:
236 start
238 end
239 test
240 plan
241 abort
242 quiet
243 mode
244 skip_all
245 version
247 $o->version();
248 Returns the version of the module.
250 start
252 $o = new Test::Inter 'start' => $N;
253 $o->start($N)
254 To define which test you want to start with, pass in an ($opt,$val)
256 pair of ('start',N), set an environment variable TI_START=N, or a
257 global variable $::TI_START=N.
258 When the start test is defined, most tests numbered less than N are
260 completely ignored. If the tests are being run quietly (see the
261 quiet method below), nothing is printed out for these tests.
262 Otherwise, a skip message is printed out.
263 One class of tests IS still executed. Tests run using the
265 require_ok or use_ok methods (to test the loading of modules) are
266 still run.
267 If no value (or a value of 0) is used, it defaults to the first
269 test.
270 end
272 $o = new Test::Inter 'end' => $M;
273 $o->end($M);
274 To define which test you want to end with, pass in an ($opt,$val)
276 pair of ('end',M), set an environment variable TI_END=M, or set a
277 global variable $::TI_END=M.
278 When the end test is defined, all tests numbered more than M are
280 completely ignored. If the tests are being run quietly (see the
281 quiet method below), nothing is printed out for these tests.
282 Otherwise, a skip message is printed out.
283 If no value is given, it defaults to 0 (which means that all
285 reamining tests are run).
286 testnum
288 $o = new Test::Inter 'testnum' => $N;
289 $o->testnum($N);
290 This is used to run only a single test. It is equivalent to setting
292 both the start and end tests to $N.
293 plan
295 done_testing
296 $o = new Test::Inter 'plan' => $N;
297 $o->plan($n);
298 $o->done_testing();
300 $o->done_testing($n);
301 The TAP API (the 'language' used to run a sequence of tests and see
303 which ones failed and which ones passedd) requires a statement of
304 the number of tests that are expected to run.
305 This statement can appear at the start of the test suite, or at the
307 end.
308 If you know in advance how many tests should run in the test
310 script, you can pass in a non-zero integer in a ('plan',N) pair to
311 the new method, or set the TI_PLAN environment variable or the
312 $::TI_PLAN global variable, or call the plan method.
313 If you know how many tests should run at the end of the test
315 script, you can pass in a non-zero integer to the done_testing
316 method.
317 Frequently, you don't really care how many tests are in the script
319 (especially if new tests are added on a regular basis). In this
320 case, you still need to include a statement that says that the
321 number of tests expected is however many were run. To do this, call
322 the done_testing method with no argument.
323 NOTE: if the plan method is used, it MUST be used before any tests
325 are run (including those that test the loading of modules). If the
326 done_testing method is used, it MUST be called after all tests are
327 run. You must specify a plan or use a done_testing statement, but
328 you cannot do both.
329 It is NOT strictly required to set a plan if the script is only run
331 interactively, so if for some reason this module is used for test
332 scritps which are not part of a standard perl test suite, the plan
333 and done_testing statements are optional. As a matter of fact, the
334 script will run just fine without them... but a perl installer will
335 report a failure in the test suite.
336 abort
338 $o = new Test::Inter 'abort' => 0/1/2;
339 $o->abort(0/1/2);
340 The abort option can be set using an ('abort',0/1/2) option pair,
342 or by setting the TI_ABORT environment variable, or the $::TI_ABORT
343 global variable.
344 If this is set to 1, the test script will run unmodified until a
346 test fails. At that point, all remaining tests will be skipped. If
347 it is set to 2, the test script will run until a test fails at
348 which point it will exit with an error code of 1.
349 In both cases, todo tests will NOT trigger the abort behavior.
351 quiet
353 $o = new Test::Inter 'quiet' => 0/1/2;
354 $o->quiet(0/1/2);
355 The quiet option can be set using an ('quiet',0/1/2) option pair,
357 or by setting the TI_QUIET environment variable, or the $::TI_QUIET
358 global variable.
359 If this is set to 0 (the default), all information will be printed
361 out. If it is set to 1, some optional information will not be
362 printed. If it is set to 2, all optional information will not be
363 printed.
364 mode
366 $o = new Test::Inter 'mode' => MODE;
367 $o->mode(MODE);
368 The mode option can be set using a ('mode',MODE) option pair, or by
370 setting the TI_MODE environment variable, or the $::TI_MODE global
371 variable.
372 Currently, MODE can be 'test' or 'inter' meaning that the script is
374 run as part of a test suite, or interactively.
375 When run in test mode, it prints out the results using the TAP
377 grammar (i.e. 'ok 1', 'not ok 3', etc.).
378 When run in interactive mode, it prints out results in a more human
380 readable format.
381 skip_all
383 $o = new Test::Inter 'skip_all' => REASON;
384 $o->skip_all(REASON);
385 The skip_all option can be set using an ('skip_all',REASON) option
387 pair, or by setting the TI_SKIP_ALL environment variable, or the
388 $::TI_SKIP_ALL global variable.
389 If this is set, the entire test script will be skipped for the
391 reason given. This must be done before any test is run, and before
392 any plan number is set.
393 The skip_all can also be called at any point during the script
395 (i.e. after tests have been run). In this case, all remaining
396 scripts will be skipped.
397 $o->skip_all(REASON,FEATURE,FEATURE,...);
399 $o->skip_all('',FEATURE,FEATURE,...);
400 This will skip all tests (or all remaining tests) unless all
402 features are available. REASON can be entered as an empty string
403 and the reason the tests are skipped will be a message about the
404 missing feature.
405 feature
407 $o->feature($feature,$val);
408 This defines a feature. If $val is non-zero, the feature is
410 available. Otherwise it is not.
411 diag
413 note
414 $o->diag($message);
415 $o->note($message);
416 Both of these print an optional message. Messages printed with the
418 note method are always optional and will be omitted if the quiet
419 option is set to 1 or 2. Messages printed with the diag method are
420 optional and will not be printed if the quiet option is set to 2,
421 but they will be printed if the quiet method is set to 1.
422 testdir
424 Occasionally, it may be necessary to know the directory where the
425 tests live (for example, there may be a config or data file in
426 there). This method will return the directory.
427
429 Test scripts can load other modules (using either the perl 'use' or
430 'require' commands). There are three different modes for doing this
431 which determine how this is done.
432 required mode
434 By default, this is used to test for a module that is required for
435 all tests in the test script.
436 Loading the module is treated as an actual test in the test suite.
438 The test is to determine whether the module is available and can be
439 loaded. If it can be loaded, it is, and it is reported as a
440 successful test. If it cannot be loaded, it is reported as a failed
441 test.
442 In the result of a failed test, all remaining tests will be skipped
444 automatically (except for other tests which load modules).
445 feature mode
447 In feature mode, loading the module is not treated as a test (i.e.
448 it will not print out an 'ok' or 'not ok' line. Instead, it will
449 set a feature (named the same as the module) which can be used to
450 determine whether other tests should run or not.
451 forbid mode
453 In a few very rare cases, we may want to test for a module but
454 expect that it not be present. This is the exact opposite of the
455 'required' mode.
456 Successfully loading the module is treated as a test failure. In
458 the event of a failure, all remaining tests will be skipped.
459 The methods available are:
461 require_ok
463 $o->require_ok($module [,$mode]);
464 This is used to load a module using the perl 'require' function. If
466 $mode is not passed in, the default mode (required) is used to test
467 the existance of the module.
468 If $mode is passed in, it must be either the string 'forbid' or
470 'feature'.
471 use_ok
473 $o->use_ok(@args [,$mode]);
474 This is used to load a module with 'use', or check a perl version.
476 BEGIN { $o->use_ok('5.010'); }
478 BEGIN { $o->use_ok('Some::Module'); }
479 BEGIN { $o->use_ok('Some::Module',2.05); }
480 BEGIN { $o->use_ok('Some::Module','foo','bar'); }
481 BEGIN { $o->use_ok('Some::Module',2.05,'foo','bar'); }
482 are the same as:
484 use 5.010;
486 use Some::Module;
487 use Some::Module 2.05;
488 use Some::Module qw(foo bar);
489 use Some::Module 2.05 qw(foo bar);
490 Putting the use_ok call in a BEGIN block allows the functions to be
492 imported at compile-time and prototypes are properly honored.
493 You'll also need to load the Test::Inter module, and create the
494 object in a BEGIN block.
495 $mode acts the same as in the require_ok method.
497
499 There are several methods for running tests. The ok, is, and isnt
500 methods are included for those already comfortable with Test::More and
501 wishing to stick with the same format of test script. The tests method
502 is the suggested method though since it makes use of the full power of
503 this module.
504 ok
506 $o->ok(TESTS);
507 A test run with ok looks at a result, and if it evaluates to 0 (or
509 false), it fails. If it evaluates to non-zero (or true), it passes.
510 These tests do not require you to specify the expected results. If
512 expected results are given, they will be compared against the
513 result received, and if they differ, a diagnostic message will be
514 printed, but the test will still succeed or fail based only on the
515 actual result produced.
516 These tests require a single result and either zero or one expected
518 results.
519 To run a single test, use any of the following:
521 $o->ok(); # always succeeds
523 $o->ok($result);
525 $o->ok($result,$name);
526 $o->ok($result,$expected,$name);
527 $o->ok(\&func);
529 $o->ok(\&func,$name);
530 $o->ok(\&func,$expected,$name);
531 $o->ok(\&func,\@args);
533 $o->ok(\&func,\@args,$name);
534 $o->ok(\&func,\@args,$expected,$name);
535 If $result is a scalar, the test passes if $result is true. If
537 $result is a list reference, and the list is either empty, or the
538 first element is a scalar), the test succeeds if the list contains
539 any values (except for undef). If $result is a hash reference, the
540 test succeeds if the hash contains any key with a value that is not
541 undef.
542 If \&func and \@args are passed in, then $result is generated by
544 passing @args to &func and behaves identically to the calls where
545 $result is passed in. If \&func is passed in but no arguments, the
546 function takes no arguments, but still produces a result.
547 $result may be a scalar, list reference, or hash reference. If it
549 is a list reference, the test passes is the list contains any
550 defined values. If it is a hash reference, the test passes if any
551 of the keys contain defined values.
552 If an expected value is passed in and the result does not match it,
554 a diagnostic warning will be printed, even if the test passes.
555 is
557 isnt
558 $o->is(TESTS);
559 $o->isnt(TESTS);
560 A test run with is looks as a result and tests to see if it is
562 identical to an expected result. If it is, the test passes.
563 Otherwise it fails. In the case of a failure, a diagnostic message
564 will show what result was actually obtained and what was expected.
565 A test run with isnt looks at a result and tests to see if the
567 result obtained is different than an expected result. If it is
568 different, the test passes. Otherwise it fails.
569 The is method can be called in any of the following ways:
571 $o->is($result,$expected);
573 $o->is($result,$expected,$name);
574 $o->is(\&func,$expected);
576 $o->is(\&func,$expected,$name);
577 $o->is(\&func,\@args,$expected);
579 $o->is(\&func,\@args,$expected,$name);
580 The isnt method can be called in exactly the same way.
582 As with the ok method, the result can be a scalar, hashref, or
584 listref. If it is a hashref or listref, the entire structure must
585 match the expected value.
586 tests
588 $o->tests($opt=>$val, $opt=>$val, ...)
589 The options available are described in the following section.
591 file
593 $o->file($func,$input,$outputdir,$expected,$name [,@args]);
594 Sometimes it may be easiest to store the input, output, and
596 expected output from a series of tests in files. In this case, each
597 line of output will be treated as a single test, so the output and
598 expected output must match up exactly.
599 $func is a reference to a function which will produce a temporary
601 output file. If $input is specified, it is the name of the input
602 file, and it will be passed to the function as the first argument.
603 If $input is left blank, no input file will be used. The input file
604 may be specified as a full path, or just the file name (in which
605 case it will be looked for in the test directory and the current
606 directory).
607 $func also takes a arequired argument which is the output file.
609 The tests method will create a tempoary file containing the output.
610 If $outputdir is passed in, it is the directory where the output
611 file will be written. If $outputdir is left blank, the temporary
612 file will be written to the test directory.
613 If @args is passed in, it is a list of additional arguments which
615 will be passed to $func.
616 $expected is the name of a file which contains the expeccted
618 output. It can be fully specified, or it will be checked for in
619 the test directory.
620
622 It is expected that most tests (except for those that load a module)
623 will be run using the tests method called as:
624 $o->tests($opt => $val, $opt => $val, ...);
626 The following options are available:
628 name
630 name => NAME
631 This sets the name of this set of tests. All tests will be given
633 the same name.
634 tests
636 func
637 expected
638 In order to specify a series of tests, you have to specify either a
639 function and a list of arguments, or a list of results.
640 Specifying the function and list of arguments can be done using the
642 pair:
643 func => \&FUNCTION
645 tests => TESTS
646 If the func option is not set, tests contains a list of results.
648 A list of expected results may also be given. They can be included
650 in the
651 tests => TESTS
653 option or included separately as:
655 expected => RESULTS
657 The way to specify these are covered in the next section SPECIFYING
659 THE TESTS.
660 feature
662 disable
663 feature => [FEATURE1, FEATURE2, ...]
664 disable => [FEATURE1, FEATURE2, ...]
666 The default set of tests to run is determined using the start, end,
668 and skip_all methods discussed above. Using those methods, a list
669 of tests is obtained, and it is expected that these will run.
670 The feature and disable options modify the list.
672 If the feature option is included, the tests given in this call
674 will only run if ALL of the features listed are available.
675 If the disable option is included, the tests will be run unless ANY
677 of the features listed are available.
678 skip
680 skip => REASON
681 Skip these tests for the reason given.
683 todo
685 todo => 0/1
686 Setting this to 1 says that these tests are allowed to fail. They
688 represent a feature that is not yet implemented.
689 If the tests succeed, a message will be printed notifying the
691 developer that the tests are now ready to promote to actual use.
692
694 A series of tests can be specified in two different ways. The tests can
695 be written in a very simple string format, or stored as a list.
696 Demonstrating how this can be done is best done by example, so let's
698 say that there is a function (func) which takes two arguments, and
699 returns a single value. Let's say that the expected output (and the
700 actual output) from 3 different sets of arguments is:
701 Input Expected Output Actual Output
703 ----- --------------- -------------
704 1,2 a a
705 3,4 b x
706 5,6 c c
707 (so in this case, the first and third tests pass, but the 2nd one will
709 fail).
710 Specifying these tests as lists could be done as:
712 $o->tests(
714 func => &func,
715 tests => [ [1,2], [3,4], [5,6] ],
716 expected => [ [a], [b], [c] ],
717 );
718 Here, the tests are stored as a list, and each element in the list is a
720 listref containing the set of arguments.
721 If the func option is not passed in, the tests option is set to a list
723 of results to compare with the expected results, so the following is
724 equivalent to the above:
725 $o->tests(
727 tests => [ [a], [x], [c] ],
728 expected => [ [a], [b], [c] ],
729 );
730 If an argument (or actual result) or an expected result is only a
732 single value, it can be entered as a scalar instead of a list ref, so
733 the following is also equivalent:
734 $o->tests(
736 func => &func,
737 tests => [ [1,2], [3,4], [5,6] ],
738 expected => [ a, b, [c] ],
739 );
740 The only exception to this is if the single value is itself a list
742 reference. In this case it MUST be included as a reference. In other
743 words, if you have a single test, and the expected value for this test
744 is a list reference, it must be passed in as:
745 expected => [ [ \@r ] ]
747 NOT as:
749 expected => [ \@r ]
751 Passing in a set of expected results is optional. If none are passed
753 in, the tests are treated as if they had been passed to the 'ok' method
754 (i.e. if they return something true, they pass, otherwise they fail).
755 The second way to specify tests is as a string. The string is a multi-
757 line string with each tests being separate from the next test by a
758 blank line. Comments (lines which begin with '#') are allowed, and are
759 ignored. Whitespace at the start and end of the line is ignored.
760 The string may contain the results directly, or results may be passed
762 in separately. For example, the following all give the same sets of
763 tests as the example above:
764 $o->tests(
766 func => &func,
767 tests => "
768 # Test 1
769 1 2 => a
770 # Test 2
772 3 4 => b
773 5 6 => c
775 ",
776 );
777 $o->tests(
779 func => &func,
780 tests => "
781 1 2
782 3 4
784 5 6
786 ",
787 expected => [ [a], [b], [c] ]
788 );
789 $o->tests(
791 func => &func,
792 tests => [ [1,2], [3,4], [5,6] ],
793 expected => "
794 a
795 b
797 c
799 ",
800 );
801 $o->tests(
803 func => &func,
804 tests => "
805 1 2
806 3 4
808 5 6
810 ",
811 expected => "
812 a
813 b
815 c
817 ",
818 );
819 The expected results may also consist of only a single set of results
821 (in this case, it must be passed in as a listref). In this case, all of
822 the tests are expected to have the same results.
823 So, the following are equivalent:
825 $o->tests(
827 func => &func,
828 tests => "
829 1 2 => a b
830 3 4 => a b
832 5 6 => a b
834 ",
835 );
836 $o->tests(
838 func => &func,
839 tests => "
840 1 2
841 3 4
843 5 6
845 ",
846 expected => [ [a, b] ],
847 );
848 $o->tests(
850 func => &func,
851 tests => "
852 1 2
853 3 4
855 5 6
857 ",
858 expected => "a b",
859 );
860 The number of expected values must either be 1 (i.e. all of the tests
862 are expected to produce the same value) or exactly the same number as
863 the number of tests.
864 The parser is actually quite powerful, and can handle multi-line tests,
866 quoted strings, and nested data structures.
867 The test may be split across any number of lines, provided there is not
869 a completely blank line (which signals the end of the test), so the
870 following are eqivalent:
871 tests => "a b c",
873 tests => "a b
874 c",
875 Arguments (or expected results) may include data structures. For
877 example, the following are equivalent:
878 tests => "[ a b ] { a 1 b 2 }"
880 tests => [ [ [a,b], { a=>1, b=>2 } ] ]
881 Whitespace is mostly optional, but there is one exception. An item must
883 end with some kind of delimiter, so the following will fail:
884 tests => "[a b][c d]"
886 The first element (the list ref [a b]) must be separated from the
888 second element by the delimiter (which is whitespace in this case), so
889 it must be written as:
890 tests => "[a b] [c d]"
892 As already demonstrated, hashrefs and listrefs may be included and
894 nested. Elements may also be included inside parens, but this is
895 optional since all arguments and expected results are already treated
896 as lists, so the following are equivalent:
897 tests => "a b c"
899 tests => "(a b) c"
900 Although parens are optional, they may make things more readable, and
902 allow you to use something other than whitespsace as the delimiter.
903 If the character immediately following the opening paren, brace, or
905 bracket is a punctuation mark, then it is used as the delimiter instead
906 of whitespace. For example, the following are all equivalent:
907 [ a b c ]
909 [a b c]
910 [, a,b,c ]
911 [, a, b, c ]
912 A delimiter is a single character, and the following may not be used as
914 a delimiter:
915 any opening/closing characters () [] {}
917 single or double quotes
918 alphanumeric characters
919 underscore
920 Whitespace (including newlines) around the delimiter is ignored, so the
922 following is valid:
923 [, a,
925 b,
926 c ]
927 Two delimiters next to each other or a trailing delimiter produce an
929 empty string.
930 "(,a,b,)" => (a, b, '')
932 "(,a,,b)" => (a, '', b)
933 Hashrefs may be specified by braces and the following are equivalent:
935 { a 1 b 2 }
937 {, a,1,b,2 }
938 {, a,1,b,2, }
939 Note that a trailing delimiter is ignored if there are already an even
941 number of elements, or an empty string otherwise.
942 Nested structures are allowed:
944 "[ [1 2] [3 4] ]"
946 For example,
948 $o->tests(
950 func => &func,
951 tests => "a [ b c ] { d 1 e 2 } => x y"
952 );
953 is equivalent to:
955 $o->tests(
957 func => &func,
958 tests => [ [a, [b,c], {d=>1,e=>2}] ],
959 results => [ [x,y] ],
960 );
961 Any single value can be surrounded by single or double quotes in order
963 to include the delimiter. So:
964 "(, a,'b,c',e )"
966 is equivalent to:
968 "( a b,c e )"
970 Any single value can be the string '__undef__' which will be turned
972 into an actual undef. If the value is '__blank__' it is turned into an
973 empty string (''), though it can also be specified as '' directly. Any
974 value can have an embedded newline by including a __nl__ in the value,
975 but the value must be written on a single line.
976 Expected results are separated from arguments by ' => '.
978
980 The history of this module dates back to 1996 when I needed to write a
981 test suite for my Date::Manip module. At that time, none of the Test::*
982 modules currently available in CPAN existed (the earliest ones didn't
983 come along until 1998), so I was left completely on my own writing my
984 test scripts.
985 I wrote a very basic version of my test framework which allowed me to
987 write all of the tests as a string, it would parse the string, count
988 the tests, ad then run them.
989 Over the years, the functionality I wanted grew, and periodically, I'd
991 go back and reexamine other Test frameworks (primarily Test::More) to
992 see if I could replace my framework with an existing module... and I've
993 always found them wanting, and chosen to extend my existing framework
994 instead.
995 As I've written other modules, I've wanted to use the framework in them
997 too, so I've always just copied it in, but this is obviously tedious
998 and error prone. I'm not sure why it took me so long... but in 2010, I
999 finally decided it was time to rework the framework in a module form.
1000 I loosely based my module on Test::More. I like the functionality of
1002 that module, and wanted most of it (and I plan on adding more in future
1003 versions). So this module uses some similar syntax to Test::More
1004 (though it allows a great deal more flexibility in how the tests are
1005 specified).
1006 One thing to note is that I may have been able to write this module as
1008 an extension to Test::More, but after looking into that possibility, I
1009 decided that it would be faster to not do that. I did "borrow" a couple
1010 of routines from it (though they've been modified quite heavily) as a
1011 starting point for a few of the functions in this module, and I thank
1012 the authors of Test::More for their work.
1013
1015 None known.
1016
1018 Test::More - the 'industry standard' of perl test frameworks
1019
1021 This script is free software; you can redistribute it and/or modify it
1022 under the same terms as Perl itself.
1023
1025 Sullivan Beck (sbeck@cpan.org)
1026perl v5.10.1 2011-12-07 Test::Inter(3)