1Test::Base(3) User Contributed Perl Documentation Test::Base(3)
2
6 Test::Base - A Data Driven Testing Framework
7
9 A new test module:
10 # lib/MyProject/Test.pm
12 package MyProject::Test;
13 use Test::Base -Base;
14 use MyProject;
16 package MyProject::Test::Filter;
18 use Test::Base::Filter -base;
19 sub my_filter {
21 return MyProject->do_something(shift);
22 }
23 A sample test:
25 # t/sample.t
27 use MyProject::Test;
28 plan tests => 1 * blocks;
30 run_is input => 'expected';
32 sub local_filter {
34 s/my/your/;
35 }
36 __END__
38 === 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 === 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 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 package MyTestFramework;
71 use Test::Base -Base;
72 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 "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 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 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 "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 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 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 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 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 my @all_of_my_blocks = blocks;
129 my @just_the_foo_blocks = blocks('foo');
131 next_block()
133 You can use the next_block function to iterate over all the blocks.
134 while (my $block = next_block) {
136 ...
137 }
138 It returns undef after all blocks have been iterated over. It can
140 then be called again to reiterate.
141 first_block()
143 Returns the first block or undef if there are none. It resets the
144 iterator to the "next_block" function.
145 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 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 run {
158 my $block = shift;
159 is(process($block->foo), $block->bar, $block->name);
160 };
161 "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 run_is 'foo', 'bar';
170 If no data sections are given "run_is" will try to detect them
172 automatically.
173 NOTE: Test::Base will silently ignore any blocks that don't contain
175 both sections.
176 "is_deep($data1, $data2, $test_name)"
178 Like Test::More's "is_deeply" but uses the more correct Test::Deep
179 module.
180 "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 "run_is_deeply([data_name1, data_name2])"
186 Like "run_is" but uses "is_deeply" for complex data structure
187 comparison.
188 "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 "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 run_like 'foo', qr{<html.*};
200 run_like 'foo', 'match';
201 "run_unlike([data_name, regexp | data_name]);"
203 The "run_unlike" function is similar to "run_like", except the
204 opposite.
205 run_unlike 'foo', qr{<html.*};
207 run_unlike 'foo', 'no_match';
208 "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 NOTE: If you do not specify either a plan, or run any tests, the
215 "run_compare" function will automatically be run.
216 "delimiters($block_delimiter, $data_delimiter)"
218 Override the default delimiters of "===" and "---".
219 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 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 "filters( @filters_list or $filters_hashref )"
230 Specify a list of additional filters to be applied to all blocks.
231 See "FILTERS" below.
232 You can also specify a hash ref that maps data section names to an
234 array ref of filters for that data type.
235 filters {
237 xxx => [qw(chomp lines)],
238 yyy => ['yaml'],
239 zzz => 'eval',
240 };
241 If a filters list has only one element, the array ref is optional.
243 "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 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 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 filter_arguments()
266 Return the arguments after the equals sign on a filter.
267 sub my_filter {
269 my $args = filter_arguments;
270 # is($args, 'whazzup');
271 ...
272 }
273 __DATA__
275 === A test
276 --- data my_filter=whazzup
277 tie_output()
279 You can capture STDOUT and STDERR for operations with this
280 function:
281 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 no_diff()
290 Turn off diff support for is() in a test file.
291 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 "WWW() XXX() YYY() ZZZ()"
298 These debugging functions are exported from the Spiffy.pm module.
299 See Spiffy for more info.
300 "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 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 Here is the basic layout of a specification:
318 === <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 === <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 Here is a code example:
338 use Test::Base;
340 delimiters qw(### :::);
342 # test code here
344 __END__
346 ### 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 ::: bar
355 a bar line
356 another bar line
357 ### Test Two
359 ::: foo
361 some foo line
362 some other foo line
363 ::: bar
365 some bar line
366 some other bar line
367 ::: baz
369 some baz line
370 some other baz line
371 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 The default block delimiter is "===" and the default data delimiter is
377 "--- ".
378 There are some special data section names used for control purposes:
380 --- SKIP
382 --- ONLY
383 --- LAST
384 A block with a SKIP section causes that test to be ignored. This is
386 useful to disable a test temporarily.
387 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 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 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 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 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 Example:
420 use Test::Base;
422 filters qw(foo bar);
424 filters { perl => 'strict' };
425 sub upper { uc(shift) }
427 __END__
429 === Test one
431 --- foo trim chomp upper
432 ...
433 --- bar -norm
435 ...
436 --- perl eval dumper
438 my @foo = map {
439 - $_;
440 } 1..10;
441 \ @foo;
442 Putting a "-" before a filter on a delimiter line, disables that
444 filter.
445 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 For example, consider the following filter list:
453 norm trim lines chomp array dumper eval
455 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 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 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 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 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 Here is a self explanatory example:
485 use Test::Base;
487 filters 'foo', 'bar=xyz';
489 sub foo {
491 transform(shift);
492 }
493 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 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 Normally you'll probably just use the functional interface, although
507 all the builtin filters are methods.
508 Note that filters defined in the "main" namespace can look like:
510 sub filter9 {
512 s/foo/bar/;
513 }
514 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 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 use Test::Base;
531 my $blocks1 = Test::Base->new;
532 my $blocks2 = Test::Base->new;
533 $blocks1->delimiters(qw(!!! @@@))->spec_file('test1.txt');
535 $blocks2->delimiters(qw(### $$$))->spec_string($test_data);
536 plan tests => $blocks1->blocks + $blocks2->blocks;
538 # ... 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 name()
548 This is the optional short description of a block, that is
549 specified on the block separator line.
550 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 seq_num()
556 Returns a sequence number for this block. Sequence numbers begin
557 with 1.
558 blocks_object()
560 Returns the Test::Base object that owns this block.
561 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 is_filtered()
568 Returns true if filters have already been run for this block.
569 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 Here is an example of a subclass:
581 package MyTestStuff;
583 use Test::Base -Base;
584 our @EXPORT = qw(some_func);
586 sub some_func {
588 (my ($self), @_) = find_my_self(@_);
589 ...
590 }
591 package MyTestStuff::Block;
593 use base 'Test::Base::Block';
594 sub desc {
596 $self->description(@_);
597 }
598 package MyTestStuff::Filter;
600 use base 'Test::Base::Filter';
601 sub upper {
603 $self->assert_scalar(@_);
604 uc(shift);
605 }
606 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 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 Just write a Makefile.PL that looks something like this:
619 use inc::Module::Install;
621 name 'Foo';
623 all_from 'lib/Foo.pm';
624 use_test_base;
626 WriteAll;
628 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 use strict;
636 use warnings;
637 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 This program is free software; you can redistribute it and/or modify it
655 under the same terms as Perl itself.
656 See <http://www.perl.com/perl/misc/Artistic.html>
658perl v5.36.0 2023-01-20 Test::Base(3)