1Test::Base(3) User Contributed Perl Documentation Test::Base(3)
2
3
4
6 Test::Base - A Data Driven Testing Framework
7
9 A new test module:
10
11 # lib/MyProject/Test.pm
12 package MyProject::Test;
13 use Test::Base -Base;
14
15 use MyProject;
16
17 package MyProject::Test::Filter;
18 use Test::Base::Filter -base;
19
20 sub my_filter {
21 return MyProject->do_something(shift);
22 }
23
24 A sample test:
25
26 # t/sample.t
27 use MyProject::Test;
28
29 plan tests => 1 * blocks;
30
31 run_is input => 'expected';
32
33 sub local_filter {
34 s/my/your/;
35 }
36
37 __END__
38
39 === Test one (the name of the test)
40 --- input my_filter local_filter
41 my
42 input
43 lines
44 --- expected
45 expected
46 output
47
48 === Test two
49 This is an optional description
50 of this particular test.
51 --- input my_filter
52 other
53 input
54 lines
55 --- expected
56 other expected
57 output
58
60 Testing is usually the ugly part of Perl module authoring. Perl gives
61 you a standard way to run tests with Test::Harness, and basic testing
62 primitives with Test::More. After that you are pretty much on your own
63 to develop a testing framework and philosophy. Test::More encourages
64 you to make your own framework by subclassing Test::Builder, but that
65 is not trivial.
66
67 Test::Base gives you a way to write your own test framework base class
68 that is trivial. In fact it is as simple as two lines:
69
70 package MyTestFramework;
71 use Test::Base -Base;
72
73 A module called "MyTestFramework.pm" containing those two lines, will
74 give all the power of Test::More and all the power of Test::Base to
75 every test file that uses it. As you build up the capabilities of
76 "MyTestFramework", your tests will have all of that power as well.
77
78 "MyTestFramework" becomes a place for you to put all of your reusable
79 testing bits. As you write tests, you will see patterns and
80 duplication, and you can "upstream" them into "MyTestFramework". Of
81 course, you don't have to subclass Test::Base at all. You can use it
82 directly in many applications, including everywhere you would use
83 Test::More.
84
85 Test::Base concentrates on offering reusable data driven patterns, so
86 that you can write tests with a minimum of code. At the heart of all
87 testing you have inputs, processes and expected outputs. Test::Base
88 provides some clean ways for you to express your input and expected
89 output data, so you can spend your
90
91 time focusing on that rather than your code scaffolding.
92
94 Test::Base extends Test::More and exports all of its functions. So you
95 can basically write your tests the same as Test::More. Test::Base also
96 exports many functions of its own:
97
98 "is(actual, expected, [test-name])"
99 This is the equivalent of Test::More's "is" function with one
100 interesting twist. If your actual and expected results differ and
101 the output is multi- line, this function will show you a unified
102 diff format of output. Consider the benefit when looking for the
103 one character that is different in hundreds of lines of output!
104
105 Diff output requires the optional "Text::Diff" CPAN module. If you
106 don't have this module, the "is()" function will simply give you
107 normal Test::More output. To disable diffing altogether, set the
108 "TEST_SHOW_NO_DIFFS" environment variable (or
109 $ENV{TEST_SHOW_NO_DIFFS}) to a true value. You can also call the
110 "no_diff" function as a shortcut.
111
112 "blocks( [data-section-name] )"
113 The most important function is "blocks". In list context it returns
114 a list of "Test::Base::Block" objects that are generated from the
115 test specification in the "DATA" section of your test file. In
116 scalar context it returns the number of objects. This is useful to
117 calculate your Test::More plan.
118
119 Each Test::Base::Block object has methods that correspond to the
120 names of that object's data sections. There is also a "name" and a
121 "description" method for accessing those parts of the block if they
122 were specified.
123
124 The "blocks" function can take an optional single argument, that
125 indicates to only return the blocks that contain a particular named
126 data section. Otherwise "blocks" returns all blocks.
127
128 my @all_of_my_blocks = blocks;
129
130 my @just_the_foo_blocks = blocks('foo');
131
132 "next_block()"
133 You can use the next_block function to iterate over all the blocks.
134
135 while (my $block = next_block) {
136 ...
137 }
138
139 It returns undef after all blocks have been iterated over. It can
140 then be called again to reiterate.
141
142 "first_block()"
143 Returns the first block or undef if there are none. It resets the
144 iterator to the "next_block" function.
145
146 "run(&subroutine)"
147 There are many ways to write your tests. You can reference each
148 block individually or you can loop over all the blocks and perform
149 a common operation. The "run" function does the looping for you, so
150 all you need to do is pass it a code block to execute for each
151 block.
152
153 The "run" function takes a subroutine as an argument, and calls the
154 sub one time for each block in the specification. It passes the
155 current block object to the subroutine.
156
157 run {
158 my $block = shift;
159 is(process($block->foo), $block->bar, $block->name);
160 };
161
162 "run_is([data_name1, data_name2])"
163 Many times you simply want to see if two data sections are
164 equivalent in every block, probably after having been run through
165 one or more filters. With the "run_is" function, you can just pass
166 the names of any two data sections that exist in every block, and
167 it will loop over every block comparing the two sections.
168
169 run_is 'foo', 'bar';
170
171 If no data sections are given "run_is" will try to detect them
172 automatically.
173
174 NOTE: Test::Base will silently ignore any blocks that don't contain
175 both sections.
176
177 "is_deep($data1, $data2, $test_name)"
178 Like Test::More's "is_deeply" but uses the more correct Test::Deep
179 module.
180
181 "run_is_deeply([data_name1, data_name2])"
182 Like "run_is_deeply" but uses "is_deep" which uses the more correct
183 Test::Deep.
184
185 "run_is_deeply([data_name1, data_name2])"
186 Like "run_is" but uses "is_deeply" for complex data structure
187 comparison.
188
189 "run_is_deeply([data_name1, data_name2])"
190 Like "run_is_deeply" but uses "is_deep" which uses the more correct
191 Test::Deep.
192
193 "run_like([data_name, regexp | data_name]);"
194 The "run_like" function is similar to "run_is" except the second
195 argument is a regular expression. The regexp can either be a "qr{}"
196 object or a data section that has been filtered into a regular
197 expression.
198
199 run_like 'foo', qr{<html.*};
200 run_like 'foo', 'match';
201
202 "run_unlike([data_name, regexp | data_name]);"
203 The "run_unlike" function is similar to "run_like", except the
204 opposite.
205
206 run_unlike 'foo', qr{<html.*};
207 run_unlike 'foo', 'no_match';
208
209 "run_compare(data_name1, data_name2)"
210 The "run_compare" function is like the "run_is", "run_is_deeply"
211 and the "run_like" functions all rolled into one. It loops over
212 each relevant block and determines what type of comparison to do.
213
214 NOTE: If you do not specify either a plan, or run any tests, the
215 "run_compare" function will automatically be run.
216
217 "delimiters($block_delimiter, $data_delimiter)"
218 Override the default delimiters of "===" and "---".
219
220 "spec_file($file_name)"
221 By default, Test::Base reads its input from the DATA section. This
222 function tells it to get the spec from a file instead.
223
224 "spec_string($test_data)"
225 By default, Test::Base reads its input from the DATA section. This
226 function tells it to get the spec from a string that has been
227 prepared somehow.
228
229 "filters( @filters_list or $filters_hashref )"
230 Specify a list of additional filters to be applied to all blocks.
231 See "FILTERS" below.
232
233 You can also specify a hash ref that maps data section names to an
234 array ref of filters for that data type.
235
236 filters {
237 xxx => [qw(chomp lines)],
238 yyy => ['yaml'],
239 zzz => 'eval',
240 };
241
242 If a filters list has only one element, the array ref is optional.
243
244 "filters_delay( [1 | 0] );"
245 By default Test::Base::Block objects are have all their filters run
246 ahead of time. There are testing situations in which it is
247 advantageous to delay the filtering. Calling this function with no
248 arguments or a true value, causes the filtering to be delayed.
249
250 use Test::Base;
251 filters_delay;
252 plan tests => 1 * blocks;
253 for my $block (blocks) {
254 ...
255 $block->run_filters;
256 ok($block->is_filtered);
257 ...
258 }
259
260 In the code above, the filters are called manually, using the
261 "run_filters" method of Test::Base::Block. In functions like
262 "run_is", where the tests are run automatically, filtering is
263 delayed until right before the test.
264
265 "filter_arguments()"
266 Return the arguments after the equals sign on a filter.
267
268 sub my_filter {
269 my $args = filter_arguments;
270 # is($args, 'whazzup');
271 ...
272 }
273
274 __DATA__
275 === A test
276 --- data my_filter=whazzup
277
278 "tie_output()"
279 You can capture STDOUT and STDERR for operations with this
280 function:
281
282 my $out = '';
283 tie_output(*STDOUT, $out);
284 print "Hey!\n";
285 print "Che!\n";
286 untie *STDOUT;
287 is($out, "Hey!\nChe!\n");
288
289 "no_diff()"
290 Turn off diff support for is() in a test file.
291
292 "default_object()"
293 Returns the default Test::Base object. This is useful if you feel
294 the need to do an OO operation in otherwise functional test code.
295 See OO below.
296
297 "WWW() XXX() YYY() ZZZ()"
298 These debugging functions are exported from the Spiffy.pm module.
299 See Spiffy for more info.
300
301 "croak() carp() cluck() confess()"
302 You can use the functions from the Carp module without needing to
303 import them. Test::Base does it for you by default.
304
306 Test::Base allows you to specify your test data in an external file,
307 the DATA section of your program or from a scalar variable containing
308 all the text input.
309
310 A test specification is a series of text lines. Each test (or block) is
311 separated by a line containing the block delimiter and an optional test
312 "name". Each block is further subdivided into named sections with a
313 line containing the data delimiter and the data section name. A
314 "description" of the test can go on lines after the block delimiter but
315 before the first data section.
316
317 Here is the basic layout of a specification:
318
319 === <block name 1>
320 <optional block description lines>
321 --- <data section name 1> <filter-1> <filter-2> <filter-n>
322 <test data lines>
323 --- <data section name 2> <filter-1> <filter-2> <filter-n>
324 <test data lines>
325 --- <data section name n> <filter-1> <filter-2> <filter-n>
326 <test data lines>
327
328 === <block name 2>
329 <optional block description lines>
330 --- <data section name 1> <filter-1> <filter-2> <filter-n>
331 <test data lines>
332 --- <data section name 2> <filter-1> <filter-2> <filter-n>
333 <test data lines>
334 --- <data section name n> <filter-1> <filter-2> <filter-n>
335 <test data lines>
336
337 Here is a code example:
338
339 use Test::Base;
340
341 delimiters qw(### :::);
342
343 # test code here
344
345 __END__
346
347 ### Test One
348 We want to see if foo and bar
349 are really the same...
350 ::: foo
351 a foo line
352 another foo line
353
354 ::: bar
355 a bar line
356 another bar line
357
358 ### Test Two
359
360 ::: foo
361 some foo line
362 some other foo line
363
364 ::: bar
365 some bar line
366 some other bar line
367
368 ::: baz
369 some baz line
370 some other baz line
371
372 This example specifies two blocks. They both have foo and bar data
373 sections. The second block has a baz component. The block delimiter is
374 "###" and the data delimiter is ":::".
375
376 The default block delimiter is "===" and the default data delimiter is
377 "--- ".
378
379 There are some special data section names used for control purposes:
380
381 --- SKIP
382 --- ONLY
383 --- LAST
384
385 A block with a SKIP section causes that test to be ignored. This is
386 useful to disable a test temporarily.
387
388 A block with an ONLY section causes only that block to be used. This is
389 useful when you are concentrating on getting a single test to pass. If
390 there is more than one block with ONLY, the first one will be chosen.
391
392 Because ONLY is very useful for debugging and sometimes you forgot to
393 remove the ONLY flag before committing to the VCS or uploading to CPAN,
394 Test::Base by default gives you a diag message saying I found ONLY ...
395 maybe you're debugging?. If you don't like it, use "no_diag_on_only".
396
397 A block with a LAST section makes that block the last one in the
398 specification. All following blocks will be ignored.
399
401 The real power in writing tests with Test::Base comes from its
402 filtering capabilities. Test::Base comes with an ever growing set of
403 useful generic filters than you can sequence and apply to various test
404 blocks. That means you can specify the block serialization in the most
405 readable format you can find, and let the filters translate it into
406 what you really need for a test. It is easy to write your own filters
407 as well.
408
409 Test::Base allows you to specify a list of filters to each data section
410 of each block. The default filters are "norm" and "trim". These filters
411 will be applied (in order) to the data after it has been parsed from
412 the specification and before it is set into its Test::Base::Block
413 object.
414
415 You can add to the default filter list with the "filters" function. You
416 can specify additional filters to a specific block by listing them
417 after the section name on a data section delimiter line.
418
419 Example:
420
421 use Test::Base;
422
423 filters qw(foo bar);
424 filters { perl => 'strict' };
425
426 sub upper { uc(shift) }
427
428 __END__
429
430 === Test one
431 --- foo trim chomp upper
432 ...
433
434 --- bar -norm
435 ...
436
437 --- perl eval dumper
438 my @foo = map {
439 - $_;
440 } 1..10;
441 \ @foo;
442
443 Putting a "-" before a filter on a delimiter line, disables that
444 filter.
445
446 Scalar vs List
447 Each filter can take either a scalar or a list as input, and will
448 return either a scalar or a list. Since filters are chained together,
449 it is important to learn which filters expect which kind of input and
450 return which kind of output.
451
452 For example, consider the following filter list:
453
454 norm trim lines chomp array dumper eval
455
456 The data always starts out as a single scalar string. "norm" takes a
457 scalar and returns a scalar. "trim" takes a list and returns a list,
458 but a scalar is a valid list. "lines" takes a scalar and returns a
459 list. "chomp" takes a list and returns a list. "array" takes a list and
460 returns a scalar (an anonymous array reference containing the list
461 elements). "dumper" takes a list and returns a scalar. "eval" takes a
462 scalar and creates a list.
463
464 A list of exactly one element works fine as input to a filter requiring
465 a scalar, but any other list will cause an exception. A scalar in list
466 context is considered a list of one element.
467
468 Data accessor methods for blocks will return a list of values when used
469 in list context, and the first element of the list in scalar context.
470 This is usually "the right thing", but be aware.
471
472 The Stock Filters
473 Test::Base comes with large set of stock filters. They are in the
474 "Test::Base::Filter" module. See Test::Base::Filter for a listing and
475 description of these filters.
476
477 Rolling Your Own Filters
478 Creating filter extensions is very simple. You can either write a
479 function in the "main" namespace, or a method in the
480 "Test::Base::Filter" namespace or a subclass of it. In either case the
481 text and any extra arguments are passed in and you return whatever you
482 want the new value to be.
483
484 Here is a self explanatory example:
485
486 use Test::Base;
487
488 filters 'foo', 'bar=xyz';
489
490 sub foo {
491 transform(shift);
492 }
493
494 sub Test::Base::Filter::bar {
495 my $self = shift; # The Test::Base::Filter object
496 my $data = shift;
497 my $args = $self->current_arguments;
498 my $current_block_object = $self->block;
499 # transform $data in a barish manner
500 return $data;
501 }
502
503 If you use the method interface for a filter, you can access the block
504 internals by calling the "block" method on the filter object.
505
506 Normally you'll probably just use the functional interface, although
507 all the builtin filters are methods.
508
509 Note that filters defined in the "main" namespace can look like:
510
511 sub filter9 {
512 s/foo/bar/;
513 }
514
515 since Test::Base automatically munges the input string into $_ variable
516 and checks the return value of the function to see if it looks like a
517 number. If you must define a filter that returns just a single number,
518 do it in a different namespace as a method. These filters don't allow
519 the simplistic $_ munging.
520
522 Test::Base has a nice functional interface for simple usage. Under the
523 hood everything is object oriented. A default Test::Base object is
524 created and all the functions are really just method calls on it.
525
526 This means if you need to get fancy, you can use all the object
527 oriented stuff too. Just create new Test::Base objects and use the
528 functions as methods.
529
530 use Test::Base;
531 my $blocks1 = Test::Base->new;
532 my $blocks2 = Test::Base->new;
533
534 $blocks1->delimiters(qw(!!! @@@))->spec_file('test1.txt');
535 $blocks2->delimiters(qw(### $$$))->spec_string($test_data);
536
537 plan tests => $blocks1->blocks + $blocks2->blocks;
538
539 # ... etc
540
542 In Test::Base, blocks are exposed as Test::Base::Block objects. This
543 section lists the methods that can be called on a Test::Base::Block
544 object. Of course, each data section name is also available as a
545 method.
546
547 "name()"
548 This is the optional short description of a block, that is
549 specified on the block separator line.
550
551 "description()"
552 This is an optional long description of the block. It is the text
553 taken from between the block separator and the first data section.
554
555 "seq_num()"
556 Returns a sequence number for this block. Sequence numbers begin
557 with 1.
558
559 "blocks_object()"
560 Returns the Test::Base object that owns this block.
561
562 "run_filters()"
563 Run the filters on the data sections of the blocks. You don't need
564 to use this method unless you also used the "filters_delay"
565 function.
566
567 "is_filtered()"
568 Returns true if filters have already been run for this block.
569
570 "original_values()"
571 Returns a hash of the original, unfiltered values of each data
572 section.
573
575 One of the nicest things about Test::Base is that it is easy to
576 subclass. This is very important, because in your personal project, you
577 will likely want to extend Test::Base with your own filters and other
578 reusable pieces of your test framework.
579
580 Here is an example of a subclass:
581
582 package MyTestStuff;
583 use Test::Base -Base;
584
585 our @EXPORT = qw(some_func);
586
587 sub some_func {
588 (my ($self), @_) = find_my_self(@_);
589 ...
590 }
591
592 package MyTestStuff::Block;
593 use base 'Test::Base::Block';
594
595 sub desc {
596 $self->description(@_);
597 }
598
599 package MyTestStuff::Filter;
600 use base 'Test::Base::Filter';
601
602 sub upper {
603 $self->assert_scalar(@_);
604 uc(shift);
605 }
606
607 Note that you don't have to re-Export all the functions from
608 Test::Base. That happens automatically, due to the powers of Spiffy.
609
610 The first line in "some_func" allows it to be called as either a
611 function or a method in the test code.
612
614 You might be thinking that you do not want to use Test::Base in you
615 modules, because it adds an installation dependency. Fear not.
616 Module::Install::TestBase takes care of that.
617
618 Just write a Makefile.PL that looks something like this:
619
620 use inc::Module::Install;
621
622 name 'Foo';
623 all_from 'lib/Foo.pm';
624
625 use_test_base;
626
627 WriteAll;
628
629 The line with "use_test_base" will automatically bundle all the code
630 the user needs to run Test::Base based tests.
631
633 Test::Base automatically adds:
634
635 use strict;
636 use warnings;
637
638 to all of your test scripts and Test::Base subclasses. A Spiffy feature
639 indeed.
640
642 This module started its life with the horrible and ridicule inducing
643 name "Test::Chunks". It was renamed to "Test::Base" with the hope that
644 it would be seen for the very useful module that it has become. If you
645 are switching from "Test::Chunks" to "Test::Base", simply substitute
646 the concept and usage of "chunks" to "blocks".
647
649 Ingy döt Net <ingy@cpan.org>
650
652 Copyright 2005-2018. Ingy döt Net.
653
654 This program is free software; you can redistribute it and/or modify it
655 under the same terms as Perl itself.
656
657 See <http://www.perl.com/perl/misc/Artistic.html>
658
659
660
661perl v5.36.0 2022-07-22 Test::Base(3)