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

NAME

6       Test::Inter - framework for more readable interactive test scripts
7

DESCRIPTION

9       This is another framework for writing test scripts. Much of the syntax
10       is loosely inspired by Test::More, and Test::Inter has most of it's
11       functionality, but it is not a drop-in replacement.
12
13       Test::More (and other existing test frameworks) suffer from two
14       weaknesses, both of which have prevented me from ever using them:
15
16          None offer the ability to access specific tests in
17          a reasonably interactive fashion, primarily for
18          debugging purposes
19
20          None offer the ability to write the tests in
21          whatever format would make the tests the most
22          readable
23
24       The way I write and use test scripts, existing Test::* modules are not
25       nearly as useful as they could be.
26
27       Test scripts written using Test::More work fine when running as part of
28       the test suite, but debugging an individual test requires extra steps,
29       and the tests themselves are not as readable as they should be.
30

INTERACTIVE EXECUTION

32       One requirement that I have of a test framework is the ability to
33       interact with it.
34
35       I do most of my debugging using test scripts. When I find a bug, I
36       write a test case for it (typically by adding it to an existing test
37       script) and then debug it using the test script.  Then I leave the test
38       there to ensure that the bug won't come back (hopefully).
39
40       Since I use test scripts in a very interactive way (often in the
41       debugger), I want to be able to do the following trivially:
42
43       Easy access to a specific test or tests
44           I'd like to be able to run only a single test, or a subset of
45           tests.
46
47       Easily set breakpoints in the debugger
48           Setting a breakpoint in the debugger to run up to the start of the
49           Nth test is one of the most common tasks I want to do when I'm
50           debugging a failed test.
51
52       To illustrate the first point, in Test::More, a series of tests might
53       be specified in a test script as shown in the following example (line
54       numbers added for convenience):
55
56          ...
57
58          100:  # test 1
59          101:  $result = func("apples","bushels");
60          102:  is($result, "enough");
61          103:
62          104:  # test 2
63          105:  $result = func("grapefruit","tons");
64          106:  is($result, "enough");
65          107:
66          108:  # test 3
67          109:  $result = func("oranges","boatloads");
68          110:  is($result, "insufficient");
69          111:
70          112:  # tests 4-6
71          113:  foreach my $arg (qw(pears plums pineapple)) {
72          114:    $result = func($arg,"boxes");
73          115:    is($result, "enough");
74          116:  }
75
76          ...
77
78       Say you ran the test suite, and test 3 failed.  To debug it you have to
79       open up the test script, find the 3rd test, and set the appropriate
80       breakpoint.  In this case, you'll want to break at line 109.
81
82       None of these steps are impossible of course, but it will take some
83       time to get it right.  It becomes harder when there are lots of tests
84       (imagine that you want to test the 117th test instead of the 3rd test)
85       or when tests are wrapped up in loops, embedded in subroutines, or
86       other similar situations.
87
88       As an example, what if it's the 5th test that fails in the example
89       above.  Now the break point will be a conditional one, so you have to
90       figure out not only the line, but the condition the appropriate state
91       during that test.  In this case, you need to stop at line 114 when $arg
92       is 'plums'.
93
94       Wouldn't it be far better to set a break point in func when the Nth
95       test is reached?  With Test::Inter, you can.
96
97       So for the above script, the debugger commands that you would use to
98       debug the 3rd test are:
99
100          Test::More :   b 109
101          Test::Inter:   b func ($::TI_NUM==3)
102
103       and the 5th test are:
104
105          Test::More :   b 114  ($arg eq 'plums')
106          Test::Inter:   b func ($::TI_NUM==5)
107
108       It would also be nice to be able to skip the first two tests... perhaps
109       they take a long time to run, and I want to get right to work on test
110       3.  You can do this easily too by setting the $::TI_START variable.
111
112       There are some other variables that can be used to specify which test
113       or tests to run described in the "TEST::INTER VARIABLES" section below.
114
115       The other thing I want to do when I run the test scripts interactively
116       is to see more information which will assist in debugging a failed
117       test.
118
119       This can be controlled with variables such as TI_QUIET, TI_MODE, and
120       TI_WIDTH described below in the "TEST::INTER VARIABLES" section.
121

READABLE TESTS

