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 time focusing on that rather than
90 your code scaffolding.
91
93 Test::Base extends Test::More and exports all of its functions. So you
94 can basically write your tests the same as Test::More. Test::Base also
95 exports many functions of its own:
96 is(actual, expected, [test-name])
98 This is the equivalent of Test::More's "is" function with one
99 interesting twist. If your actual and expected results differ and the
100 output is multi-line, this function will show you a unified diff format
101 of output. Consider the benefit when looking for the one character that
102 is different in hundreds of lines of output!
103 Diff output requires the optional "Text::Diff" CPAN module. If you
105 don't have this module, the "is()" function will simply give you normal
106 Test::More output. To disable diffing altogether, set the
107 "TEST_SHOW_NO_DIFFS" environment variable (or $ENV{TEST_SHOW_NO_DIFFS})
108 to a true value. You can also call the "no_diff" function as a
109 shortcut.
110 blocks( [data-section-name] )
112 The most important function is "blocks". In list context it returns a
113 list of "Test::Base::Block" objects that are generated from the test
114 specification in the "DATA" section of your test file. In scalar
115 context it returns the number of objects. This is useful to calculate
116 your Test::More plan.
117 Each Test::Base::Block object has methods that correspond to the names
119 of that object's data sections. There is also a "name" and a
120 "description" method for accessing those parts of the block if they
121 were specified.
122 The "blocks" function can take an optional single argument, that
124 indicates to only return the blocks that contain a particular named
125 data section. Otherwise "blocks" returns all blocks.
126 my @all_of_my_blocks = blocks;
128 my @just_the_foo_blocks = blocks('foo');
130 next_block()
132 You can use the next_block function to iterate over all the blocks.
133 while (my $block = next_block) {
135 ...
136 }
137 It returns undef after all blocks have been iterated over. It can then
139 be called again to reiterate.
140 first_block()
142 Returns the first block or undef if there are none. It resets the
143 iterator to the "next_block" function.
144 run(&subroutine)
146 There are many ways to write your tests. You can reference each block
147 individually or you can loop over all the blocks and perform a common
148 operation. The "run" function does the looping for you, so all you need
149 to do is pass it a code block to execute for each block.
150 The "run" function takes a subroutine as an argument, and calls the sub
152 one time for each block in the specification. It passes the current
153 block object to the subroutine.
154 run {
156 my $block = shift;
157 is(process($block->foo), $block->bar, $block->name);
158 };
159 run_is([data_name1, data_name2])
161 Many times you simply want to see if two data sections are equivalent
162 in every block, probably after having been run through one or more
163 filters. With the "run_is" function, you can just pass the names of
164 any two data sections that exist in every block, and it will loop over
165 every block comparing the two sections.
166 run_is 'foo', 'bar';
168 If no data sections are given "run_is" will try to detect them
170 automatically.
171 NOTE: Test::Base will silently ignore any blocks that don't contain
173 both sections.
174 is_deep($data1, $data2, $test_name)
176 Like Test::More's "is_deeply" but uses the more correct Test::Deep
177 module.
178 run_is_deeply([data_name1, data_name2])
180 Like "run_is_deeply" but uses "is_deep" which uses the more correct
181 Test::Deep.
182 run_is_deeply([data_name1, data_name2])
184 Like "run_is" but uses "is_deeply" for complex data structure
185 comparison.
186 run_is_deeply([data_name1, data_name2])
188 Like "run_is_deeply" but uses "is_deep" which uses the more correct
189 Test::Deep.
190 run_like([data_name, regexp | data_name]);
192 The "run_like" function is similar to "run_is" except the second
193 argument is a regular expression. The regexp can either be a "qr{}"
194 object or a data section that has been filtered into a regular
195 expression.
196 run_like 'foo', qr{<html.*};
198 run_like 'foo', 'match';
199 run_unlike([data_name, regexp | data_name]);
201 The "run_unlike" function is similar to "run_like", except the
202 opposite.
203 run_unlike 'foo', qr{<html.*};
205 run_unlike 'foo', 'no_match';
206 run_compare(data_name1, data_name2)
208 The "run_compare" function is like the "run_is", "run_is_deeply" and
209 the "run_like" functions all rolled into one. It loops over each
210 relevant block and determines what type of comparison to do.
211 NOTE: If you do not specify either a plan, or run any tests, the
213 "run_compare" function will automatically be run.
214 delimiters($block_delimiter, $data_delimiter)
216 Override the default delimiters of "===" and "---".
217 spec_file($file_name)
219 By default, Test::Base reads its input from the DATA section. This
220 function tells it to get the spec from a file instead.
221 spec_string($test_data)
223 By default, Test::Base reads its input from the DATA section. This
224 function tells it to get the spec from a string that has been prepared
225 somehow.
226 filters( @filters_list or $filters_hashref )
228 Specify a list of additional filters to be applied to all blocks. See
229 FILTERS below.
230 You can also specify a hash ref that maps data section names to an
232 array ref of filters for that data type.
233 filters {
235 xxx => [qw(chomp lines)],
236 yyy => ['yaml'],
237 zzz => 'eval',
238 };
239 If a filters list has only one element, the array ref is optional.
241 filters_delay( [1 | 0] );
243 By default Test::Base::Block objects are have all their filters run
244 ahead of time. There are testing situations in which it is advantageous
245 to delay the filtering. Calling this function with no arguments or a
246 true value, causes the filtering to be delayed.
247 use Test::Base;
249 filters_delay;
250 plan tests => 1 * blocks;
251 for my $block (blocks) {
252 ...
253 $block->run_filters;
254 ok($block->is_filtered);
255 ...
256 }
257 In the code above, the filters are called manually, using the
259 "run_filters" method of Test::Base::Block. In functions like "run_is",
260 where the tests are run automatically, filtering is delayed until right
261 before the test.
262 filter_arguments()
264 Return the arguments after the equals sign on a filter.
265 sub my_filter {
267 my $args = filter_arguments;
268 # is($args, 'whazzup');
269 ...
270 }
271 __DATA__
273 === A test
274 --- data my_filter=whazzup
275 tie_output()
277 You can capture STDOUT and STDERR for operations with this function:
278 my $out = '';
280 tie_output(*STDOUT, $buffer);
281 print "Hey!\n";
282 print "Che!\n";
283 untie *STDOUT;
284 is($out, "Hey!\nChe!\n");
285 no_diff()
287 Turn off diff support for is() in a test file.
288 default_object()
290 Returns the default Test::Base object. This is useful if you feel the
291 need to do an OO operation in otherwise functional test code. See OO
292 below.
293 WWW() XXX() YYY() ZZZ()
295 These debugging functions are exported from the Spiffy.pm module. See
296 Spiffy for more info.
297 croak() carp() cluck() confess()
299 You can use the functions from the Carp module without needing to
300 import them. Test::Base does it for you by default.
301
303 Test::Base allows you to specify your test data in an external file,
304 the DATA section of your program or from a scalar variable containing
305 all the text input.
306 A test specification is a series of text lines. Each test (or block) is
308 separated by a line containing the block delimiter and an optional test
309 "name". Each block is further subdivided into named sections with a
310 line containing the data delimiter and the data section name. A
311 "description" of the test can go on lines after the block delimiter but
312 before the first data section.
313 Here is the basic layout of a specification:
315 === <block name 1>
317 <optional block description lines>
318 --- <data section name 1> <filter-1> <filter-2> <filter-n>
319 <test data lines>
320 --- <data section name 2> <filter-1> <filter-2> <filter-n>
321 <test data lines>
322 --- <data section name n> <filter-1> <filter-2> <filter-n>
323 <test data lines>
324 === <block name 2>
326 <optional block description lines>
327 --- <data section name 1> <filter-1> <filter-2> <filter-n>
328 <test data lines>
329 --- <data section name 2> <filter-1> <filter-2> <filter-n>
330 <test data lines>
331 --- <data section name n> <filter-1> <filter-2> <filter-n>
332 <test data lines>
333 Here is a code example:
335 use Test::Base;
337 delimiters qw(### :::);
339 # test code here
341 __END__
343 ### Test One
345 We want to see if foo and bar
346 are really the same...
347 ::: foo
348 a foo line
349 another foo line
350 ::: bar
352 a bar line
353 another bar line
354 ### Test Two
356 ::: foo
358 some foo line
359 some other foo line
360 ::: bar
362 some bar line
363 some other bar line
364 ::: baz
366 some baz line
367 some other baz line
368 This example specifies two blocks. They both have foo and bar data
370 sections. The second block has a baz component. The block delimiter is
371 "###" and the data delimiter is ":::".
372 The default block delimiter is "===" and the default data delimiter is
374 "---".
375 There are some special data section names used for control purposes:
377 --- SKIP
379 --- ONLY
380 --- LAST
381 A block with a SKIP section causes that test to be ignored. This is
383 useful to disable a test temporarily.
384 A block with an ONLY section causes only that block to be used. This is
386 useful when you are concentrating on getting a single test to pass. If
387 there is more than one block with ONLY, the first one will be chosen.
388 Because ONLY is very useful for debugging and sometimes you forgot to
390 remove the ONLY flag before commiting to the VCS or uploading to CPAN,
391 Test::Base by default gives you a diag message saying I found ONLY ...
392 maybe you're debugging?. If you don't like it, use "no_diag_on_only".
393 A block with a LAST section makes that block the last one in the
395 specification. All following blocks will be ignored.
396
398 The real power in writing tests with Test::Base comes from its
399 filtering capabilities. Test::Base comes with an ever growing set of
400 useful generic filters than you can sequence and apply to various test
401 blocks. That means you can specify the block serialization in the most
402 readable format you can find, and let the filters translate it into
403 what you really need for a test. It is easy to write your own filters
404 as well.
405 Test::Base allows you to specify a list of filters to each data section
407 of each block. The default filters are "norm" and "trim". These
408 filters will be applied (in order) to the data after it has been parsed
409 from the specification and before it is set into its Test::Base::Block
410 object.
411 You can add to the default filter list with the "filters" function. You
413 can specify additional filters to a specific block by listing them
414 after the section name on a data section delimiter line.
415 Example:
417 use Test::Base;
419 filters qw(foo bar);
421 filters { perl => 'strict' };
422 sub upper { uc(shift) }
424 __END__
426 === Test one
428 --- foo trim chomp upper
429 ...
430 --- bar -norm
432 ...
433 --- perl eval dumper
435 my @foo = map {
436 - $_;
437 } 1..10;
438 \ @foo;
439 Putting a "-" before a filter on a delimiter line, disables that
441 filter.
442 Scalar vs List
444 Each filter can take either a scalar or a list as input, and will
445 return either a scalar or a list. Since filters are chained together,
446 it is important to learn which filters expect which kind of input and
447 return which kind of output.
448 For example, consider the following filter list:
450 norm trim lines chomp array dumper eval
452 The data always starts out as a single scalar string. "norm" takes a
454 scalar and returns a scalar. "trim" takes a list and returns a list,
455 but a scalar is a valid list. "lines" takes a scalar and returns a
456 list. "chomp" takes a list and returns a list. "array" takes a list and
457 returns a scalar (an anonymous array reference containing the list
458 elements). "dumper" takes a list and returns a scalar. "eval" takes a
459 scalar and creates a list.
460 A list of exactly one element works fine as input to a filter requiring
462 a scalar, but any other list will cause an exception. A scalar in list
463 context is considered a list of one element.
464 Data accessor methods for blocks will return a list of values when used
466 in list context, and the first element of the list in scalar context.
467 This is usually "the right thing", but be aware.
468 The Stock Filters
470 Test::Base comes with large set of stock filters. They are in the
471 "Test::Base::Filter" module. See Test::Base::Filter for a listing and
472 description of these filters.
473 Rolling Your Own Filters
475 Creating filter extensions is very simple. You can either write a
476 function in the "main" namespace, or a method in the
477 "Test::Base::Filter" namespace or a subclass of it. In either case the
478 text and any extra arguments are passed in and you return whatever you
479 want the new value to be.
480 Here is a self explanatory example:
482 use Test::Base;
484 filters 'foo', 'bar=xyz';
486 sub foo {
488 transform(shift);
489 }
490 sub Test::Base::Filter::bar {
492 my $self = shift; # The Test::Base::Filter object
493 my $data = shift;
494 my $args = $self->current_arguments;
495 my $current_block_object = $self->block;
496 # transform $data in a barish manner
497 return $data;
498 }
499 If you use the method interface for a filter, you can access the block
501 internals by calling the "block" method on the filter object.
502 Normally you'll probably just use the functional interface, although
504 all the builtin filters are methods.
505 Note that filters defined in the "main" namespace can look like:
507 sub filter9 {
509 s/foo/bar/;
510 }
511 since Test::Base automatically munges the input string into $_ variable
513 and checks the return value of the function to see if it looks like a
514 number. If you must define a filter that returns just a single number,
515 do it in a different namespace as a method. These filters don't allow
516 the simplistic $_ munging.
517
519 Test::Base has a nice functional interface for simple usage. Under the
520 hood everything is object oriented. A default Test::Base object is
521 created and all the functions are really just method calls on it.
522 This means if you need to get fancy, you can use all the object
524 oriented stuff too. Just create new Test::Base objects and use the
525 functions as methods.
526 use Test::Base;
528 my $blocks1 = Test::Base->new;
529 my $blocks2 = Test::Base->new;
530 $blocks1->delimiters(qw(!!! @@@))->spec_file('test1.txt');
532 $blocks2->delimiters(qw(### $$$))->spec_string($test_data);
533 plan tests => $blocks1->blocks + $blocks2->blocks;
535 # ... etc
537
539 In Test::Base, blocks are exposed as Test::Base::Block objects. This
540 section lists the methods that can be called on a Test::Base::Block
541 object. Of course, each data section name is also available as a
542 method.
543 name()
545 This is the optional short description of a block, that is specified on
546 the block separator line.
547 description()
549 This is an optional long description of the block. It is the text taken
550 from between the block separator and the first data section.
551 seq_num()
553 Returns a sequence number for this block. Sequence numbers begin with
554 1.
555 blocks_object()
557 Returns the Test::Base object that owns this block.
558 run_filters()
560 Run the filters on the data sections of the blocks. You don't need to
561 use this method unless you also used the "filters_delay" function.
562 is_filtered()
564 Returns true if filters have already been run for this block.
565 original_values()
567 Returns a hash of the original, unfiltered values of each data section.
568
570 One of the nicest things about Test::Base is that it is easy to
571 subclass. This is very important, because in your personal project, you
572 will likely want to extend Test::Base with your own filters and other
573 reusable pieces of your test framework.
574 Here is an example of a subclass:
576 package MyTestStuff;
578 use Test::Base -Base;
579 our @EXPORT = qw(some_func);
581 sub some_func {
583 (my ($self), @_) = find_my_self(@_);
584 ...
585 }
586 package MyTestStuff::Block;
588 use base 'Test::Base::Block';
589 sub desc {
591 $self->description(@_);
592 }
593 package MyTestStuff::Filter;
595 use base 'Test::Base::Filter';
596 sub upper {
598 $self->assert_scalar(@_);
599 uc(shift);
600 }
601 Note that you don't have to re-Export all the functions from
603 Test::Base. That happens automatically, due to the powers of Spiffy.
604 The first line in "some_func" allows it to be called as either a
606 function or a method in the test code.
607
609 You might be thinking that you do not want to use Test::Base in you
610 modules, because it adds an installation dependency. Fear not.
611 Module::Install takes care of that.
612 Just write a Makefile.PL that looks something like this:
614 use inc::Module::Install;
616 name 'Foo';
618 all_from 'lib/Foo.pm';
619 use_test_base;
621 WriteAll;
623 The line with "use_test_base" will automatically bundle all the code
625 the user needs to run Test::Base based tests.
626
628 Test::Base automatically adds:
629 use strict;
631 use warnings;
632 to all of your test scripts and Test::Base subclasses. A Spiffy feature
634 indeed.
635
637 This module started its life with the horrible and ridicule inducing
638 name "Test::Chunks". It was renamed to "Test::Base" with the hope that
639 it would be seen for the very useful module that it has become. If you
640 are switching from "Test::Chunks" to "Test::Base", simply substitute
641 the concept and usage of "chunks" to "blocks".
642
644 Ingy doet Net <ingy@cpan.org>
645
647 Copyright (c) 2006, 2008, 2009. Ingy doet Net. Copyright (c) 2005.
648 Brian Ingerson.
649 This program is free software; you can redistribute it and/or modify it
651 under the same terms as Perl itself.
652 See http://www.perl.com/perl/misc/Artistic.html
654perl v5.10.1 2009-03-27 Test::Base(3)