Debian Codegraph @

README

raw
1 NAME
2 Test::Class - Easily create test classes in an xUnit/JUnit style
3
4 VERSION
5 version 0.51
6
7 SYNOPSIS
8 package Example::Test;
9 use base qw(Test::Class);
10 use Test::More;
11
12 # setup methods are run before every test method.
13 sub make_fixture : Test(setup) {
14 my $array = [1, 2];
15 shift->{test_array} = $array;
16 }
17
18 # a test method that runs 1 test
19 sub test_push : Test {
20 my $array = shift->{test_array};
21 push @$array, 3;
22 is_deeply($array, [1, 2, 3], 'push worked');
23 }
24
25 # a test method that runs 4 tests
26 sub test_pop : Test(4) {
27 my $array = shift->{test_array};
28 is(pop @$array, 2, 'pop = 2');
29 is(pop @$array, 1, 'pop = 1');
30 is_deeply($array, [], 'array empty');
31 is(pop @$array, undef, 'pop = undef');
32 }
33
34 # teardown methods are run after every test method.
35 sub teardown : Test(teardown) {
36 my $array = shift->{test_array};
37 diag("array = (@$array) after test(s)");
38 }
39
40 later in a nearby .t file
41
42 #! /usr/bin/perl
43 use Example::Test;
44
45 # run all the test methods in Example::Test
46 Test::Class->runtests;
47
48 Outputs:
49
50 1..5
51 ok 1 - pop = 2
52 ok 2 - pop = 1
53 ok 3 - array empty
54 ok 4 - pop = undef
55 # array = () after test(s)
56 ok 5 - push worked
57 # array = (1 2 3) after test(s)
58
59 DESCRIPTION
60 Test::Class provides a simple way of creating classes and objects to
61 test your code in an xUnit style.
62
63 Built using Test::Builder, it was designed to work with other
64 Test::Builder based modules (Test::More, Test::Differences,
65 Test::Exception, etc.).
66
67 *Note:* This module will make more sense, if you are already familiar
68 with the "standard" mechanisms for testing perl code. Those unfamiliar
69 with Test::Harness, Test::Simple, Test::More and friends should go take
70 a look at them now. Test::Tutorial is a good starting point.
71
72 INTRODUCTION
73 A brief history lesson
74 In 1994 Kent Beck wrote a testing framework for Smalltalk called SUnit.
75 It was popular. You can read a copy of his original paper at
76 <http://www.xprogramming.com/testfram.htm>.
77
78 Later Kent Beck and Erich Gamma created JUnit for testing Java
79 <http://www.junit.org/>. It was popular too.
80
81 Now there are xUnit frameworks for every language from Ada to XSLT. You
82 can find a list at <http://www.xprogramming.com/software.htm>.
83
84 While xUnit frameworks are traditionally associated with unit testing
85 they are also useful in the creation of functional/acceptance tests.
86
87 Test::Class is (yet another) implementation of xUnit style testing in
88 Perl.
89
90 Why you should use Test::Class
91 Test::Class attempts to provide simple xUnit testing that integrates
92 simply with the standard perl *.t style of testing. In particular:
93
94 * All the advantages of xUnit testing. You can easily create test
95 fixtures and isolate tests. It provides a framework that should be
96 familiar to people who have used other xUnit style test systems.
97
98 * It is built with Test::Builder and should co-exist happily with all
99 other Test::Builder based modules. This makes using test classes in
100 *.t scripts, and refactoring normal tests into test classes, much
101 simpler because:
102
103 * You do not have to learn a new set of new test APIs and can
104 continue using ok(), like(), etc. from Test::More and friends.
105
106 * Skipping tests and todo tests are supported.
107
108 * You can have normal tests and Test::Class classes co-existing in
109 the same *.t script. You don't have to re-write an entire
110 script, but can use test classes as and when it proves useful.
111
112 * You can easily package your tests as classes/modules, rather than
113 *.t scripts. This simplifies reuse, documentation and distribution,
114 encourages refactoring, and allows tests to be extended by
115 inheritance.
116
117 * You can have multiple setup/teardown methods. For example have one
118 teardown method to clean up resources and another to check that
119 class invariants still hold.
120
121 * It can make running tests faster. Once you have refactored your *.t
122 scripts into classes they can be easily run from a single script.
123 This gains you the (often considerable) start up time that each
124 separate *.t script takes.
125
126 Why you should *not* use Test::Class
127 * If your *.t scripts are working fine then don't bother with
128 Test::Class. For simple test suites it is almost certainly overkill.
129 Don't start thinking about using Test::Class until issues like
130 duplicate code in your test scripts start to annoy.
131
132 * If you are distributing your code it is yet another module that the
133 user has to have to run your tests (unless you distribute it with
134 your test suite of course).
135
136 * If you are used to the TestCase/Suite/Runner class structure used by
137 JUnit and similar testing frameworks you may find Test::Unit more
138 familiar (but try reading "HELP FOR CONFUSED JUNIT USERS" before you
139 give up).
140
141 TEST CLASSES
142 A test class is just a class that inherits from Test::Class. Defining a
143 test class is as simple as doing:
144
145 package Example::Test;
146 use base qw(Test::Class);
147
148 Since Test::Class does not provide its own test functions, but uses
149 those provided by Test::More and friends, you will nearly always also
150 want to have:
151
152 use Test::More;
153
154 to import the test functions into your test class.
155
156 METHOD TYPES
157 There are three different types of method you can define using
158 Test::Class.
159
160 1) Test methods
161 You define test methods using the Test attribute. For example:
162
163 package Example::Test;
164 use base qw(Test::Class);
165 use Test::More;
166
167 sub subtraction : Test {
168 is( 2-1, 1, 'subtraction works' );
169 }
170
171 This declares the "subtraction" method as a test method that runs one
172 test.
173
174 If your test method runs more than one test, you should put the number
175 of tests in brackets like this:
176
177 sub addition : Test(2) {
178 is(10 + 20, 30, 'addition works');
179 is(20 + 10, 30, ' both ways');
180 }
181
182 If you don't know the number of tests at compile time you can use
183 "no_plan" like this.
184
185 sub check_class : Test(no_plan) {
186 my $objects = shift->{objects};
187 isa_ok($_, "Object") foreach @$objects;
188 }
189
190 or use the :Tests attribute, which acts just like ":Test" but defaults
191 to "no_plan" if no number is given:
192
193 sub check_class : Tests {
194 my $objects = shift->{objects};
195 isa_ok($_, "Object") foreach @$objects;
196 }
197
198 2) Setup and teardown methods
199 Setup and teardown methods are run before and after every test. For
200 example:
201
202 sub before : Test(setup) { diag("running before test") }
203 sub after : Test(teardown) { diag("running after test") }
204
205 You can use setup and teardown methods to create common objects used by
206 all of your test methods (a test *fixture*) and store them in your
207 Test::Class object, treating it as a hash. For example:
208
209 sub pig : Test(setup) {
210 my $self = shift;
211 $self->{test_pig} = Pig->new;
212 }
213
214 sub born_hungry : Test {
215 my $pig = shift->{test_pig};
216 is($pig->hungry, 'pigs are born hungry');
217 }
218
219 sub eats : Test(3) {
220 my $pig = shift->{test_pig};
221 ok( $pig->feed, 'pig fed okay');
222 ok(! $pig->hungry, 'fed pig not hungry');
223 ok(! $pig->feed, 'cannot feed full pig');
224 }
225
226 You can also declare setup and teardown methods as running tests. For
227 example you could check that the test pig survives each test method by
228 doing:
229
230 sub pig_alive : Test(teardown => 1) {
231 my $pig = shift->{test_pig};
232 ok($pig->alive, 'pig survived tests' );
233 }
234
235 3) Startup and shutdown methods
236 Startup and shutdown methods are like setup and teardown methods for the
237 whole test class. All the startup methods are run once when you start
238 running a test class. All the shutdown methods are run once just before
239 a test class stops running.
240
241 You can use these to create and destroy expensive objects that you don't
242 want to have to create and destroy for every test - a database
243 connection for example:
244
245 sub db_connect : Test(startup) {
246 shift->{dbi} = DBI->connect;
247 }
248
249 sub db_disconnect : Test(shutdown) {
250 shift->{dbi}->disconnect;
251 }
252
253 Just like setup and teardown methods you can pass an optional number of
254 tests to startup and shutdown methods. For example:
255
256 sub example : Test(startup => 1) {
257 ok(1, 'a startup method with one test');
258 }
259
260 If you want to run an unknown number of tests within your startup
261 method, you need to say e.g.
262
263 sub example : Test(startup => no_plan) {
264 ok(1, q{The first of many tests that don't want to have to count});
265 ...
266 }
267
268 as the : Tests attribute behaves exactly like : Test in this context.
269
270 If a startup method has a failing test or throws an exception then all
271 other tests for the current test object are ignored.
272
273 RUNNING TESTS
274 You run test methods with runtests(). Doing:
275
276 Test::Class->runtests
277
278 runs all of the test methods in every loaded test class. This allows you
279 to easily load multiple test classes in a *.t file and run them all.
280
281 #! /usr/bin/perl
282
283 # load all the test classes I want to run
284 use Foo::Test;
285 use Foo::Bar::Test;
286 use Foo::Fribble::Test;
287 use Foo::Ni::Test;
288
289 # and run them all
290 Test::Class->runtests;
291
292 You can use Test::Class::Load to automatically load all the test classes
293 in a given set of directories.
294
295 If you need finer control you can create individual test objects with
296 new(). For example to just run the tests in the test class
297 "Foo::Bar::Test" you can do:
298
299 Example::Test->new->runtests
300
301 You can also pass runtests() a list of test objects to run. For example:
302
303 my $o1 = Example::Test->new;
304 my $o2 = Another::Test->new;
305 # runs all the tests in $o1 and $o2
306 $o1->runtests($o2);
307
308 Since, by definition, the base Test::Class has no tests, you could also
309 have written:
310
311 my $o1 = Example::Test->new;
312 my $o2 = Another::Test->new;
313 Test::Class->runtests($o1, $o2);
314
315 If you pass runtests() class names it will automatically create test
316 objects for you, so the above can be written more compactly as:
317
318 Test::Class->runtests(qw( Example::Test Another::Test ))
319
320 In all of the above examples runtests() will look at the number of tests
321 both test classes run and output an appropriate test header for
322 Test::Harness automatically.
323
324 What happens if you run test classes and normal tests in the same
325 script? For example:
326
327 Test::Class->runtests;
328 ok(Example->new->foo, 'a test not in the test class');
329 ok(Example->new->bar, 'ditto');
330
331 Test::Harness will complain that it saw more tests than it expected
332 since the test header output by runtests() will not include the two
333 normal tests.
334
335 To overcome this problem you can pass an integer value to runtests().
336 This is added to the total number of tests in the test header. So the
337 problematic example can be rewritten as follows:
338
339 Test::Class->runtests(+2);
340 ok(Example->new->foo, 'a test not in the test class');
341 ok(Example->new->bar, 'ditto');
342
343 If you prefer to write your test plan explicitly you can use
344 expected_tests() to find out the number of tests a class/object is
345 expected to run.
346
347 Since runtests() will not output a test plan if one has already been
348 set, the previous example can be written as:
349
350 plan tests => Test::Class->expected_tests(+2);
351 Test::Class->runtests;
352 ok(Example->new->foo, 'a test not in the test class');
353 ok(Example->new->bar, 'ditto');
354
355 *Remember:* Test objects are just normal perl objects. Test classes are
356 just normal perl classes. Setup, test and teardown methods are just
357 normal methods. You are completely free to have other methods in your
358 class that are called from your test methods, or have object specific
359 "new" and "DESTROY" methods.
360
361 In particular you can override the new() method to pass parameters to
362 your test object, or re-define the number of tests a method will run.
363 See num_method_tests() for an example.
364
365 TEST DESCRIPTIONS
366 The test functions you import from Test::More and other Test::Builder
367 based modules usually take an optional third argument that specifies the
368 test description, for example:
369
370 is $something, $something_else, 'a description of my test';
371
372 If you do not supply a test description, and the test function does not
373 supply its own default, then Test::Class will use the name of the
374 currently running test method, replacing all "_" characters with spaces
375 so:
376
377 sub one_plus_one_is_two : Test {
378 is 1+1, 2;
379 }
380
381 will result in:
382
383 ok 1 - one plus one is two
384
385 RUNNING ORDER OF METHODS
386 Methods of each type are run in the following order:
387
388 1. All of the startup methods in alphabetical order
389
390 2. For each test method, in alphabetical order:
391
392 * All of the setup methods in alphabetical order
393
394 * The test method.
395
396 * All of the teardown methods in alphabetical order
397
398 3. All of the shutdown methods in alphabetical order.
399
400 Most of the time you should not care what order tests are run in, but it
401 can occasionally be useful to force some test methods to be run early.
402 For example:
403
404 sub _check_new {
405 my $self = shift;
406 isa_ok(Object->new, "Object") or $self->BAILOUT('new fails!');
407 }
408
409 The leading "_" will force the above method to run first - allowing the
410 entire suite to be aborted before any other test methods run.
411
412 HANDLING EXCEPTIONS
413 If a startup, setup, test, teardown or shutdown method dies then
414 runtests() will catch the exception and fail any remaining test. For
415 example:
416
417 sub test_object : Test(2) {
418 my $object = Object->new;
419 isa_ok( $object, "Object" ) or die "could not create object\n";
420 ok( $object->open, "open worked" );
421 }
422
423 will produce the following if the first test failed:
424
425 not ok 1 - The object isa Object
426 # Failed test 'The object isa Object'
427 # at /Users/adrianh/Desktop/foo.pl line 14.
428 # (in MyTest->test_object)
429 # The object isn't defined
430 not ok 2 - test_object died (could not create object)
431 # Failed test 'test_object died (could not create object)'
432 # at /Users/adrianh/Desktop/foo.pl line 19.
433 # (in MyTest->test_object)
434
435 This can considerably simplify testing code that throws exceptions.
436
437 Rather than having to explicitly check that the code exited normally
438 (e.g. with "lives_ok" in Test::Exception) the test will fail
439 automatically - without aborting the other test methods. For example
440 contrast:
441
442 use Test::Exception;
443
444 my $file;
445 lives_ok { $file = read_file('test.txt') } 'file read';
446 is($file, "content", 'test file read');
447
448 with:
449
450 sub read_file : Test {
451 is(read_file('test.txt'), "content", 'test file read');
452 }
453
454 If more than one test remains after an exception then the first one is
455 failed, and the remaining ones are skipped.
456
457 If the setup method of a test method dies, then all of the remaining
458 setup and shutdown methods are also skipped.
459
460 Since startup methods will usually be creating state needed by all the
461 other test methods, an exception within a startup method will prevent
462 all other test methods of that class running.
463
464 RETURNING EARLY
465 If a test method returns before it has run all of its tests, by default
466 the missing tests are deemed to have been skipped; see "Skipped Tests"
467 for more information.
468
469 However, if the class's "fail_if_returned_early" method returns true,
470 then the missing tests will be deemed to have failed. For example,
471
472 package MyClass;
473 use base 'Test::Class';
474 sub fail_if_returned_early { 1 }
475
476 sub oops : Tests(8) {
477 for (my $n=1; $n*$n<50; ++$n) {
478 ok 1, "$n squared is less than fifty";
479 }
480 }
481
482 RETURNING LATE
483 If a test method runs too many tests, by default the test plan succeeds.
484
485 However, if the class's "fail_if_returned_late" method returns true,
486 then the extra tests will trigger a failure. For example,
487
488 package MyClass;
489 use base 'Test::Class';
490 sub fail_if_returned_late { 1 }
491
492 sub oops : Tests(1) {
493 ok 1, "just a simple test";
494 ok 1, "just a simple test"; #oops I copied and pasted too many tests
495 }
496
497 SKIPPED TESTS
498 You can skip the rest of the tests in a method by returning from the
499 method before all the test have finished running (but see "Returning
500 Early" for how to change this). The value returned is used as the reason
501 for the tests being skipped.
502
503 This makes managing tests that can be skipped for multiple reasons very
504 simple. For example:
505
506 sub flying_pigs : Test(5) {
507 my $pig = Pig->new;
508 isa_ok($pig, 'Pig') or return("cannot breed pigs")
509 can_ok($pig, 'takeoff') or return("pigs don't fly here");
510 ok($pig->takeoff, 'takeoff') or return("takeoff failed");
511 ok( $pig->altitude > 0, 'Pig is airborne' );
512 ok( $pig->airspeed > 0, ' and moving' );
513 }
514
515 If you run this test in an environment where "Pig->new" worked and the
516 takeoff method existed, but failed when ran, you would get:
517
518 ok 1 - The object isa Pig
519 ok 2 - can takeoff
520 not ok 3 - takeoff
521 ok 4 # skip takeoff failed
522 ok 5 # skip takeoff failed
523
524 You can also skip tests just as you do in Test::More or Test::Builder -
525 see "Conditional tests" in Test::More for more information.
526
527 *Note:* if you want to skip tests in a method with "no_plan" tests then
528 you have to explicitly skip the tests in the method - since Test::Class
529 cannot determine how many tests (if any) should be skipped:
530
531 sub test_objects : Tests {
532 my $self = shift;
533 my $objects = $self->{objects};
534 if (@$objects) {
535 isa_ok($_, "Object") foreach (@$objects);
536 } else {
537 $self->builder->skip("no objects to test");
538 }
539 }
540
541 Another way of overcoming this problem is to explicitly set the number
542 of tests for the method at run time using num_method_tests() or
543 "num_tests".
544
545 You can make a test class skip all of its tests by setting SKIP_CLASS()
546 before runtests() is called.
547
548 TO DO TESTS
549 You can create todo tests just as you do in Test::More and Test::Builder
550 using the $TODO variable. For example:
551
552 sub live_test : Test {
553 local $TODO = "live currently unimplemented";
554 ok(Object->live, "object live");
555 }
556
557 See "Todo tests" in Test::Harness for more information.
558
559 EXTENDING TEST CLASSES BY INHERITANCE
560 You can extend test methods by inheritance in the usual way. For example
561 consider the following test class for a "Pig" object.
562
563 package Pig::Test;
564 use base qw(Test::Class);
565 use Test::More;
566
567 sub testing_class { "Pig" }
568 sub new_args { (-age => 3) }
569
570 sub setup : Test(setup) {
571 my $self = shift;
572 my $class = $self->testing_class;
573 my @args = $self->new_args;
574 $self->{pig} = $class->new( @args );
575 }
576
577 sub _creation : Test {
578 my $self = shift;
579 isa_ok($self->{pig}, $self->testing_class)
580 or $self->FAIL_ALL('Pig->new failed');
581 }
582
583 sub check_fields : Test {
584 my $pig = shift->{pig}
585 is($pig->age, 3, "age accessed");
586 }
587
588 Next consider "NamedPig" a subclass of "Pig" where you can give your pig
589 a name.
590
591 We want to make sure that all the tests for the "Pig" object still work
592 for "NamedPig". We can do this by subclassing "Pig::Test" and overriding
593 the "testing_class" and "new_args" methods.
594
595 package NamedPig::Test;
596 use base qw(Pig::Test);
597 use Test::More;
598
599 sub testing_class { "NamedPig" }
600 sub new_args { (shift->SUPER::new_args, -name => 'Porky') }
601
602 Now we need to test the name method. We could write another test method,
603 but we also have the option of extending the existing "check_fields"
604 method.
605
606 sub check_fields : Test(2) {
607 my $self = shift;
608 $self->SUPER::check_fields;
609 is($self->{pig}->name, 'Porky', 'name accessed');
610 }
611
612 While the above works, the total number of tests for the method is
613 dependent on the number of tests in its "SUPER::check_fields". If we add
614 a test to "Pig::Test->check_fields" we will also have to update the
615 number of tests of "NamedPig::test->check_fields".
616
617 Test::Class allows us to state explicitly that we are adding tests to an
618 existing method by using the "+" prefix. Since we are adding a single
619 test to "check_fields", it can be rewritten as:
620
621 sub check_fields : Test(+1) {
622 my $self = shift;
623 $self->SUPER::check_fields;
624 is($self->{pig}->name, 'Porky', 'name accessed');
625 }
626
627 With the above definition you can add tests to "check_fields" in
628 "Pig::Test" without affecting "NamedPig::Test".
629
630 RUNNING INDIVIDUAL TESTS
631 NOTE: The exact mechanism for running individual tests is likely to
632 change in the future.
633
634 Sometimes you just want to run a single test. Commenting out other tests
635 or writing code to skip them can be a hassle, so you can specify the
636 "TEST_METHOD" environment variable. The value is expected to be a valid
637 regular expression and, if present, only runs test methods whose names
638 match the regular expression. Startup, setup, teardown and shutdown
639 tests will still be run.
640
641 One easy way of doing this is by specifying the environment variable
642 *before* the "runtests" method is called.
643
644 Running a test named "customer_profile":
645
646 #! /usr/bin/perl
647 use Example::Test;
648
649 $ENV{TEST_METHOD} = 'customer_profile';
650 Test::Class->runtests;
651
652 Running all tests with "customer" in their name:
653
654 #! /usr/bin/perl
655 use Example::Test;
656
657 $ENV{TEST_METHOD} = '.*customer.*';
658 Test::Class->runtests;
659
660 If you specify an invalid regular expression, your tests will not be
661 run:
662
663 #! /usr/bin/perl
664 use Example::Test;
665
666 $ENV{TEST_METHOD} = 'C++';
667 Test::Class->runtests;
668
669 And when you run it:
670
671 TEST_METHOD (C++) is not a valid regular expression: Search pattern \
672 not terminated at (eval 17) line 1.
673
674 ORGANISING YOUR TEST CLASSES
675 You can, of course, organise your test modules as you wish. My personal
676 preferences is:
677
678 * Name test classes with a suffix of "::Test" so the test class for
679 the "Foo::Bar" module would be "Foo::Bar::Test".
680
681 * Place all test classes in t/lib.
682
683 The Test::Class::Load provides a simple mechanism for easily loading all
684 of the test classes in a given set of directories.
685
686 A NOTE ON LOADING TEST CLASSES
687 Due to its use of subroutine attributes Test::Class based modules must
688 be loaded at compile rather than run time. This is because the :Test
689 attribute is applied by a CHECK block.
690
691 This can be problematic if you want to dynamically load Test::Class
692 modules. Basically while:
693
694 require $some_test_class;
695
696 will break, doing:
697
698 BEGIN { require $some_test_class }
699
700 will work just fine. For more information on CHECK blocks see "BEGIN,
701 CHECK, INIT and END" in perlmod.
702
703 If you still can't arrange for your classes to be loaded at runtime, you
704 could use an alternative mechanism for adding your tests:
705
706 # sub test_something : Test(3) {...}
707 # becomes
708 sub test_something {...}
709 __PACKAGE__->add_testinfo('test_something', test => 3);
710
711 See the add_testinfo method for more details.
712
713 Additionally, if you've forgotten to enable warnings and have two test
714 subs called the same thing, you will get the same error.
715
716 GENERAL FILTERING OF TESTS
717 The use of $ENV{TEST_METHOD} to run just a subset of tests is useful,
718 but sometimes it doesn't give the level of granularity that you desire.
719 Another feature of this class is the ability to do filtering on other
720 static criteria. In order to permit this, a generic filtering method is
721 supported. This can be used by specifying coderefs to the 'add_filter'
722 method of this class.
723
724 In determining which tests should be run, all filters that have
725 previously been specified via the add_filter method will be run in-turn
726 for each normal test method. If any of these filters return a false
727 value, the method will not be executed, or included in the number of
728 tests. Note that filters will only be run for normal test methods, they
729 are ignored for startup, shutdown, setup, and teardown test methods.
730
731 Note that test filters are global, and will affect all tests in all
732 classes, not just the one that they were defined in.
733
734 An example of this mechanism that mostly simulates the use of
735 TEST_METHOD above is:
736
737 package MyTests;
738
739 use Test::More;
740
741 use base qw( Test::Class );
742
743 my $MYTEST_METHOD = qr/^t_not_filtered$/;
744
745 my $filter = sub {
746 my ( $test_class, $test_method ) = @_;
747
748 return $test_method =~ $MYTEST_METHOD;
749 }
750 Test::Class->add_filter( $filter );
751
752 sub t_filtered : Test( 1 ) {
753 fail( "filtered test run" );
754 }
755
756 sub t_not_filtered : Test( 1 ) {
757 pass( "unfiltered test run" );
758 }
759
760 METHODS
761 Creating and running tests
762 Test
763 # test methods
764 sub method_name : Test { ... }
765 sub method_name : Test(N) { ... }
766
767 # setup methods
768 sub method_name : Test(setup) { ... }
769 sub method_name : Test(setup => N) { ... }
770
771 # teardown methods
772 sub method_name : Test(teardown) { ... }
773 sub method_name : Test(teardown => N) { ... }
774
775 # startup methods
776 sub method_name : Test(startup) { ... }
777 sub method_name : Test(startup => N) { ... }
778
779 # shutdown methods
780 sub method_name : Test(shutdown) { ... }
781 sub method_name : Test(shutdown => N) { ... }
782
783 Marks a startup, setup, test, teardown or shutdown method. See
784 runtests() for information on how to run methods declared with the
785 "Test" attribute.
786
787 N specifies the number of tests the method runs.
788
789 * If N is an integer then the method should run exactly N tests.
790
791 * If N is an integer with a "+" prefix then the method is expected
792 to call its "SUPER::" method and extend it by running N
793 additional tests.
794
795 * If N is the string "no_plan" then the method can run an
796 arbitrary number of tests.
797
798 If N is not specified it defaults to 1 for test methods, and 0 for
799 startup, setup, teardown and shutdown methods.
800
801 You can change the number of tests that a method runs using
802 num_method_tests() or num_tests().
803
804 Tests
805 sub method_name : Tests { ... }
806 sub method_name : Tests(N) { ... }
807
808 Acts just like the ":Test" attribute, except that if the number of
809 tests is not specified it defaults to "no_plan". So the following
810 are equivalent:
811
812 sub silly1 :Test( no_plan ) { ok(1) foreach (1 .. rand 5) }
813 sub silly2 :Tests { ok(1) foreach (1 .. rand 5) }
814
815 new
816 $Tests = CLASS->new(KEY => VAL ...)
817 $Tests2 = $Tests->new(KEY => VAL ...)
818
819 Creates a new test object (blessed hashref) containing the specified
820 key/value pairs.
821
822 If called as an object method the existing object's key/value pairs
823 are copied into the new object. Any key/value pairs passed to "new"
824 override those in the original object if duplicates occur.
825
826 Since the test object is passed to every test method as it runs, it
827 is a convenient place to store test fixtures. For example:
828
829 sub make_fixture : Test(setup) {
830 my $self = shift;
831 $self->{object} = Object->new();
832 $self->{dbh} = Mock::DBI->new(-type => normal);
833 }
834
835 sub test_open : Test {
836 my $self = shift;
837 my ($o, $dbh) = ($self->{object}, $self->{dbh});
838 ok($o->open($dbh), "opened ok");
839 }
840
841 See num_method_tests() for an example of overriding "new".
842
843 expected_tests
844 $n = $Tests->expected_tests
845 $n = CLASS->expected_tests
846 $n = $Tests->expected_tests(TEST, ...)
847 $n = CLASS->expected_tests(TEST, ...)
848
849 Returns the total number of tests that runtests() will run on the
850 specified class/object. This includes tests run by any setup and
851 teardown methods.
852
853 Will return "no_plan" if the exact number of tests is undetermined
854 (i.e. if any setup, test or teardown method has an undetermined
855 number of tests).
856
857 The "expected_tests" of an object after runtests() has been executed
858 will include any run time changes to the expected number of tests
859 made by num_tests() or num_method_tests().
860
861 "expected_tests" can also take an optional list of test objects,
862 test classes and integers. In this case the result is the total
863 number of expected tests for all the test/object classes (including
864 the one the method was applied to) plus any integer values.
865
866 "expected_tests" is useful when you're integrating one or more test
867 classes into a more traditional test script, for example:
868
869 use Test::More;
870 use My::Test::Class;
871
872 plan tests => My::Test::Class->expected_tests(+2);
873
874 ok(whatever, 'a test');
875 ok(whatever, 'another test');
876 My::Test::Class->runtests;
877
878 runtests
879 $allok = $Tests->runtests
880 $allok = CLASS->runtests
881 $allok = $Tests->runtests(TEST, ...)
882 $allok = CLASS->runtests(TEST, ...)
883
884 "runtests" is used to run test classes. At its most basic doing:
885
886 $test->runtests
887
888 will run the test methods of the test object $test, unless
889 "$test->SKIP_CLASS" returns a true value.
890
891 Unless you have already specified a test plan using Test::Builder
892 (or Test::More, et al) "runtests" will set the test plan just before
893 the first method that runs a test is executed.
894
895 If the environment variable "TEST_VERBOSE" is set "runtests" will
896 display the name of each test method before it runs like this:
897
898 # My::Test::Class->my_test
899 ok 1 - fribble
900 # My::Test::Class->another_test
901 ok 2 - bar
902
903 Just like expected_tests(), "runtests" can take an optional list of
904 test object/classes and integers. All of the test object/classes are
905 run. Any integers are added to the total number of tests shown in
906 the test header output by "runtests".
907
908 For example, you can run all the tests in test classes A, B and C,
909 plus one additional normal test by doing:
910
911 Test::Class->runtests(qw(A B C), +1);
912 ok(1==1, 'non class test');
913
914 Finally, if you call "runtests" on a test class without any
915 arguments it will run all of the test methods of that class, and all
916 subclasses of that class. For example:
917
918 #! /usr/bin/perl
919 # Test all the Foo stuff
920
921 use Foo::Test;
922 use Foo::Bar::Test;
923 use Foo::Ni::Test;
924
925 # run all the Foo*Test modules we just loaded
926 Test::Class->runtests;
927
928 SKIP_CLASS
929 $reason = CLASS->SKIP_CLASS;
930 CLASS->SKIP_CLASS( $reason );
931
932 Determines whether the test class CLASS should run it's tests. If
933 SKIP_CLASS returns a true value then runtests() will not run any of
934 the test methods in CLASS.
935
936 You can override the default on a class-by-class basis by supplying
937 a new value to SKIP_CLASS. For example if you have an abstract base
938 class that should not run just add the following to your module:
939
940 My::Abstract::Test->SKIP_CLASS( 1 );
941
942 This will not affect any sub-classes of "My::Abstract::Test" which
943 will run as normal.
944
945 If the true value returned by SKIP_CLASS is anything other than "1"
946 then a skip test is output using this value as the skip message. For
947 example:
948
949 My::Postgres::Test->SKIP_CLASS(
950 $ENV{POSTGRES_HOME} ? 0 : '$POSTGRES_HOME needs to be set'
951 );
952
953 will output something like this if "POSTGRES_HOME" is not set
954
955 ... other tests ...
956 ok 123 # skip My::Postgres::Test - $POSTGRES_HOME needs to be set
957 ... more tests ...
958
959 You can also override SKIP_CLASS for a class hierarchy. For example,
960 to prevent any subclasses of My::Postgres::Test running we could
961 override SKIP_CLASS like this:
962
963 sub My::Postgres::Test::SKIP_CLASS {
964 $ENV{POSTGRES_HOME} ? 0 : '$POSTGRES_HOME needs to be set'
965 }
966
967 Fetching and setting a method's test number
968 num_method_tests
969 $n = $Tests->num_method_tests($method_name)
970 $Tests->num_method_tests($method_name, $n)
971 $n = CLASS->num_method_tests($method_name)
972 CLASS->num_method_tests($method_name, $n)
973
974 Fetch or set the number of tests that the named method is expected
975 to run.
976
977 If the method has an undetermined number of tests then $n should be
978 the string "no_plan".
979
980 If the method is extending the number of tests run by the method in
981 a superclass then $n should have a "+" prefix.
982
983 When called as a class method any change to the expected number of
984 tests applies to all future test objects. Existing test objects are
985 unaffected.
986
987 When called as an object method any change to the expected number of
988 tests applies to that object alone.
989
990 "num_method_tests" is useful when you need to set the expected
991 number of tests at object creation time, rather than at compile
992 time.
993
994 For example, the following test class will run a different number of
995 tests depending on the number of objects supplied.
996
997 package Object::Test;
998 use base qw(Test::Class);
999 use Test::More;
1000
1001 sub new {
1002 my $class = shift;
1003 my $self = $class->SUPER::new(@_);
1004 my $num_objects = @{$self->{objects}};
1005 $self->num_method_tests('test_objects', $num_objects);
1006 return($self);
1007 }
1008
1009 sub test_objects : Tests {
1010 my $self = shift;
1011 ok($_->open, "opened $_") foreach @{$self->{objects}};
1012 }
1013 ...
1014 # This runs two tests
1015 Object::Test->new(objects => [$o1, $o2]);
1016
1017 The advantage of setting the number of tests at object creation
1018 time, rather than using a test method without a plan, is that the
1019 number of expected tests can be determined before testing begins.
1020 This allows better diagnostics from runtests(), Test::Builder and
1021 Test::Harness.
1022
1023 "num_method_tests" is a protected method and can only be called by
1024 subclasses of Test::Class. It fetches or sets the expected number of
1025 tests for the methods of the class it was *called in*, not the
1026 methods of the object/class it was *applied to*. This allows test
1027 classes that use "num_method_tests" to be subclassed easily.
1028
1029 For example, consider the creation of a subclass of Object::Test
1030 that ensures that all the opened objects are read-only:
1031
1032 package Special::Object::Test;
1033 use base qw(Object::Test);
1034 use Test::More;
1035
1036 sub test_objects : Test(+1) {
1037 my $self = shift;
1038 $self->SUPER::test_objects;
1039 my @bad_objects = grep {! $_->read_only} (@{$self->{objects}});
1040 ok(@bad_objects == 0, "all objects read only");
1041 }
1042 ...
1043 # This runs three tests
1044 Special::Object::Test->new(objects => [$o1, $o2]);
1045
1046 Since the call to "num_method_tests" in Object::Test only affects
1047 the "test_objects" of Object::Test, the above works as you would
1048 expect.
1049
1050 num_tests
1051 $n = $Tests->num_tests
1052 $Tests->num_tests($n)
1053 $n = CLASS->num_tests
1054 CLASS->num_tests($n)
1055
1056 Set or return the number of expected tests associated with the
1057 currently running test method. This is the same as calling
1058 num_method_tests() with a method name of current_method().
1059
1060 For example:
1061
1062 sub txt_files_readable : Tests {
1063 my $self = shift;
1064 my @files = <*.txt>;
1065 $self->num_tests(scalar(@files));
1066 ok(-r $_, "$_ readable") foreach (@files);
1067 }
1068
1069 Setting the number of expected tests at run time, rather than just
1070 having a "no_plan" test method, allows runtests() to display
1071 appropriate diagnostic messages if the method runs a different
1072 number of tests.
1073
1074 Support methods
1075 builder
1076 $Tests->builder
1077
1078 Returns the underlying Test::Builder object that Test::Class uses.
1079 For example:
1080
1081 sub test_close : Test {
1082 my $self = shift;
1083 my ($o, $dbh) = ($self->{object}, $self->{dbh});
1084 $self->builder->ok($o->close($dbh), "closed ok");
1085 }
1086
1087 current_method
1088 $method_name = $Tests->current_method
1089 $method_name = CLASS->current_method
1090
1091 Returns the name of the test method currently being executed by
1092 runtests(), or "undef" if runtests() has not been called.
1093
1094 The method name is also available in the setup and teardown methods
1095 that run before and after the test method. This can be useful in
1096 producing diagnostic messages, for example:
1097
1098 sub test_invarient : Test(teardown => 1) {
1099 my $self = shift;
1100 my $m = $self->current_method;
1101 ok($self->invarient_ok, "class okay after $m");
1102 }
1103
1104 BAILOUT
1105 $Tests->BAILOUT($reason)
1106 CLASS->BAILOUT($reason)
1107
1108 Things are going so badly all testing should terminate, including
1109 running any additional test scripts invoked by Test::Harness. This
1110 is exactly the same as doing:
1111
1112 $self->builder->BAILOUT
1113
1114 See "BAILOUT" in Test::Builder for details. Any teardown and
1115 shutdown methods are *not* run.
1116
1117 FAIL_ALL
1118 $Tests->FAIL_ALL($reason)
1119 CLASS->FAIL_ALL($reason)
1120
1121 Things are going so badly all the remaining tests in the current
1122 script should fail. Exits immediately with the number of tests
1123 failed, or 254 if more than 254 tests were run. Any teardown methods
1124 are *not* run.
1125
1126 This does not affect the running of any other test scripts invoked
1127 by Test::Harness.
1128
1129 For example, if all your tests rely on the ability to create objects
1130 then you might want something like this as an early test:
1131
1132 sub _test_new : Test(3) {
1133 my $self = shift;
1134 isa_ok(Object->new, "Object")
1135 || $self->FAIL_ALL('cannot create Objects');
1136 ...
1137 }
1138
1139 SKIP_ALL
1140 $Tests->SKIP_ALL($reason)
1141 CLASS->SKIP_ALL($reason)
1142
1143 Things are going so badly all the remaining tests in the current
1144 script should be skipped. Exits immediately with 0 - teardown
1145 methods are *not* run.
1146
1147 This does not affect the running of any other test scripts invoked
1148 by Test::Harness.
1149
1150 For example, if you had a test script that only applied to the
1151 darwin OS you could write:
1152
1153 sub _darwin_only : Test(setup) {
1154 my $self = shift;
1155 $self->SKIP_ALL("darwin only") unless $^O eq "darwin";
1156 }
1157
1158 add_testinfo
1159 CLASS->add_testinfo($name, $type, $num_tests)
1160
1161 Chiefly for use by libraries like Test::Class::Sugar, which can't
1162 use the ":Test(...)" interfaces make test methods. "add_testinfo"
1163 informs the class about a test method that has been defined without
1164 a "Test", "Tests" or other attribute.
1165
1166 $name is the name of the method, $type must be one of "startup",
1167 "setup", "test", "teardown" or "shutdown", and $num_tests has the
1168 same meaning as "N" in the description of the Test attribute.
1169
1170 add_filter
1171 CLASS->add_filter($filter_coderef);
1172
1173 Adds a filtering coderef. Each filter is passed a test class and
1174 method name and returns a boolean. All filters are applied globally
1175 in the order they were added. If any filter returns false the test
1176 method is not run or included in the number of tests.
1177
1178 Note that filters will only be run for normal test methods, they are
1179 ignored for startup, shutdown, setup, and teardown test methods.
1180
1181 See the section on the "GENERAL FILTERING OF TESTS" for more
1182 information.
1183
1184 fail_if_returned_early
1185 Controls what happens if a method returns before it has run all of
1186 its tests. It is called with no arguments in boolean context; if it
1187 returns true, then the missing tests fail, otherwise, they skip. See
1188 "Returning Early" and "Skipped Tests".
1189
1190 fail_if_returned_late
1191 Controls what happens if a method returns after running too many
1192 tests. It is called with no arguments in boolean context; if it
1193 returns true, then the extra tests trigger a failure test. See
1194 "Returning Late" and "Skipped Tests".
1195
1196 HELP FOR CONFUSED JUNIT USERS
1197 This section is for people who have used JUnit (or similar) and are
1198 confused because they don't see the TestCase/Suite/Runner class
1199 framework they were expecting. Here we take each of the major classes in
1200 JUnit and compare them with their equivalent Perl testing modules.
1201
1202 Class Assert
1203 The test assertions provided by Assert correspond to the test
1204 functions provided by the Test::Builder based modules (Test::More,
1205 Test::Exception, Test::Differences, etc.)
1206
1207 Unlike JUnit the test functions supplied by Test::More et al do
1208 *not* throw exceptions on failure. They just report the failure to
1209 STDOUT where it is collected by Test::Harness. This means that where
1210 you have
1211
1212 sub foo : Test(2) {
1213 ok($foo->method1);
1214 ok($foo->method2);
1215 }
1216
1217 The second test *will* run if the first one fails. You can emulate
1218 the JUnit way of doing it by throwing an explicit exception on test
1219 failure:
1220
1221 sub foo : Test(2) {
1222 ok($foo->method1) or die "method1 failed";
1223 ok($foo->method2);
1224 }
1225
1226 The exception will be caught by Test::Class and the other test
1227 automatically failed.
1228
1229 Class TestCase
1230 Test::Class corresponds to TestCase in JUnit.
1231
1232 In Test::Class setup, test and teardown methods are marked
1233 explicitly using the Test attribute. Since we need to know the total
1234 number of tests to provide a test plan for Test::Harness, we also
1235 state how many tests each method runs.
1236
1237 Unlike JUnit you can have multiple setup/teardown methods in a
1238 class.
1239
1240 Class TestSuite
1241 Test::Class also does the work that would be done by TestSuite in
1242 JUnit.
1243
1244 Since the methods are marked with attributes, Test::Class knows what
1245 is and isn't a test method. This allows it to run all the test
1246 methods without having the developer create a suite manually, or use
1247 reflection to dynamically determine the test methods by name. See
1248 the runtests() method for more details.
1249
1250 The running order of the test methods is fixed in Test::Class.
1251 Methods are executed in alphabetical order.
1252
1253 To run individual test methods, see "RUNNING INDIVIDUAL TESTS".
1254
1255 Class TestRunner
1256 Test::Harness does the work of the TestRunner in JUnit. It collects
1257 the test results (sent to STDOUT) and collates the results.
1258
1259 Unlike JUnit there is no distinction made by Test::Harness between
1260 errors and failures. However, it does support skipped and todo test
1261 - which JUnit does not.
1262
1263 If you want to write your own test runners you should look at
1264 Test::Harness::Straps.
1265
1266 OTHER MODULES FOR XUNIT TESTING IN PERL
1267 In addition to Test::Class there are two other distributions for xUnit
1268 testing in perl. Both have a longer history than Test::Class and might
1269 be more suitable for your needs.
1270
1271 I am biased since I wrote Test::Class - so please read the following
1272 with appropriate levels of scepticism. If you think I have
1273 misrepresented the modules please let me know.
1274
1275 Test::SimpleUnit
1276 A very simple unit testing framework. If you are looking for a
1277 lightweight single module solution this might be for you.
1278
1279 The advantage of Test::SimpleUnit is that it is simple! Just one
1280 module with a smallish API to learn.
1281
1282 Of course this is also the disadvantage.
1283
1284 It's not class based so you cannot create testing classes to reuse
1285 and extend.
1286
1287 It doesn't use Test::Builder so it's difficult to extend or
1288 integrate with other testing modules. If you are already familiar
1289 with Test::Builder, Test::More and friends you will have to learn a
1290 new test assertion API. It does not support todo tests.
1291
1292 Test::Unit
1293 Test::Unit is a port of JUnit <http://www.junit.org/> into perl. If
1294 you have used JUnit then the Test::Unit framework should be very
1295 familiar.
1296
1297 It is class based so you can easily reuse your test classes and
1298 extend by subclassing. You get a nice flexible framework you can
1299 tweak to your heart's content. If you can run Tk you also get a
1300 graphical test runner.
1301
1302 However, Test::Unit is not based on Test::Builder. You cannot easily
1303 move Test::Builder based test functions into Test::Unit based
1304 classes. You have to learn another test assertion API.
1305
1306 Test::Unit implements it's own testing framework separate from
1307 Test::Harness. You can retrofit *.t scripts as unit tests, and
1308 output test results in the format that Test::Harness expects, but
1309 things like todo tests and skipping tests are not supported.
1310
1311 SUPPORT
1312 Bugs may be submitted through GitHub issues
1313 <https://github.com/szabgab/test-class/issues>
1314
1315 There is also an irc channel available for users of this distribution,
1316 at "#perl-qa" on "irc.perl.org" <irc://irc.perl.org/#perl-qa>.
1317
1318 TO DO
1319 If you think this module should do something that it doesn't (or does
1320 something that it shouldn't) please let me know.
1321
1322 You can see an old to do list at
1323 <http://adrianh.tadalist.com/lists/public/4798>, with an RSS feed of
1324 changes at <http://adrianh.tadalist.com/lists/feed_public/4798>.
1325
1326 ACKNOWLEDGMENTS
1327 This is yet another implementation of the ideas from Kent Beck's Testing
1328 Framework paper <http://www.xprogramming.com/testfram.htm>.
1329
1330 Thanks to Adam Kennedy, agianni, Alexander D'Archangel, Andrew
1331 Grangaard, Apocalypse, Ask Bjorn Hansen, Chris Dolan, Chris Williams,
1332 Corion, Cosimo Streppone, Daniel Berger, Dave Evans, Dave O'Neill, David
1333 Cantrell, David Wheeler, Diab Jerius, Emil Jansson, Gunnar Wolf, Hai
1334 Pham, Hynek, imacat, Jeff Deifik, Jim Brandt, Jochen Stenzel, Johan
1335 Lindstrom, John West, Jonathan R. Warden, Joshua ben Jore, Jost Krieger,
1336 Ken Fox, Kenichi Ishigaki Lee Goddard, Mark Morgan, Mark Reynolds, Mark
1337 Stosberg, Martin Ferrari, Mathieu Sauve-Frankel, Matt Trout, Matt
1338 Williamson, Michael G Schwern, Murat Uenalan, Naveed Massjouni, Nicholas
1339 Clark, Ovid, Piers Cawley, Rob Kinyon, Sam Raymer, Scott Lanning,
1340 Sebastien Aperghis-Tramoni, Steve Kirkup, Stray Toaster, Ted Carnahan,
1341 Terrence Brannon, Todd W, Tom Metro, Tony Bowden, Tony Edwardson,
1342 William McKee, various anonymous folk and all the fine people on perl-qa
1343 for their feedback, patches, suggestions and nagging.
1344
1345 This module wouldn't be possible without the excellent Test::Builder.
1346 Thanks to chromatic and Michael G Schwern for creating such a useful
1347 module.
1348
1349 AUTHORS
1350 Adrian Howard <[email protected]>, Curtis "Ovid" Poe, <ovid at
1351 cpan.org>, Mark Morgan <[email protected]>.
1352
1353 SEE ALSO
1354 Test::Class::Load
1355 Simple way to load "Test::Class" classes automatically.
1356
1357 Test::Class::Most
1358 Test::Class with additional conveniences to reduce need for some
1359 boilerplate code. Also makes Test::Most testing functions available.
1360
1361 Test::Class::Moose
1362 Testing framework allows you to write your tests in Moose and test
1363 Moose and non-Moose code. It offers reporting, extensibility, test
1364 inheritance, parallel testing and more.
1365
1366 Perl Testing: A Developer's Notebook by Ian Langworth and chromatic
1367 Chapter 8 covers using Test::Class.
1368
1369 Advanced Perl Programming, second edition by Simon Cozens
1370 Chapter 8 has a few pages on using Test::Class.
1371
1372 The Perl Journal, April 2003
1373 Includes the article "Test-Driven Development in Perl" by Piers
1374 Cawley that uses Test::Class.
1375
1376 Test::Class Tutorial series written by Curtis "Ovid" Poe
1377
1378 * Organizing Test Suites with Test::Class
1379 <http://www.modernperlbooks.com/mt/2009/03/organizing-test-suite
1380 s-with-testclass.html>
1381
1382 * Reusing Test Code with Test::Class
1383 <http://www.modernperlbooks.com/mt/2009/03/reusing-test-code-wit
1384 h-testclass.html>
1385
1386 * Making Your Testing Life Easier
1387 <http://www.modernperlbooks.com/mt/2009/03/making-your-testing-l
1388 ife-easier.html>
1389
1390 * Using Test Control Methods with Test::Class
1391 <http://www.modernperlbooks.com/mt/2009/03/using-test-control-me
1392 thods-with-testclass.html>
1393
1394 * Working with Test::Class Test Suites
1395 <http://www.modernperlbooks.com/mt/2009/03/working-with-testclas
1396 s-test-suites.html>
1397
1398 Test::Builder
1399 Support module for building test libraries.
1400
1401 Test::Simple & Test::More
1402 Basic utilities for writing tests.
1403
1404 <https://qa.perl.org/test-modules.html>
1405 Overview of some of the many testing modules available on CPAN.
1406
1407 Test::Object
1408 Another approach to object oriented testing.
1409
1410 Test::Group and Test::Block
1411 Alternatives to grouping sets of tests together.
1412
1413 The following modules use Test::Class as part of their test suite. You
1414 might want to look at them for usage examples:
1415
1416 App-GitGot, Aspect, Bricolage (<http://www.bricolage.cc/>), CHI,
1417 Cinnamon, Class::StorageFactory, CGI::Application::Search,
1418 DBIx::Romani, Xmldoom, Object::Relational, File::Random,
1419 Geography::JapanesePrefectures, Google::Adwords, Merge::HashRef,
1420 PerlBuildSystem, Ubic, Pixie, Yahoo::Marketing, and XUL-Node
1421
1422 The following modules are not based on Test::Builder, but may be of
1423 interest as alternatives to Test::Class.
1424
1425 Test::Unit
1426 Perl unit testing framework closely modeled on JUnit.
1427
1428 Test::SimpleUnit
1429 A very simple unit testing framework.
1430
1431 LICENCE
1432 Copyright 2002-2010 Adrian Howard, All Rights Reserved.
1433
1434 This program is free software; you can redistribute it and/or modify it
1435 under the same terms as Perl itself.
1436