123       The other feature that I wanted in a test suite is the ability to
124       define the tests in a format that is natural and readable FOR THE
125       TESTS.  In almost every case, it is best to think of a test script as
126       consisting of two separate parts: a script part, and a test part.
127
128       The script part of a test script is the least important part! It's
129       usually fairly trivial, rarely needs to be changed, and is not the
130       focus of the test script.
131
132       The tests part of the script IS the important part, and these should be
133       expressed in a form that is natural to them, easy to maintain, easy to
134       read, and easy to modify, and none of these should involve modifying
135       the script portion of the test script in general. Because the content
136       of the tests is the important part of the script, the emphasis should
137       be in making them more readable, even at the expense of the script
138       portion.  As a general rule, if the script portion of the test script
139       obscures the tests in any way, it's not written correctly!
140
141       The solution to this is well understood, and is common to many other
142       systems where you are mixing two "languages".  The task of correctly
143       specifying both the tests and the test script is virtually identical to
144       the task of creating a PHP script which consists of a mixture of PHP
145       and HTML, or the task of creating a template file using some templating
146       system where the file consists of a mixture of text to be displayed and
147       templating commands.  It is well understood in each of these cases that
148       the more the two "languages" are interwoven, the less readable both
149       are, and the harder it is to maintain.  The more you are able to
150       separate the two, the easier both are to read and maintain.
151
152       As often as possible, I want the tests to be written in some sort of
153       text format which can be easily viewed and modified (usually as a
154       simple table) with no perl commands interspersed. I want to the freedom
155       to define the tests in one section (a long string, the DATA section, or
156       even in a separate file) which is easily readable. This may introduce
157       the necessity of parsing it, but it makes it significantly easier to
158       maintain the tests.
159
160       This flexibility makes it much easier to read the tests (as opposed to
161       the script) which is the fundamental content of a test script.
162
163       Looking again at the example test script, you can see that there is far
164       too much perl interspersed with the tests.
165
166       It's difficult to read the tests individually in this script because
167       there is too much perl code among them, and virtually impossible to
168       look at them as a whole.
169
170       It is true that looking at this particular example, it is very
171       simple... but the script ISN'T the content you're interested in (and
172       bear in mind that many test scripts are nowhere near this simple). The
173       REAL content of this script are the tests, which consist of the
174       function arguments and the expected result. Although it's not
175       impossible to see each of these in the script above, it's not in a
176       format that is conducive to studying the tests, and especially not for
177       examining the list of tests as a whole.
178
179       Now, look at an alternate way of specifying the tests using this
180       module:
181
182          $tests = "
183
184            apples     bushels   => enough
185
186            grapefruit tons      => enough
187
188            oranges    boatloads => insufficient
189
190            pears      boxes     => enough
191
192            plums      boxes     => enough
193
194            pineapple  boxes     => enough
195
196          ";
197
198          $o->tests(tests => $tests,
199                    func  => \&func);
200
201       Here, it's easy to see the list of tests, and adding additional tests
202       is a breeze.
203

CREATING A TEST

205       This module supports a number of methods for defining tests, so you can
206       use whichever one is most convenient (including methods that are
207       identical to Test::More if that really is the best method).
208
209       Every test may have several pieces of information:
210
211       A name
212           Every test is automatically assigned a number, but it may be useful
213           to specify a name of a test (which is actually a short description
214           of the test). Whenever a test result is reported, the name will be
215           given (if one was specified).
216
217           The name may not have a '#' in it.
218
219           The name is completely optional, but makes the results more
220           readable.
221
222       An expected result
223           In order to test something, you need to know what result was
224           expected (or in some cases, what result was NOT expected).
225
226       A function and arguments OR a result
227           You also need to know the results that you're comparing to the
228           expected results.
229
230           This can be obtained by simply working with a set of results, or a
231           function name and a set of arguments to pass to it.
232
233       Conditions
234           It is useful to be able to specify state information at the start
235           of the test suite (for example, to see if certain features are
236           available), and some tests may only run if those conditions are
237           met.
238
239           If no conditions are set for a test, it will always run.
240
241       Todo tests
242           Some tests may be marked as 'todo' tests. These are test which are
243           allowed to fail (meaning that they have been put in place for an
244           as-yet unimplemented feature). Since it is expected that the test
245           will fail, the test suite will still pass, even if these tests
246           fail.
247
248           The tests will still run and if they pass, a message is issued
249           saying that the feature is now implemented, and the tests should be
250           graduated to non-todo state.
251

BASE METHODS

