2 Test::Base - A Data Driven Testing Framework
7 # lib/MyProject/Test.pm
8 package MyProject::Test;
13 package MyProject::Test::Filter;
14 use Test::Base::Filter -base;
17 return MyProject->do_something(shift);
25 plan tests => 1 * blocks;
27 run_is input => 'expected';
35 === Test one (the name of the test)
36 --- input my_filter local_filter
45 This is an optional description
46 of this particular test.
56 Testing is usually the ugly part of Perl module authoring. Perl gives
57 you a standard way to run tests with Test::Harness, and basic testing
58 primitives with Test::More. After that you are pretty much on your own
59 to develop a testing framework and philosophy. Test::More encourages you
60 to make your own framework by subclassing Test::Builder, but that is not
63 Test::Base gives you a way to write your own test framework base class
64 that *is* trivial. In fact it is as simple as two lines:
66 package MyTestFramework;
69 A module called "MyTestFramework.pm" containing those two lines, will
70 give all the power of Test::More and all the power of Test::Base to
71 every test file that uses it. As you build up the capabilities of
72 "MyTestFramework", your tests will have all of that power as well.
74 "MyTestFramework" becomes a place for you to put all of your reusable
75 testing bits. As you write tests, you will see patterns and duplication,
76 and you can "upstream" them into "MyTestFramework". Of course, you don't
77 have to subclass Test::Base at all. You can use it directly in many
78 applications, including everywhere you would use Test::More.
80 Test::Base concentrates on offering reusable data driven patterns, so
81 that you can write tests with a minimum of code. At the heart of all
82 testing you have inputs, processes and expected outputs. Test::Base
83 provides some clean ways for you to express your input and expected
84 output data, so you can spend your time focusing on that rather than
85 your code scaffolding.
88 Test::Base extends Test::More and exports all of its functions. So you
89 can basically write your tests the same as Test::More. Test::Base also
90 exports many functions of its own:
92 is(actual, expected, [test-name])
93 This is the equivalent of Test::More's "is" function with one
94 interesting twist. If your actual and expected results differ and the
95 output is multi-line, this function will show you a unified diff format
96 of output. Consider the benefit when looking for the one character that
97 is different in hundreds of lines of output!
99 Diff output requires the optional "Text::Diff" CPAN module. If you don't
100 have this module, the "is()" function will simply give you normal
101 Test::More output. To disable diffing altogether, set the
102 "TEST_SHOW_NO_DIFFS" environment variable (or $ENV{TEST_SHOW_NO_DIFFS})
103 to a true value. You can also call the "no_diff" function as a shortcut.
105 blocks( [data-section-name] )
106 The most important function is "blocks". In list context it returns a
107 list of "Test::Base::Block" objects that are generated from the test
108 specification in the "DATA" section of your test file. In scalar context
109 it returns the number of objects. This is useful to calculate your
112 Each Test::Base::Block object has methods that correspond to the names
113 of that object's data sections. There is also a "name" and a
114 "description" method for accessing those parts of the block if they were
117 The "blocks" function can take an optional single argument, that
118 indicates to only return the blocks that contain a particular named data
119 section. Otherwise "blocks" returns all blocks.
121 my @all_of_my_blocks = blocks;
123 my @just_the_foo_blocks = blocks('foo');
126 You can use the next_block function to iterate over all the blocks.
128 while (my $block = next_block) {
132 It returns undef after all blocks have been iterated over. It can then
133 be called again to reiterate.
136 Returns the first block or undef if there are none. It resets the
137 iterator to the "next_block" function.
140 There are many ways to write your tests. You can reference each block
141 individually or you can loop over all the blocks and perform a common
142 operation. The "run" function does the looping for you, so all you need
143 to do is pass it a code block to execute for each block.
145 The "run" function takes a subroutine as an argument, and calls the sub
146 one time for each block in the specification. It passes the current
147 block object to the subroutine.
151 is(process($block->foo), $block->bar, $block->name);
154 run_is([data_name1, data_name2])
155 Many times you simply want to see if two data sections are equivalent in
156 every block, probably after having been run through one or more filters.
157 With the "run_is" function, you can just pass the names of any two data
158 sections that exist in every block, and it will loop over every block
159 comparing the two sections.
163 If no data sections are given "run_is" will try to detect them
166 NOTE: Test::Base will silently ignore any blocks that don't contain both
169 run_is_deeply([data_name1, data_name2])
170 Like "run_is" but uses "is_deeply" for complex data structure
173 run_like([data_name, regexp | data_name]);
174 The "run_like" function is similar to "run_is" except the second
175 argument is a regular expression. The regexp can either be a "qr{}"
176 object or a data section that has been filtered into a regular
179 run_like 'foo', qr{<html.*};
180 run_like 'foo', 'match';
182 run_unlike([data_name, regexp | data_name]);
183 The "run_unlike" function is similar to "run_like", except the opposite.
185 run_unlike 'foo', qr{<html.*};
186 run_unlike 'foo', 'no_match';
188 run_compare(data_name1, data_name2)
189 The "run_compare" function is like the "run_is", "run_is_deeply" and the
190 "run_like" functions all rolled into one. It loops over each relevant
191 block and determines what type of comparison to do.
193 NOTE: If you do not specify either a plan, or run any tests, the
194 "run_compare" function will automatically be run.
196 delimiters($block_delimiter, $data_delimiter)
197 Override the default delimiters of "===" and "---".
199 spec_file($file_name)
200 By default, Test::Base reads its input from the DATA section. This
201 function tells it to get the spec from a file instead.
203 spec_string($test_data)
204 By default, Test::Base reads its input from the DATA section. This
205 function tells it to get the spec from a string that has been prepared
208 filters( @filters_list or $filters_hashref )
209 Specify a list of additional filters to be applied to all blocks. See
212 You can also specify a hash ref that maps data section names to an array
213 ref of filters for that data type.
216 xxx => [qw(chomp lines)],
221 If a filters list has only one element, the array ref is optional.
223 filters_delay( [1 | 0] );
224 By default Test::Base::Block objects are have all their filters run
225 ahead of time. There are testing situations in which it is advantageous
226 to delay the filtering. Calling this function with no arguments or a
227 true value, causes the filtering to be delayed.
231 plan tests => 1 * blocks;
232 for my $block (blocks) {
235 ok($block->is_filtered);
239 In the code above, the filters are called manually, using the
240 "run_filters" method of Test::Base::Block. In functions like "run_is",
241 where the tests are run automatically, filtering is delayed until right
245 Return the arguments after the equals sign on a filter.
248 my $args = filter_arguments;
249 # is($args, 'whazzup');
255 --- data my_filter=whazzup
258 You can capture STDOUT and STDERR for operations with this function:
261 tie_output(*STDOUT, $buffer);
265 is($out, "Hey!\nChe!\n");
268 Turn off diff support for is() in a test file.
271 Returns the default Test::Base object. This is useful if you feel the
272 need to do an OO operation in otherwise functional test code. See OO
275 WWW() XXX() YYY() ZZZ()
276 These debugging functions are exported from the Spiffy.pm module. See
277 Spiffy for more info.
279 croak() carp() cluck() confess()
280 You can use the functions from the Carp module without needing to import
281 them. Test::Base does it for you by default.
284 Test::Base allows you to specify your test data in an external file, the
285 DATA section of your program or from a scalar variable containing all
288 A *test specification* is a series of text lines. Each test (or block)
289 is separated by a line containing the block delimiter and an optional
290 test "name". Each block is further subdivided into named sections with a
291 line containing the data delimiter and the data section name. A
292 "description" of the test can go on lines after the block delimiter but
293 before the first data section.
295 Here is the basic layout of a specification:
298 <optional block description lines>
299 --- <data section name 1> <filter-1> <filter-2> <filter-n>
301 --- <data section name 2> <filter-1> <filter-2> <filter-n>
303 --- <data section name n> <filter-1> <filter-2> <filter-n>
307 <optional block description lines>
308 --- <data section name 1> <filter-1> <filter-2> <filter-n>
310 --- <data section name 2> <filter-1> <filter-2> <filter-n>
312 --- <data section name n> <filter-1> <filter-2> <filter-n>
315 Here is a code example:
319 delimiters qw(### :::);
326 We want to see if foo and bar
327 are really the same...
350 This example specifies two blocks. They both have foo and bar data
351 sections. The second block has a baz component. The block delimiter is
352 "###" and the data delimiter is ":::".
354 The default block delimiter is "===" and the default data delimiter is
357 There are some special data section names used for control purposes:
363 A block with a SKIP section causes that test to be ignored. This is
364 useful to disable a test temporarily.
366 A block with an ONLY section causes only that block to be used. This is
367 useful when you are concentrating on getting a single test to pass. If
368 there is more than one block with ONLY, the first one will be chosen.
370 Because ONLY is very useful for debugging and sometimes you forgot to
371 remove the ONLY flag before commiting to the VCS or uploading to CPAN,
372 Test::Base by default gives you a diag message saying *I found ONLY ...
373 maybe you're debugging?*. If you don't like it, use "no_diag_on_only".
375 A block with a LAST section makes that block the last one in the
376 specification. All following blocks will be ignored.
379 The real power in writing tests with Test::Base comes from its filtering
380 capabilities. Test::Base comes with an ever growing set of useful
381 generic filters than you can sequence and apply to various test blocks.
382 That means you can specify the block serialization in the most readable
383 format you can find, and let the filters translate it into what you
384 really need for a test. It is easy to write your own filters as well.
386 Test::Base allows you to specify a list of filters to each data section
387 of each block. The default filters are "norm" and "trim". These filters
388 will be applied (in order) to the data after it has been parsed from the
389 specification and before it is set into its Test::Base::Block object.
391 You can add to the default filter list with the "filters" function. You
392 can specify additional filters to a specific block by listing them after
393 the section name on a data section delimiter line.
400 filters { perl => 'strict' };
402 sub upper { uc(shift) }
407 --- foo trim chomp upper
419 Putting a "-" before a filter on a delimiter line, disables that filter.
422 Each filter can take either a scalar or a list as input, and will return
423 either a scalar or a list. Since filters are chained together, it is
424 important to learn which filters expect which kind of input and return
425 which kind of output.
427 For example, consider the following filter list:
429 norm trim lines chomp array dumper eval
431 The data always starts out as a single scalar string. "norm" takes a
432 scalar and returns a scalar. "trim" takes a list and returns a list, but
433 a scalar is a valid list. "lines" takes a scalar and returns a list.
434 "chomp" takes a list and returns a list. "array" takes a list and
435 returns a scalar (an anonymous array reference containing the list
436 elements). "dumper" takes a list and returns a scalar. "eval" takes a
437 scalar and creates a list.
439 A list of exactly one element works fine as input to a filter requiring
440 a scalar, but any other list will cause an exception. A scalar in list
441 context is considered a list of one element.
443 Data accessor methods for blocks will return a list of values when used
444 in list context, and the first element of the list in scalar context.
445 This is usually "the right thing", but be aware.
448 Test::Base comes with large set of stock filters. They are in the
449 "Test::Base::Filter" module. See Test::Base::Filter for a listing and
450 description of these filters.
452 Rolling Your Own Filters
453 Creating filter extensions is very simple. You can either write a
454 *function* in the "main" namespace, or a *method* in the
455 "Test::Base::Filter" namespace or a subclass of it. In either case the
456 text and any extra arguments are passed in and you return whatever you
457 want the new value to be.
459 Here is a self explanatory example:
463 filters 'foo', 'bar=xyz';
469 sub Test::Base::Filter::bar {
470 my $self = shift; # The Test::Base::Filter object
472 my $args = $self->current_arguments;
473 my $current_block_object = $self->block;
474 # transform $data in a barish manner
478 If you use the method interface for a filter, you can access the block
479 internals by calling the "block" method on the filter object.
481 Normally you'll probably just use the functional interface, although all
482 the builtin filters are methods.
484 Note that filters defined in the "main" namespace can look like:
490 since Test::Base automatically munges the input string into $_ variable
491 and checks the return value of the function to see if it looks like a
492 number. If you must define a filter that returns just a single number,
493 do it in a different namespace as a method. These filters don't allow
494 the simplistic $_ munging.
497 Test::Base has a nice functional interface for simple usage. Under the
498 hood everything is object oriented. A default Test::Base object is
499 created and all the functions are really just method calls on it.
501 This means if you need to get fancy, you can use all the object oriented
502 stuff too. Just create new Test::Base objects and use the functions as
506 my $blocks1 = Test::Base->new;
507 my $blocks2 = Test::Base->new;
509 $blocks1->delimiters(qw(!!! @@@))->spec_file('test1.txt');
510 $blocks2->delimiters(qw(### $$$))->spec_string($test_data);
512 plan tests => $blocks1->blocks + $blocks2->blocks;
516 THE "Test::Base::Block" CLASS
517 In Test::Base, blocks are exposed as Test::Base::Block objects. This
518 section lists the methods that can be called on a Test::Base::Block
519 object. Of course, each data section name is also available as a method.
522 This is the optional short description of a block, that is specified on
523 the block separator line.
526 This is an optional long description of the block. It is the text taken
527 from between the block separator and the first data section.
530 Returns a sequence number for this block. Sequence numbers begin with 1.
533 Returns the Test::Base object that owns this block.
536 Run the filters on the data sections of the blocks. You don't need to
537 use this method unless you also used the "filters_delay" function.
540 Returns true if filters have already been run for this block.
543 Returns a hash of the original, unfiltered values of each data section.
546 One of the nicest things about Test::Base is that it is easy to
547 subclass. This is very important, because in your personal project, you
548 will likely want to extend Test::Base with your own filters and other
549 reusable pieces of your test framework.
551 Here is an example of a subclass:
554 use Test::Base -Base;
556 our @EXPORT = qw(some_func);
559 (my ($self), @_) = find_my_self(@_);
563 package MyTestStuff::Block;
564 use base 'Test::Base::Block';
567 $self->description(@_);
570 package MyTestStuff::Filter;
571 use base 'Test::Base::Filter';
574 $self->assert_scalar(@_);
578 Note that you don't have to re-Export all the functions from Test::Base.
579 That happens automatically, due to the powers of Spiffy.
581 The first line in "some_func" allows it to be called as either a
582 function or a method in the test code.
585 You might be thinking that you do not want to use Test::Base in you
586 modules, because it adds an installation dependency. Fear not.
587 Module::Install takes care of that.
589 Just write a Makefile.PL that looks something like this:
591 use inc::Module::Install;
594 all_from 'lib/Foo.pm';
600 The line with "use_test_base" will automatically bundle all the code the
601 user needs to run Test::Base based tests.
604 Test::Base automatically adds:
609 to all of your test scripts and Test::Base subclasses. A Spiffy feature
613 This module started its life with the horrible and ridicule inducing
614 name "Test::Chunks". It was renamed to "Test::Base" with the hope that
615 it would be seen for the very useful module that it has become. If you
616 are switching from "Test::Chunks" to "Test::Base", simply substitute the
617 concept and usage of "chunks" to "blocks".
620 Ingy döt Net <ingy@cpan.org>
623 Copyright (c) 2006. Ingy döt Net. All rights reserved. Copyright (c)
624 2005. Brian Ingerson. All rights reserved.
626 This program is free software; you can redistribute it and/or modify it
627 under the same terms as Perl itself.
629 See http://www.perl.com/perl/misc/Artistic.html