253       new
254              $o = new Test::Inter [$name] [%options];
255
256           This creates a new test framework. There are several options which
257           may be used to specify which tests are run, how they are run, and
258           what output is given.
259
260           The entire test script can be named by passing in $name.
261
262           All options can be set in four different ways.
263
264           First, you can pass in a hash of OPT = VAL> pairs in the new
265           method.  So, to set the start option, the %options) hash would
266           contain:
267
268              start => VALUE
269
270           Second, you can set an environment variable.  This will override
271           any value passed in the first way.  The environment variable is
272           named TI_XXX where XXX is the fully capitalized option.  So:
273
274              $ENV{TI_START} = VALUE
275
276           The third method, which overrides the previous two, is to set a
277           global variable.  It is also named TI_XXX in the main namespace, so
278           to set it this way, set:
279
280              $::TI_START = VALUE
281
282           The final method is to call one of the methods below and these
283           override all other methods.
284
285           Each of the allowed options are described below in the following
286           base methods:
287
288              start
289              end
290              testnum
291              plan
292              abort
293              quiet
294              mode
295              skip_all
296              width
297
298       version
299              $o->version();
300
301           Returns the version of the module.
302
303       encoding
304              $o->encoding($encoding);
305
306           $encoding is any value that can be passed as an encoding to perl's
307           Encode::decode function.
308
309           Use this if your test strings contain characters in other
310           encodings.
311
312       start
313              $o = new Test::Inter 'start' => $N;
314              $o->start($N)
315
316           To define which test you want to start with, set the start option
317           as described in the new method above.
318
319           When the start test is defined, most tests numbered less than N are
320           completely ignored. If the tests are being run quietly (see the
321           quiet method below), nothing is printed out for these tests.
322           Otherwise, a skip message is printed out.
323
324           One class of tests IS still executed. Tests run using the
325           require_ok or use_ok methods (to test the loading of modules) are
326           still run.
327
328           If no value (or a value of 0) is used, tests run from the first
329           test.
330
331       end
332              $o = new Test::Inter 'end' => $M;
333              $o->end($M);
334
335           To define which test you want to end with, set the end option as
336           described in the new method above.
337
338           When the end test is defined, all tests numbered more than M are
339           completely ignored. If the tests are being run quietly (see the
340           quiet method below), nothing is printed out for these tests.
341           Otherwise, a skip message is printed out.
342
343           If no value is given, it defaults to 0 (which means that all
344           remaining tests are run).
345
346       testnum
347              $o = new Test::Inter 'testnum' => $N;
348              $o->testnum($N);
349
350           To run only a single test, set the testnum option as described in
351           the new method above.
352
353           It is equivalent to setting both the start and end tests to $N.
354
355       plan
356       done_testing
357              $o = new Test::Inter 'plan' => $N;
358              $o->plan($n);
359
360              $o->done_testing();
361              $o->done_testing($n);
362
363           The TAP API (the 'language' used to run a sequence of tests and see
364           which ones failed and which ones passed) requires a statement of
365           the number of tests that are expected to run.
366
367           This statement can appear at the start of the test suite, or at the
368           end.
369
370           If you know in advance how many tests should run in the test
371           script, you can set the plan option as described in the new method
372           above to the number of tests.
373
374           If you know how many tests should run at the end of the test
375           script, you can pass in a non-zero integer to the done_testing
376           method.
377
378           Frequently, you don't really care how many tests are in the script
379           (especially if new tests are added on a regular basis). In this
380           case, you still need to include a statement that says that the
381           number of tests expected is however many were run. To do this, call
382           the done_testing method with no argument.
383
384           NOTE: if the plan method is used, it MUST be used before any tests
385           are run (including those that test the loading of modules). If the
386           done_testing method is used, it MUST be called after all tests are
387           run. You must specify a plan or use a done_testing statement, but
388           you cannot do both.
389
390           It is NOT strictly required to set a plan if the script is only run
391           interactively, so if for some reason this module is used for test
392           scripts which are not part of a standard perl test suite, the plan
393           and done_testing statements are optional. As a matter of fact, the
394           script will run just fine without them... but a perl installer will
395           report a failure in the test suite.
396
397       abort
398              $o = new Test::Inter 'abort' => 0/1/2;
399              $o->abort(0/1/2);
400
401           To define how you want a failure to be treated, set the abort
402           option as described in the new method above.  The abort option can
403           take a value of 0, 1, or 2.
404
405           If this is set to 1, the test script will run unmodified until a
406           test fails. At that point, all remaining tests will be skipped.  If
407           it is set to 2, the test script will run until a test fails at
408           which point it will exit with an error code of 1.  With a value of
409           0, failed tests will be reported, but the script will continue.
410
411           In both cases, todo tests will NOT trigger the abort behavior.
412
413       quiet
414              $o = new Test::Inter 'quiet' => 0/1/2;
415              $o->quiet(0/1/2);
416
417           To define how you want failures to be reported, set the quiet
418           option as described in the new method above.  The quiet option can
419           take a value of 0, 1, or 2.
420
421           If this is set to 0 (the default), all information will be printed
422           out. If it is set to 1, some optional information will not be
423           printed.  If it is set to 2, all optional information will not be
424           printed.
425
426       mode
427              $o = new Test::Inter 'mode' => MODE;
428              $o->mode(MODE);
429
430           Test::Inter scripts can be run in either an interactive mode, or as
431           part of a test suite with different behaviors.  To select the mode,
432           set the mode option as described in the new method above.  The mode
433           option can take a value of 'inter' or 'test'.
434
435           When run in test mode, it prints out the results using the TAP
436           grammar (i.e. 'ok 1', 'not ok 3', etc.).
437
438           When run in interactive mode, it prints out results in a more human
439           readable format.
440
441       width
442              $o = new Test::Inter 'width' => WIDTH;
443              $o->width(WIDTH);
444
445           The width option can be set as described in the new method above.
446
447           WIDTH is the width of the terminal (for printing out failed test
448           information). It defaults to 80, but it can be set to any width
449           (and lines longer then this are truncated). If WIDTH is set to 0,
450           no truncation is done.
451
452       skip_all
453              $o = new Test::Inter 'skip_all' => REASON;
454              $o->skip_all(REASON);
455
456           The skip_all option can be set as described in the new method
457           above.
458
459           If this is set, the entire test script will be skipped for the
460           reason given. This must be done before any test is run, and before
461           any plan number is set.
462
463           The skip_all can also be called at any point during the script
464           (i.e.  after tests have been run). In this case, all remaining
465           scripts will be skipped.
466
467              $o->skip_all(REASON,FEATURE,FEATURE,...);
468              $o->skip_all('',FEATURE,FEATURE,...);
469
470           This will skip all tests (or all remaining tests) unless all
471           <FEATURE>s are available.  REASON can be entered as an empty string
472           and the reason the tests are skipped will be a message about the
473           missing feature.
474
475       feature
476              $o->feature($feature,$val);
477
478           This defines a feature. If $val is non-zero, the feature is
479           available.  Otherwise it is not.
480
481       diag
482       note
483              $o->diag($message);
484              $o->note($message);
485
486           Both of these print an optional message. Messages printed with the
487           "note" method are always optional and will be omitted if the quiet
488           option is set to 1 or 2. Messages printed with the "diag" method
489           are optional and will not be printed if the quiet option is set to
490           2, but they will be printed if the quiet method is set to 1.
491
492       testdir
493           Occasionally, it may be necessary to know the directory where the
494           tests live (for example, there may be a config or data file in
495           there).  This method will return the directory.
496

METHODS FOR LOADING MODULES

498       Test scripts can load other modules (using either the perl "use" or
499       "require" commands).  There are three different modes for doing this
500       which determine how this is done.
501
502       required
503           By default, this is used to test for a module that is required for
504           all tests in the test script.
505
506           Loading the module is treated as an actual test in the test suite.
507           The test is to determine whether the module is available and can be
508           loaded. If it can be loaded, it is, and it is reported as a
509           successful test. If it cannot be loaded, it is reported as a failed
510           test.
511
512           In the result of a failed test, all remaining tests will be skipped
513           automatically (except for other tests which load modules).
514
515       feature
516           In feature mode, loading the module is not treated as a test (i.e.
517           it will not print out an 'ok' or 'not ok' line. Instead, it will
518           set a feature (named the same as the module) which can be used to
519           determine whether other tests should run or not.
520
521       forbid
522           In a few very rare cases, we may want to test for a module but
523           expect that it not be present. This is the exact opposite of the
524           required mode.
525
526           Successfully loading the module is treated as a test failure. In
527           the event of a failure, all remaining tests will be skipped.
528
529       The methods available are:
530
531       require_ok
532              $o->require_ok($module [,$mode]);
533
534           This is used to load a module using the perl "require" function. If
535           $mode is not passed in, the default mode (required) is used to test
536           the existence of the module.
537
538           If $mode is passed in, it must be either the string 'forbid' or
539           'feature'.
540
541           If $mode is 'feature', a feature named $module is set if the module
542           was able to be loaded.
543
544       use_ok
545              $o->use_ok(@args [,$mode]);
546
547           This is used to load a module with "use", or check a perl version.
548
549              BEGIN { $o->use_ok('5.010'); }
550              BEGIN { $o->use_ok('Some::Module'); }
551              BEGIN { $o->use_ok('Some::Module',2.05); }
552              BEGIN { $o->use_ok('Some::Module','foo','bar'); }
553              BEGIN { $o->use_ok('Some::Module',2.05,'foo','bar'); }
554
555           are the same as:
556
557              use 5.010;
558              use Some::Module;
559              use Some::Module 2.05;
560              use Some::Module qw(foo bar);
561              use Some::Module 2.05 qw(foo bar);
562
563           Putting the use_ok call in a BEGIN block allows the functions to be
564           imported at compile-time and prototypes are properly honored.
565           You'll also need to load the Test::Inter module, and create the
566           object in a BEGIN block.
567
568           $mode acts the same as in the require_ok method.
569

METHODS FOR RUNNING TEST

571       There are several methods for running tests. The ok, is, and isnt
572       methods are included for those already comfortable with Test::More and
573       wishing to stick with the same format of test script. The tests method
574       is the suggested method though since it makes use of the full power of
575       this module.
576
577       ok
578              $o->ok(TESTS);
579
580           A test run with ok looks at a result, and if it evaluates to 0 (or
581           false), it fails. If it evaluates to non-zero (or true), it passes.
582
583           These tests do not require you to specify the expected results.  If
584           expected results are given, they will be compared against the
585           result received, and if they differ, a diagnostic message will be
586           printed, but the test will still succeed or fail based only on the
587           actual result produced.
588
589           These tests require a single result and either zero or one expected
590           results.
591
592           To run a single test, use any of the following:
593
594              $o->ok();          # always succeeds
595
596              $o->ok($result);
597              $o->ok($result,$name);
598              $o->ok($result,$expected,$name);
599
600              $o->ok(\&func);
601              $o->ok(\&func,$name);
602              $o->ok(\&func,$expected,$name);
603
604              $o->ok(\&func,\@args);
605              $o->ok(\&func,\@args,$name);
606              $o->ok(\&func,\@args,$expected,$name);
607
608           If $result is a scalar, the test passes if $result is true. If
609           $result is a list reference, the test succeeds if the list contains
610           any defined values. If $result is a hash reference, the test
611           succeeds if the hash contains any key with a value that is not
612           "undef".
613
614           If "\&func" and "\@args" are passed in, then $result is generated
615           by passing @args to &func and behaves identically to the calls
616           where $result is passed in.  If "\&func" is passed in but no
617           arguments, the function takes no arguments, but still produces a
618           result.
619
620           If an expected value is passed in and the result does not match it,
621           a diagnostic warning will be printed, even if the test passes.
622
623       is
624       isnt
625              $o->is(TESTS);
626              $o->isnt(TESTS);
627
628           A test run with is looks at a result and tests to see if it is
629           identical to an expected result. If it is, the test passes.
630           Otherwise it fails. In the case of a failure, a diagnostic message
631           will show what result was actually obtained and what was expected.
632
633           A test run with isnt looks at a result and tests to see if the
634           result obtained is different than an expected result. If it is
635           different, the test passes.  Otherwise it fails.
636
637           The is method can be called in any of the following ways:
638
639              $o->is($result,$expected);
640              $o->is($result,$expected,$name);
641
642              $o->is(\&func,$expected);
643              $o->is(\&func,$expected,$name);
644
645              $o->is(\&func,\@args,$expected);
646              $o->is(\&func,\@args,$expected,$name);
647
648           The isnt method can be called in exactly the same way.
649
650           As with the ok method, the result can be a scalar, hashref, or
651           listref. If it is a hashref or listref, the entire structure must
652           match the expected value.
653
654       tests
655              $o->tests($opt=>$val, $opt=>$val, ...)
656
657           The options available are described in the following section.
658
659       file
660              $o->file($func,$input,$outputdir,$expected,$name [,@args]);
661
662           Sometimes it may be easiest to store the input, output, and
663           expected output from a test in a text file. In this case, each line
664           of output will be treated as a single test, so the output and
665           expected output must match up exactly.
666
667           $func is a reference to a function which will produce a temporary
668           output file.
669
670           If $input is specified, it is the name of the input file.  If it is
671           empty, no input file will be used.  The input file can be fully
672           specified, or it can be relative to the test directory.
673
674           If $outputdir is passed in, it is the directory where the output
675           file will be written.  It can be fully specified, or relative to
676           the test directory.  If $outputdir is left blank, the temporary
677           file will be written to the test directory.
678
679           $expected is the name of a file which contains the expected output.
680           It can be fully specified, or it will be checked for in the test
681           directory.
682
683           $name is the name of this series of tests.
684
685           @args are extra arguments to pass to the test function.
686
687           The function will be called with the arguments:
688
689              &$func( [$input,] $output,@args);
690
691           $input is only passed in if it was passed in to this method.  If no
692           input file is specified, nothing will be passed to the function.
693
694           $output is the name of a temporary file where the output will be
695           written to.
696

USING THE TESTS METHOD

698       It is expected that most tests (except for those that load a module)
699       will be run using the tests method called as:
700
701          $o->tests(%options);
702
703       The following options are available:
704
705       name
706              name => NAME
707
708           This sets the name of this set of tests. All tests will be given
709           the same name.
710
711       tests
712       func
713       expected
714           In order to specify a series of tests, you have to specify either a
715           function and a list of arguments, or a list of results.
716
717           Specifying the function and list of arguments can be done using the
718           pair:
719
720              func  => \&FUNCTION
721              tests => TESTS
722
723           If the func option is not set, tests contains a list of results.
724
725           A list of expected results may also be given. They can be included
726           in the
727
728              tests => TESTS
729
730           option or included separately as:
731
732              expected => RESULTS
733
734           The way to specify these are covered in the next section SPECIFYING
735           THE TESTS.
736
737       feature
738       disable
739              feature => [FEATURE1, FEATURE2, ...]
740
741              disable => [FEATURE1, FEATURE2, ...]
742
743           The default set of tests to run is determined using the start, end,
744           and skip_all methods discussed above. Using those methods, a list
745           of tests is obtained, and it is expected that these will run.
746
747           The feature and disable options modify the list.
748
749           If the feature option is included, the tests given in this call
750           will only run if ALL of the features listed are available.
751
752           If the disable option is included, the tests will be run unless ANY
753           of the features listed are available.
754
755       skip
756              skip => REASON
757
758           Skip these tests for the reason given.
759
760       todo
761              todo => 0/1
762
763           Setting this to 1 says that these tests are allowed to fail. They
764           represent a feature that is not yet implemented.
765
766           If the tests succeed, a message will be printed notifying the
767           developer that the tests are now ready to promote to actual use.
768

SPECIFYING THE TESTS

770       A series of tests can be specified in two different ways. The tests can
771       be written in a very simple string format, or stored as a list.
772
773       Demonstrating how this can be done is best done by example, so let's
774       say that there is a function (func) which takes two arguments, and
775       returns a single value.  Let's say that the expected output (and the
776       actual output) from 3 different sets of arguments is:
777
778          Input   Expected Output  Actual Output
779          -----   ---------------  -------------
780          1,2     a                a
781          3,4     b                x
782          5,6     c                c
783
784       (so in this case, the first and third tests pass, but the 2nd one will
785       fail).
786
787       Specifying these tests as lists could be done as:
788
789          $o->tests(
790             func     => &func,
791             tests    => [ [1,2], [3,4], [5,6] ],
792             expected => [ [a],   [b],   [c] ],
793          );
794
795       Here, the tests are stored as a list, and each element in the list is a
796       listref containing the set of arguments.
797
798       If the func option is not passed in, the tests option is set to a list
799       of results to compare with the expected results, so the following is
800       equivalent to the above:
801
802          $o->tests(
803             tests    => [ [a],   [x],   [c] ],
804             expected => [ [a],   [b],   [c] ],
805          );
806
807       If an argument (or actual result) or an expected result is only a
808       single value, it can be entered as a scalar instead of a list ref, so
809       the following is also equivalent:
810
811          $o->tests(
812             func     => &func,
813             tests    => [ [1,2], [3,4], [5,6] ],
814             expected => [ a,     b,     [c] ],
815          );
816
817       The only exception to this is if the single value is itself a list
818       reference.  In this case it MUST be included as a reference. In other
819       words, if you have a single test, and the expected value for this test
820       is a list reference, it must be passed in as:
821
822          expected => [ [ \@r ] ]
823
824       NOT as:
825
826          expected => [ \@r ]
827
828       Passing in a set of expected results is optional. If none are passed
829       in, the tests are treated as if they had been passed to the ok method
830       (i.e. if they return something true, they pass, otherwise they fail).
831
832       The second way to specify tests is as a string. The string is a multi-
833       line string with each tests being separate from the next test by a
834       blank line.  Comments (lines which begin with '#') are allowed, and are
835       ignored. Whitespace at the start and end of the line is ignored.
836
837       The string may contain the results directly, or results may be passed
838       in separately. For example, the following all give the same sets of
839       tests as the example above:
840
841          $o->tests(
842             func     => &func,
843             tests    => "
844                          # Test 1
845                          1 2 => a
846
847                          # Test 2
848                          3 4 => b
849
850                          5 6 => c
851                         ",
852          );
853
854          $o->tests(
855             func     => &func,
856             tests    => "
857                          1 2
858
859                          3 4
860
861                          5 6
862                         ",
863              expected => [ [a], [b], [c] ]
864          );
865
866          $o->tests(
867             func     => &func,
868             tests    => [ [1,2], [3,4], [5,6] ],
869             expected => "
870                          a
871
872                          b
873
874                          c
875                         ",
876          );
877
878          $o->tests(
879             func     => &func,
880             tests    => "
881                          1 2
882
883                          3 4
884
885                          5 6
886                         ",
887             expected => "
888                          a
889
890                          b
891
892                          c
893                         ",
894          );
895
896       The expected results may also consist of only a single set of results
897       (in this case, it must be passed in as a listref). In this case, all of
898       the tests are expected to have the same results.
899
900       So, the following are equivalent:
901
902          $o->tests(
903             func     => &func,
904             tests    => "
905                          1 2 => a b
906
907                          3 4 => a b
908
909                          5 6 => a b
910                         ",
911          );
912
913          $o->tests(
914             func     => &func,
915             tests    => "
916                          1 2
917
918                          3 4
919
920                          5 6
921                         ",
922             expected  => [ [a, b] ],
923          );
924
925          $o->tests(
926             func     => &func,
927             tests    => "
928                          1 2
929
930                          3 4
931
932                          5 6
933                         ",
934             expected  => "a b",
935          );
936
937       The number of expected values must either be 1 (i.e. all of the tests
938       are expected to produce the same value) or exactly the same number as
939       the number of tests.
940
941       The parser is actually quite powerful, and can handle multi-line tests,
942       quoted strings, and nested data structures.
943
944       The test may be split across any number of lines, provided there is not
945       a completely blank line (which signals the end of the test), so the
946       following are equivalent:
947
948          tests => "a b c",
949          tests => "a b
950                    c",
951
952       Arguments (or expected results) may include data structures. For
953       example, the following are equivalent:
954
955          tests => "[ a b ] { a 1 b 2 }"
956          tests => [ [ [a,b], { a=>1, b=>2 } ] ]
957
958       Whitespace is mostly optional, but there is one exception. An item must
959       end with some kind of delimiter, so the following will fail:
960
961          tests => "[a b][c d]"
962
963       The first element (the list ref [a b]) must be separated from the
964       second element by the delimiter (which is whitespace in this case), so
965       it must be written as:
966
967          tests => "[a b] [c d]"
968
969       As already demonstrated, hashrefs and listrefs may be included and
970       nested. Elements may also be included inside parens, but this is
971       optional since all arguments and expected results are already treated
972       as lists, so the following are equivalent:
973
974          tests => "a b c"
975          tests => "(a b) c"
976
977       Although parens are optional, they may make things more readable, and
978       allow you to use something other than whitespace as the delimiter.
979       Since parens are actually ignored, a string '()' is also ignored, so do
980       not use empty parentheses.
981
982       If the character immediately following the opening paren, brace, or
983       bracket is a punctuation mark, then it is used as the delimiter instead
984       of whitespace. For example, the following are all equivalent:
985
986          [ a b c ]
987          [a b c]
988          [, a,b,c ]
989          [, a, b, c ]
990
991       A delimiter is a single character, and the following may not be used as
992       a delimiter:
993
994          any opening/closing characters () [] {}
995          single or double quotes
996          alphanumeric characters
997          underscore
998
999       Whitespace (including newlines) around the delimiter is ignored, so the
1000       following is valid:
1001
1002          [, a,
1003             b,
1004             c ]
1005
1006       Two delimiters next to each other or a trailing delimiter produce an
1007       empty string.
1008
1009          "(,a,b,)" => (a, b, '')
1010          "(,a,,b)" => (a, '', b)
1011
1012       Hashrefs may be specified by braces and the following are equivalent:
1013
1014          { a 1 b 2 }
1015          {, a,1,b,2 }
1016          {, a,1,b,2, }
1017
1018       Note that a trailing delimiter is ignored if there are already an even
1019       number of elements, or an empty string otherwise.
1020
1021       Nested structures are allowed:
1022
1023          "[ [1 2] [3 4] ]"
1024
1025       For example,
1026
1027          $o->tests(
1028             func     => &func,
1029             tests    => "a [ b c ] { d 1 e 2 } => x y"
1030          );
1031
1032       is equivalent to:
1033
1034          $o->tests(
1035             func     => &func,
1036             tests    => [ [a, [b,c], {d=>1,e=>2}] ],
1037             results  => [ [x,y] ],
1038          );
1039
1040       Any single value can be surrounded by single or double quotes in order
1041       to include the delimiter. So:
1042
1043          "(, a,'b,c',e )"
1044
1045       is equivalent to:
1046
1047          "( a b,c e )"
1048
1049       Any single value can be the string '__undef__' which will be turned
1050       into an actual undef. If the value is '__blank__' it is turned into an
1051       empty string (''), though it can also be specified as '' directly. Any
1052       value can have an embedded newline by including a __nl__ in the value,
1053       but the value must be written on a single line.
1054
1055       Expected results are separated from arguments by ' => '.
1056

TEST::INTER VARIABLES

1058       To summarize the information above, the following variables are used by
1059       Test::Inter.  Each variable can be set in two different ways: as an
1060       environment variable and as a perl variable in the main namespace.
1061
1062       For example, the TI_END variable can be set as:
1063
1064          $::TI_END
1065          $ENV{TI_END}
1066
1067       The following variables can be used to define which tests are run:
1068
1069       TI_START
1070           Set this to define the test you want to start with.
1071
1072           Example: If you have a perl test script and you want to start
1073           running it at test 12, run the following shell commands:
1074
1075              TI_START=12
1076              ./my_test_script.t
1077
1078       TI_END
1079           Set this to define the test you want to end with.
1080
1081       TI_TESTNUM
1082           Set this to run only a single test
1083
1084       There is also a variable TI_NUM (available only as $::TI_NUM) which is
1085       set automatically by Test::Inter to be the test currently being run.
1086
1087       The following variables control what is output from the tests, and how
1088       it is formatted:
1089
1090       TI_QUIET
1091           How verbose the test script is.
1092
1093       TI_MODE
1094           How the output is formatted.
1095
1096       TI_WIDTH
1097           The width of the terminal.
1098
1099       The following variables control how some tests are run:
1100
1101       TI_NOCLEAN
1102           When running a file test, the temporary output file will not be
1103           removed if this is set.
1104

HISTORY

1106       The history of this module dates back to 1996 when I needed to write a
1107       test suite for my Date::Manip module. At that time, none of the Test::*
1108       modules currently available in CPAN existed (the earliest ones didn't
1109       come along until 1998), so I was left completely on my own writing my
1110       test scripts.
1111
1112       I wrote a very basic version of my test framework which allowed me to
1113       write all of the tests as a string, it would parse the string, count
1114       the tests, and then run them.
1115
1116       Over the years, the functionality I wanted grew, and periodically, I'd
1117       go back and reexamine other Test frameworks (primarily Test::More) to
1118       see if I could replace my framework with an existing module... and I've
1119       always found them wanting, and chosen to extend my existing framework
1120       instead.
1121
1122       As I've written other modules, I've wanted to use the framework in them
1123       too, so I've always just copied it in, but this is obviously tedious
1124       and error prone. I'm not sure why it took me so long... but in 2010, I
1125       finally decided it was time to rework the framework in a module form.
1126
1127       I loosely based my module on Test::More. I like the functionality of
1128       that module, and wanted most of it (and I plan on adding more in future
1129       versions).  So this module uses some similar syntax to Test::More
1130       (though it allows a great deal more flexibility in how the tests are
1131       specified).
1132
1133       One thing to note is that I may have been able to write this module as
1134       an extension to Test::More, but after looking into that possibility, I
1135       decided that it would be faster to not do that. I did "borrow" a couple
1136       of routines from it (though they've been modified quite heavily) as a
1137       starting point for a few of the functions in this module, and I thank
1138       the authors of Test::More for their work.
1139

KNOWN BUGS AND LIMITATIONS

1141       None known.
1142

SEE ALSO

1144       Test::More - the 'industry standard' of perl test frameworks
1145

BUGS AND QUESTIONS

1147       If you find a bug in Test::Inter, there are three ways to send it to
1148       me.  Any of them are fine, so use the method that is easiest for you.
1149
1150       Direct email
1151           You are welcome to send it directly to me by email.  The email
1152           address to use is:  sbeck@cpan.org.
1153
1154       CPAN Bug Tracking
1155           You can submit it using the CPAN tracking too.  This can be done at
1156           the following URL:
1157
1158           <http://rt.cpan.org/Public/Dist/Display.html?Name=Test-Inter>
1159
1160       GitHub
1161           You can submit it as an issue on GitHub.  This can be done at the
1162           following URL:
1163
1164           <https://github.com/SBECK-github/Test-Inter>
1165
1166       Please do not use other means to report bugs (such as forums for a
1167       specific OS or Linux distribution) as it is impossible for me to keep
1168       up with all of them.
1169
1170       When filing a bug report, please include the following information:
1171
1172       Test::Inter version
1173           Please include the version of Test::Inter you are using.  You can
1174           get this by using the script:
1175
1176              use Test::Inter;
1177              print $Test::Inter::VERSION,"\n";
1178
1179       If you want to report missing or incorrect codes, you must be running
1180       the most recent version of Test::Inter.
1181
1182       If you find any problems with the documentation (errors, typos, or
1183       items that are not clear), please send them to me. I welcome any
1184       suggestions that will allow me to improve the documentation.
1185

LICENSE

1187       This script is free software; you can redistribute it and/or modify it
1188       under the same terms as Perl itself.
1189

AUTHOR

1191       Sullivan Beck (sbeck@cpan.org)
1192
1193
1194
1195perl v5.28.0                      2018-03-15                    Test::Inter(3)
Impressum