1Test::Class(3)        User Contributed Perl Documentation       Test::Class(3)
2
3
4

NAME

6       Test::Class - Easily create test classes in an xUnit/JUnit style
7

VERSION

9       version 0.50
10

SYNOPSIS

12         package Example::Test;
13         use base qw(Test::Class);
14         use Test::More;
15
16         # setup methods are run before every test method.
17         sub make_fixture : Test(setup) {
18             my $array = [1, 2];
19             shift->{test_array} = $array;
20         }
21
22         # a test method that runs 1 test
23         sub test_push : Test {
24             my $array = shift->{test_array};
25             push @$array, 3;
26             is_deeply($array, [1, 2, 3], 'push worked');
27         }
28
29         # a test method that runs 4 tests
30         sub test_pop : Test(4) {
31             my $array = shift->{test_array};
32             is(pop @$array, 2, 'pop = 2');
33             is(pop @$array, 1, 'pop = 1');
34             is_deeply($array, [], 'array empty');
35             is(pop @$array, undef, 'pop = undef');
36         }
37
38         # teardown methods are run after every test method.
39         sub teardown : Test(teardown) {
40             my $array = shift->{test_array};
41             diag("array = (@$array) after test(s)");
42         }
43
44       later in a nearby .t file
45
46         #! /usr/bin/perl
47         use Example::Test;
48
49         # run all the test methods in Example::Test
50         Test::Class->runtests;
51
52       Outputs:
53
54         1..5
55         ok 1 - pop = 2
56         ok 2 - pop = 1
57         ok 3 - array empty
58         ok 4 - pop = undef
59         # array = () after test(s)
60         ok 5 - push worked
61         # array = (1 2 3) after test(s)
62

DESCRIPTION

64       Test::Class provides a simple way of creating classes and objects to
65       test your code in an xUnit style.
66
67       Built using Test::Builder, it was designed to work with other
68       Test::Builder based modules (Test::More, Test::Differences,
69       Test::Exception, etc.).
70
71       Note: This module will make more sense, if you are already familiar
72       with the "standard" mechanisms for testing perl code. Those unfamiliar
73       with Test::Harness, Test::Simple, Test::More and friends should go take
74       a look at them now. Test::Tutorial is a good starting point.
75

INTRODUCTION

77   A brief history lesson
78       In 1994 Kent Beck wrote a testing framework for Smalltalk called SUnit.
79       It was popular. You can read a copy of his original paper at
80       <http://www.xprogramming.com/testfram.htm>.
81
82       Later Kent Beck and Erich Gamma created JUnit for testing Java
83       <http://www.junit.org/>. It was popular too.
84
85       Now there are xUnit frameworks for every language from Ada to XSLT. You
86       can find a list at <http://www.xprogramming.com/software.htm>.
87
88       While xUnit frameworks are traditionally associated with unit testing
89       they are also useful in the creation of functional/acceptance tests.
90
91       Test::Class is (yet another) implementation of xUnit style testing in
92       Perl.
93
94   Why you should use Test::Class
95       Test::Class attempts to provide simple xUnit testing that integrates
96       simply with the standard perl *.t style of testing. In particular:
97
98       ·   All the advantages of xUnit testing. You can easily create test
99           fixtures and isolate tests. It provides a framework that should be
100           familiar to people who have used other xUnit style test systems.
101
102       ·   It is built with Test::Builder and should co-exist happily with all
103           other Test::Builder based modules. This makes using test classes in
104           *.t scripts, and refactoring normal tests into test classes, much
105           simpler because:
106
107           ·   You do not have to learn a new set of new test APIs and can
108               continue using ok(), like(), etc. from Test::More and friends.
109
110           ·   Skipping tests and todo tests are supported.
111
112           ·   You can have normal tests and Test::Class classes co-existing
113               in the same *.t script. You don't have to re-write an entire
114               script, but can use test classes as and when it proves useful.
115
116       ·   You can easily package your tests as classes/modules, rather than
117           *.t scripts. This simplifies reuse, documentation and distribution,
118           encourages refactoring, and allows tests to be extended by
119           inheritance.
120
121       ·   You can have multiple setup/teardown methods. For example have one
122           teardown method to clean up resources and another to check that
123           class invariants still hold.
124
125       ·   It can make running tests faster. Once you have refactored your *.t
126           scripts into classes they can be easily run from a single script.
127           This gains you the (often considerable) start up time that each
128           separate *.t script takes.
129
130   Why you should not use Test::Class
131       ·   If your *.t scripts are working fine then don't bother with
132           Test::Class. For simple test suites it is almost certainly
133           overkill. Don't start thinking about using Test::Class until issues
134           like duplicate code in your test scripts start to annoy.
135
136       ·   If you are distributing your code it is yet another module that the
137           user has to have to run your tests (unless you distribute it with
138           your test suite of course).
139
140       ·   If you are used to the TestCase/Suite/Runner class structure used
141           by JUnit and similar testing frameworks you may find Test::Unit
142           more familiar (but try reading "HELP FOR CONFUSED JUNIT USERS"
143           before you give up).
144

TEST CLASSES

146       A test class is just a class that inherits from Test::Class. Defining a
147       test class is as simple as doing:
148
149         package Example::Test;
150         use base qw(Test::Class);
151
152       Since Test::Class does not provide its own test functions, but uses
153       those provided by Test::More and friends, you will nearly always also
154       want to have:
155
156         use Test::More;
157
158       to import the test functions into your test class.
159

METHOD TYPES

161       There are three different types of method you can define using
162       Test::Class.
163
164   1) Test methods
165       You define test methods using the Test attribute. For example:
166
167         package Example::Test;
168         use base qw(Test::Class);
169         use Test::More;
170
171         sub subtraction : Test {
172             is( 2-1, 1, 'subtraction works' );
173         }
174
175       This declares the "subtraction" method as a test method that runs one
176       test.
177
178       If your test method runs more than one test, you should put the number
179       of tests in brackets like this:
180
181         sub addition : Test(2) {
182             is(10 + 20, 30, 'addition works');
183             is(20 + 10, 30, '  both ways');
184         }
185
186       If you don't know the number of tests at compile time you can use
187       "no_plan" like this.
188
189         sub check_class : Test(no_plan) {
190             my $objects = shift->{objects};
191             isa_ok($_, "Object") foreach @$objects;
192         }
193
194       or use the :Tests attribute, which acts just like ":Test" but defaults
195       to "no_plan" if no number is given:
196
197         sub check_class : Tests {
198             my $objects = shift->{objects};
199             isa_ok($_, "Object") foreach @$objects;
200         }
201
202   2) Setup and teardown methods
203       Setup and teardown methods are run before and after every test. For
204       example:
205
206         sub before : Test(setup)    { diag("running before test") }
207         sub after  : Test(teardown) { diag("running after test") }
208
209       You can use setup and teardown methods to create common objects used by
210       all of your test methods (a test fixture) and store them in your
211       Test::Class object, treating it as a hash. For example:
212
213         sub pig : Test(setup) {
214             my $self = shift;
215             $self->{test_pig} = Pig->new;
216         }
217
218         sub born_hungry : Test {
219             my $pig = shift->{test_pig};
220             is($pig->hungry, 'pigs are born hungry');
221         }
222
223         sub eats : Test(3) {
224             my $pig = shift->{test_pig};
225             ok(  $pig->feed,   'pig fed okay');
226             ok(! $pig->hungry, 'fed pig not hungry');
227             ok(! $pig->feed,   'cannot feed full pig');
228         }
229
230       You can also declare setup and teardown methods as running tests. For
231       example you could check that the test pig survives each test method by
232       doing:
233
234         sub pig_alive : Test(teardown => 1) {
235             my $pig = shift->{test_pig};
236             ok($pig->alive, 'pig survived tests' );
237         }
238
239   3) Startup and shutdown methods
240       Startup and shutdown methods are like setup and teardown methods for
241       the whole test class. All the startup methods are run once when you
242       start running a test class. All the shutdown methods are run once just
243       before a test class stops running.
244
245       You can use these to create and destroy expensive objects that you
246       don't want to have to create and destroy for every test - a database
247       connection for example:
248
249         sub db_connect : Test(startup) {
250             shift->{dbi} = DBI->connect;
251         }
252
253         sub db_disconnect : Test(shutdown) {
254             shift->{dbi}->disconnect;
255         }
256
257       Just like setup and teardown methods you can pass an optional number of
258       tests to startup and shutdown methods. For example:
259
260         sub example : Test(startup => 1) {
261             ok(1, 'a startup method with one test');
262         }
263
264       If you want to run an unknown number of tests within your startup
265       method, you need to say e.g.
266
267         sub example : Test(startup => no_plan) {
268            ok(1, q{The first of many tests that don't want to have to count});
269            ...
270         }
271
272       as the : Tests attribute behaves exactly like : Test in this context.
273
274       If a startup method has a failing test or throws an exception then all
275       other tests for the current test object are ignored.
276

RUNNING TESTS

278       You run test methods with runtests(). Doing:
279
280         Test::Class->runtests
281
282       runs all of the test methods in every loaded test class. This allows
283       you to easily load multiple test classes in a *.t file and run them
284       all.
285
286         #! /usr/bin/perl
287
288         # load all the test classes I want to run
289         use Foo::Test;
290         use Foo::Bar::Test;
291         use Foo::Fribble::Test;
292         use Foo::Ni::Test;
293
294         # and run them all
295         Test::Class->runtests;
296
297       You can use Test::Class::Load to automatically load all the test
298       classes in a given set of directories.
299
300       If you need finer control you can create individual test objects with
301       new(). For example to just run the tests in the test class
302       "Foo::Bar::Test" you can do:
303
304         Example::Test->new->runtests
305
306       You can also pass runtests() a list of test objects to run. For
307       example:
308
309         my $o1 = Example::Test->new;
310         my $o2 = Another::Test->new;
311         # runs all the tests in $o1 and $o2
312         $o1->runtests($o2);
313
314       Since, by definition, the base Test::Class has no tests, you could also
315       have written:
316
317         my $o1 = Example::Test->new;
318         my $o2 = Another::Test->new;
319         Test::Class->runtests($o1, $o2);
320
321       If you pass runtests() class names it will automatically create test
322       objects for you, so the above can be written more compactly as:
323
324         Test::Class->runtests(qw( Example::Test Another::Test ))
325
326       In all of the above examples runtests() will look at the number of
327       tests both test classes run and output an appropriate test header for
328       Test::Harness automatically.
329
330       What happens if you run test classes and normal tests in the same
331       script? For example:
332
333         Test::Class->runtests;
334         ok(Example->new->foo, 'a test not in the test class');
335         ok(Example->new->bar, 'ditto');
336
337       Test::Harness will complain that it saw more tests than it expected
338       since the test header output by runtests() will not include the two
339       normal tests.
340
341       To overcome this problem you can pass an integer value to runtests().
342       This is added to the total number of tests in the test header. So the
343       problematic example can be rewritten as follows:
344
345         Test::Class->runtests(+2);
346         ok(Example->new->foo, 'a test not in the test class');
347         ok(Example->new->bar, 'ditto');
348
349       If you prefer to write your test plan explicitly you can use
350       expected_tests() to find out the number of tests a class/object is
351       expected to run.
352
353       Since runtests() will not output a test plan if one has already been
354       set, the previous example can be written as:
355
356         plan tests => Test::Class->expected_tests(+2);
357         Test::Class->runtests;
358         ok(Example->new->foo, 'a test not in the test class');
359         ok(Example->new->bar, 'ditto');
360
361       Remember: Test objects are just normal perl objects. Test classes are
362       just normal perl classes. Setup, test and teardown methods are just
363       normal methods. You are completely free to have other methods in your
364       class that are called from your test methods, or have object specific
365       "new" and "DESTROY" methods.
366
367       In particular you can override the new() method to pass parameters to
368       your test object, or re-define the number of tests a method will run.
369       See num_method_tests() for an example.
370

TEST DESCRIPTIONS

372       The test functions you import from Test::More and other Test::Builder
373       based modules usually take an optional third argument that specifies
374       the test description, for example:
375
376         is $something, $something_else, 'a description of my test';
377
378       If you do not supply a test description, and the test function does not
379       supply its own default, then Test::Class will use the name of the
380       currently running test method, replacing all "_" characters with spaces
381       so:
382
383         sub one_plus_one_is_two : Test {
384             is 1+1, 2;
385         }
386
387       will result in:
388
389         ok 1 - one plus one is two
390

RUNNING ORDER OF METHODS

392       Methods of each type are run in the following order:
393
394       1.  All of the startup methods in alphabetical order
395
396       2.  For each test method, in alphabetical order:
397
398           · All of the setup methods in alphabetical order
399
400           · The test method.
401
402           · All of the teardown methods in alphabetical order
403
404       3.  All of the shutdown methods in alphabetical order.
405
406       Most of the time you should not care what order tests are run in, but
407       it can occasionally be useful to force some test methods to be run
408       early. For example:
409
410         sub _check_new {
411             my $self = shift;
412             isa_ok(Object->new, "Object") or $self->BAILOUT('new fails!');
413         }
414
415       The leading "_" will force the above method to run first - allowing the
416       entire suite to be aborted before any other test methods run.
417

HANDLING EXCEPTIONS

419       If a startup, setup, test, teardown or shutdown method dies then
420       runtests() will catch the exception and fail any remaining test. For
421       example:
422
423         sub test_object : Test(2) {
424             my $object = Object->new;
425             isa_ok( $object, "Object" ) or die "could not create object\n";
426             ok( $object->open, "open worked" );
427         }
428
429       will produce the following if the first test failed:
430
431         not ok 1 - The object isa Object
432         #   Failed test 'The object isa Object'
433         #   at /Users/adrianh/Desktop/foo.pl line 14.
434         #   (in MyTest->test_object)
435         #     The object isn't defined
436         not ok 2 - test_object died (could not create object)
437         #   Failed test 'test_object died (could not create object)'
438         #   at /Users/adrianh/Desktop/foo.pl line 19.
439         #   (in MyTest->test_object)
440
441       This can considerably simplify testing code that throws exceptions.
442
443       Rather than having to explicitly check that the code exited normally
444       (e.g. with "lives_ok" in Test::Exception) the test will fail
445       automatically - without aborting the other test methods. For example
446       contrast:
447
448         use Test::Exception;
449
450         my $file;
451         lives_ok { $file = read_file('test.txt') } 'file read';
452         is($file, "content", 'test file read');
453
454       with:
455
456         sub read_file : Test {
457             is(read_file('test.txt'), "content", 'test file read');
458         }
459
460       If more than one test remains after an exception then the first one is
461       failed, and the remaining ones are skipped.
462
463       If the setup method of a test method dies, then all of the remaining
464       setup and shutdown methods are also skipped.
465
466       Since startup methods will usually be creating state needed by all the
467       other test methods, an exception within a startup method will prevent
468       all other test methods of that class running.
469

RETURNING EARLY

471       If a test method returns before it has run all of its tests, by default
472       the missing tests are deemed to have been skipped; see "Skipped Tests"
473       for more information.
474
475       However, if the class's "fail_if_returned_early" method returns true,
476       then the missing tests will be deemed to have failed.  For example,
477
478         package MyClass;
479         use base 'Test::Class';
480         sub fail_if_returned_early { 1 }
481
482         sub oops : Tests(8) {
483           for (my $n=1; $n*$n<50; ++$n) {
484             ok 1, "$n squared is less than fifty";
485           }
486         }
487

SKIPPED TESTS

489       You can skip the rest of the tests in a method by returning from the
490       method before all the test have finished running (but see "Returning
491       Early" for how to change this). The value returned is used as the
492       reason for the tests being skipped.
493
494       This makes managing tests that can be skipped for multiple reasons very
495       simple. For example:
496
497         sub flying_pigs : Test(5) {
498             my $pig = Pig->new;
499             isa_ok($pig, 'Pig')           or return("cannot breed pigs")
500             can_ok($pig, 'takeoff')       or return("pigs don't fly here");
501             ok($pig->takeoff, 'takeoff')  or return("takeoff failed");
502             ok( $pig->altitude > 0, 'Pig is airborne' );
503             ok( $pig->airspeed > 0, '  and moving'    );
504         }
505
506       If you run this test in an environment where "Pig->new" worked and the
507       takeoff method existed, but failed when ran, you would get:
508
509         ok 1 - The object isa Pig
510         ok 2 - can takeoff
511         not ok 3 - takeoff
512         ok 4 # skip takeoff failed
513         ok 5 # skip takeoff failed
514
515       You can also skip tests just as you do in Test::More or Test::Builder -
516       see "Conditional tests" in Test::More for more information.
517
518       Note: if you want to skip tests in a method with "no_plan" tests then
519       you have to explicitly skip the tests in the method - since Test::Class
520       cannot determine how many tests (if any) should be skipped:
521
522         sub test_objects : Tests {
523             my $self = shift;
524             my $objects = $self->{objects};
525             if (@$objects) {
526                 isa_ok($_, "Object") foreach (@$objects);
527             } else {
528                 $self->builder->skip("no objects to test");
529             }
530         }
531
532       Another way of overcoming this problem is to explicitly set the number
533       of tests for the method at run time using num_method_tests() or
534       "num_tests".
535
536       You can make a test class skip all of its tests by setting SKIP_CLASS()
537       before runtests() is called.
538

TO DO TESTS

540       You can create todo tests just as you do in Test::More and
541       Test::Builder using the $TODO variable. For example:
542
543         sub live_test : Test  {
544             local $TODO = "live currently unimplemented";
545             ok(Object->live, "object live");
546         }
547
548       See "Todo tests" in Test::Harness for more information.
549

EXTENDING TEST CLASSES BY INHERITANCE

551       You can extend test methods by inheritance in the usual way. For
552       example consider the following test class for a "Pig" object.
553
554         package Pig::Test;
555         use base qw(Test::Class);
556         use Test::More;
557
558         sub testing_class { "Pig" }
559         sub new_args { (-age => 3) }
560
561         sub setup : Test(setup) {
562             my $self = shift;
563             my $class = $self->testing_class;
564             my @args = $self->new_args;
565             $self->{pig} = $class->new( @args );
566         }
567
568         sub _creation : Test {
569             my $self = shift;
570             isa_ok($self->{pig}, $self->testing_class)
571                     or $self->FAIL_ALL('Pig->new failed');
572         }
573
574         sub check_fields : Test {
575             my $pig = shift->{pig}
576             is($pig->age, 3, "age accessed");
577         }
578
579       Next consider "NamedPig" a subclass of "Pig" where you can give your
580       pig a name.
581
582       We want to make sure that all the tests for the "Pig" object still work
583       for "NamedPig". We can do this by subclassing "Pig::Test" and
584       overriding the "testing_class" and "new_args" methods.
585
586         package NamedPig::Test;
587         use base qw(Pig::Test);
588         use Test::More;
589
590         sub testing_class { "NamedPig" }
591         sub new_args { (shift->SUPER::new_args, -name => 'Porky') }
592
593       Now we need to test the name method. We could write another test
594       method, but we also have the option of extending the existing
595       "check_fields" method.
596
597         sub check_fields : Test(2) {
598             my $self = shift;
599             $self->SUPER::check_fields;
600             is($self->{pig}->name, 'Porky', 'name accessed');
601         }
602
603       While the above works, the total number of tests for the method is
604       dependent on the number of tests in its "SUPER::check_fields". If we
605       add a test to "Pig::Test->check_fields" we will also have to update the
606       number of tests of "NamedPig::test->check_fields".
607
608       Test::Class allows us to state explicitly that we are adding tests to
609       an existing method by using the "+" prefix. Since we are adding a
610       single test to "check_fields", it can be rewritten as:
611
612         sub check_fields : Test(+1) {
613             my $self = shift;
614             $self->SUPER::check_fields;
615             is($self->{pig}->name, 'Porky', 'name accessed');
616         }
617
618       With the above definition you can add tests to "check_fields" in
619       "Pig::Test" without affecting "NamedPig::Test".
620

RUNNING INDIVIDUAL TESTS

622       NOTE: The exact mechanism for running individual tests is likely to
623       change in the future.
624
625       Sometimes you just want to run a single test.  Commenting out other
626       tests or writing code to skip them can be a hassle, so you can specify
627       the "TEST_METHOD" environment variable.  The value is expected to be a
628       valid regular expression and, if present, only runs test methods whose
629       names match the regular expression.  Startup, setup, teardown and
630       shutdown tests will still be run.
631
632       One easy way of doing this is by specifying the environment variable
633       before the "runtests" method is called.
634
635       Running a test named "customer_profile":
636
637        #! /usr/bin/perl
638        use Example::Test;
639
640        $ENV{TEST_METHOD} = 'customer_profile';
641        Test::Class->runtests;
642
643       Running all tests with "customer" in their name:
644
645        #! /usr/bin/perl
646        use Example::Test;
647
648        $ENV{TEST_METHOD} = '.*customer.*';
649        Test::Class->runtests;
650
651       If you specify an invalid regular expression, your tests will not be
652       run:
653
654        #! /usr/bin/perl
655        use Example::Test;
656
657        $ENV{TEST_METHOD} = 'C++';
658        Test::Class->runtests;
659
660       And when you run it:
661
662        TEST_METHOD (C++) is not a valid regular expression: Search pattern \
663        not terminated at (eval 17) line 1.
664

ORGANISING YOUR TEST CLASSES

666       You can, of course, organise your test modules as you wish. My personal
667       preferences is:
668
669       ·   Name test classes with a suffix of "::Test" so the test class for
670           the "Foo::Bar" module would be "Foo::Bar::Test".
671
672       ·   Place all test classes in t/lib.
673
674       The Test::Class::Load provides a simple mechanism for easily loading
675       all of the test classes in a given set of directories.
676

A NOTE ON LOADING TEST CLASSES

678       Due to its use of subroutine attributes Test::Class based modules must
679       be loaded at compile rather than run time. This is because the :Test
680       attribute is applied by a CHECK block.
681
682       This can be problematic if you want to dynamically load Test::Class
683       modules. Basically while:
684
685         require $some_test_class;
686
687       will break, doing:
688
689         BEGIN { require $some_test_class }
690
691       will work just fine. For more information on CHECK blocks see "BEGIN,
692       CHECK, INIT and END" in perlmod.
693
694       If you still can't arrange for your classes to be loaded at runtime,
695       you could use an alternative mechanism for adding your tests:
696
697         # sub test_something : Test(3) {...}
698         # becomes
699         sub test_something {...}
700         __PACKAGE__->add_testinfo('test_something', test => 3);
701
702       See the add_testinfo method for more details.
703
704       Additionally, if you've forgotten to enable warnings and have two test
705       subs called the same thing, you will get the same error.
706

GENERAL FILTERING OF TESTS

708       The use of $ENV{TEST_METHOD} to run just a subset of tests is useful,
709       but sometimes it doesn't give the level of granularity that you desire.
710       Another feature of this class is the ability to do filtering on other
711       static criteria.  In order to permit this, a generic filtering method
712       is supported.  This can be used by specifying coderefs to the
713       'add_filter' method of this class.
714
715       In determining which tests should be run, all filters that have
716       previously been specified via the add_filter method will be run in-turn
717       for each normal test method.  If any of these filters return a false
718       value, the method will not be executed, or included in the number of
719       tests.  Note that filters will only be run for normal test methods,
720       they are ignored for startup, shutdown, setup, and teardown test
721       methods.
722
723       Note that test filters are global, and will affect all tests in all
724       classes, not just the one that they were defined in.
725
726       An example of this mechanism that mostly simulates the use of
727       TEST_METHOD above is:
728
729        package MyTests;
730
731        use Test::More;
732
733        use base qw( Test::Class );
734
735        my $MYTEST_METHOD = qr/^t_not_filtered$/;
736
737        my $filter = sub {
738           my ( $test_class, $test_method ) = @_;
739
740           return $test_method =~ $MYTEST_METHOD;
741        }
742        Test::Class->add_filter( $filter );
743
744        sub t_filtered : Test( 1 ) {
745           fail( "filtered test run" );
746        }
747
748        sub t_not_filtered : Test( 1 ) {
749           pass( "unfiltered test run" );
750        }
751

METHODS

753   Creating and running tests
754       Test
755             # test methods
756             sub method_name : Test { ... }
757             sub method_name : Test(N) { ... }
758
759             # setup methods
760             sub method_name : Test(setup) { ... }
761             sub method_name : Test(setup => N) { ... }
762
763             # teardown methods
764             sub method_name : Test(teardown) { ... }
765             sub method_name : Test(teardown => N) { ... }
766
767             # startup methods
768             sub method_name : Test(startup) { ... }
769             sub method_name : Test(startup => N) { ... }
770
771             # shutdown methods
772             sub method_name : Test(shutdown) { ... }
773             sub method_name : Test(shutdown => N) { ... }
774
775           Marks a startup, setup, test, teardown or shutdown method. See
776           runtests() for information on how to run methods declared with the
777           "Test" attribute.
778
779           N specifies the number of tests the method runs.
780
781           ·   If N is an integer then the method should run exactly N tests.
782
783           ·   If N is an integer with a "+" prefix then the method is
784               expected to call its "SUPER::" method and extend it by running
785               N additional tests.
786
787           ·   If N is the string "no_plan" then the method can run an
788               arbitrary number of tests.
789
790           If N is not specified it defaults to 1 for test methods, and 0 for
791           startup, setup, teardown and shutdown methods.
792
793           You can change the number of tests that a method runs using
794           num_method_tests() or num_tests().
795
796       Tests
797             sub method_name : Tests { ... }
798             sub method_name : Tests(N) { ... }
799
800           Acts just like the ":Test" attribute, except that if the number of
801           tests is not specified it defaults to "no_plan". So the following
802           are equivalent:
803
804             sub silly1 :Test( no_plan ) { ok(1) foreach (1 .. rand 5) }
805             sub silly2 :Tests           { ok(1) foreach (1 .. rand 5) }
806
807       new
808             $Tests = CLASS->new(KEY => VAL ...)
809             $Tests2 = $Tests->new(KEY => VAL ...)
810
811           Creates a new test object (blessed hashref) containing the
812           specified key/value pairs.
813
814           If called as an object method the existing object's key/value pairs
815           are copied into the new object. Any key/value pairs passed to "new"
816           override those in the original object if duplicates occur.
817
818           Since the test object is passed to every test method as it runs, it
819           is a convenient place to store test fixtures. For example:
820
821             sub make_fixture : Test(setup) {
822                 my $self = shift;
823                 $self->{object} = Object->new();
824                 $self->{dbh} = Mock::DBI->new(-type => normal);
825             }
826
827             sub test_open : Test {
828                 my $self = shift;
829                 my ($o, $dbh) = ($self->{object}, $self->{dbh});
830                 ok($o->open($dbh), "opened ok");
831             }
832
833           See num_method_tests() for an example of overriding "new".
834
835       expected_tests
836             $n = $Tests->expected_tests
837             $n = CLASS->expected_tests
838             $n = $Tests->expected_tests(TEST, ...)
839             $n = CLASS->expected_tests(TEST, ...)
840
841           Returns the total number of tests that runtests() will run on the
842           specified class/object. This includes tests run by any setup and
843           teardown methods.
844
845           Will return "no_plan" if the exact number of tests is undetermined
846           (i.e. if any setup, test or teardown method has an undetermined
847           number of tests).
848
849           The "expected_tests" of an object after runtests() has been
850           executed will include any run time changes to the expected number
851           of tests made by num_tests() or num_method_tests().
852
853           "expected_tests" can also take an optional list of test objects,
854           test classes and integers. In this case the result is the total
855           number of expected tests for all the test/object classes (including
856           the one the method was applied to) plus any integer values.
857
858           "expected_tests" is useful when you're integrating one or more test
859           classes into a more traditional test script, for example:
860
861             use Test::More;
862             use My::Test::Class;
863
864             plan tests => My::Test::Class->expected_tests(+2);
865
866             ok(whatever, 'a test');
867             ok(whatever, 'another test');
868             My::Test::Class->runtests;
869
870       runtests
871             $allok = $Tests->runtests
872             $allok = CLASS->runtests
873             $allok = $Tests->runtests(TEST, ...)
874             $allok = CLASS->runtests(TEST, ...)
875
876           "runtests" is used to run test classes. At its most basic doing:
877
878             $test->runtests
879
880           will run the test methods of the test object $test, unless
881           "$test->SKIP_CLASS" returns a true value.
882
883           Unless you have already specified a test plan using Test::Builder
884           (or Test::More, et al) "runtests" will set the test plan just
885           before the first method that runs a test is executed.
886
887           If the environment variable "TEST_VERBOSE" is set "runtests" will
888           display the name of each test method before it runs like this:
889
890             # My::Test::Class->my_test
891             ok 1 - fribble
892             # My::Test::Class->another_test
893             ok 2 - bar
894
895           Just like expected_tests(), "runtests" can take an optional list of
896           test object/classes and integers. All of the test object/classes
897           are run. Any integers are added to the total number of tests shown
898           in the test header output by "runtests".
899
900           For example, you can run all the tests in test classes A, B and C,
901           plus one additional normal test by doing:
902
903               Test::Class->runtests(qw(A B C), +1);
904               ok(1==1, 'non class test');
905
906           Finally, if you call "runtests" on a test class without any
907           arguments it will run all of the test methods of that class, and
908           all subclasses of that class. For example:
909
910             #! /usr/bin/perl
911             # Test all the Foo stuff
912
913             use Foo::Test;
914             use Foo::Bar::Test;
915             use Foo::Ni::Test;
916
917             # run all the Foo*Test modules we just loaded
918             Test::Class->runtests;
919
920       SKIP_CLASS
921             $reason = CLASS->SKIP_CLASS;
922             CLASS->SKIP_CLASS( $reason );
923
924           Determines whether the test class CLASS should run it's tests. If
925           SKIP_CLASS returns a true value then  runtests() will not run any
926           of the test methods in CLASS.
927
928           You can override the default on a class-by-class basis by supplying
929           a new value to SKIP_CLASS. For example if you have an abstract base
930           class that should not run just add the following to your module:
931
932             My::Abstract::Test->SKIP_CLASS( 1 );
933
934           This will not affect any sub-classes of "My::Abstract::Test" which
935           will run as normal.
936
937           If the true value returned by SKIP_CLASS is anything other than "1"
938           then a skip test is output using this value as the skip message.
939           For example:
940
941             My::Postgres::Test->SKIP_CLASS(
942                 $ENV{POSTGRES_HOME} ? 0 : '$POSTGRES_HOME needs to be set'
943             );
944
945           will output something like this if "POSTGRES_HOME" is not set
946
947               ... other tests ...
948               ok 123 # skip My::Postgres::Test  - $POSTGRES_HOME needs to be set
949               ... more tests ...
950
951           You can also override SKIP_CLASS for a class hierarchy. For
952           example, to prevent any subclasses of My::Postgres::Test running we
953           could override SKIP_CLASS like this:
954
955             sub My::Postgres::Test::SKIP_CLASS {
956                 $ENV{POSTGRES_HOME} ? 0 : '$POSTGRES_HOME needs to be set'
957             }
958
959   Fetching and setting a method's test number
960       num_method_tests
961             $n = $Tests->num_method_tests($method_name)
962             $Tests->num_method_tests($method_name, $n)
963             $n = CLASS->num_method_tests($method_name)
964             CLASS->num_method_tests($method_name, $n)
965
966           Fetch or set the number of tests that the named method is expected
967           to run.
968
969           If the method has an undetermined number of tests then $n should be
970           the string "no_plan".
971
972           If the method is extending the number of tests run by the method in
973           a superclass then $n should have a "+" prefix.
974
975           When called as a class method any change to the expected number of
976           tests applies to all future test objects. Existing test objects are
977           unaffected.
978
979           When called as an object method any change to the expected number
980           of tests applies to that object alone.
981
982           "num_method_tests" is useful when you need to set the expected
983           number of tests at object creation time, rather than at compile
984           time.
985
986           For example, the following test class will run a different number
987           of tests depending on the number of objects supplied.
988
989             package Object::Test;
990             use base qw(Test::Class);
991             use Test::More;
992
993             sub new {
994                 my $class = shift;
995                 my $self = $class->SUPER::new(@_);
996                 my $num_objects = @{$self->{objects}};
997                 $self->num_method_tests('test_objects', $num_objects);
998                 return($self);
999             }
1000
1001             sub test_objects : Tests {
1002               my $self = shift;
1003               ok($_->open, "opened $_") foreach @{$self->{objects}};
1004             }
1005             ...
1006             # This runs two tests
1007             Object::Test->new(objects => [$o1, $o2]);
1008
1009           The advantage of setting the number of tests at object creation
1010           time, rather than using a test method without a plan, is that the
1011           number of expected tests can be determined before testing begins.
1012           This allows better diagnostics from runtests(), Test::Builder and
1013           Test::Harness.
1014
1015           "num_method_tests" is a protected method and can only be called by
1016           subclasses of Test::Class. It fetches or sets the expected number
1017           of tests for the methods of the class it was called in, not the
1018           methods of the object/class it was applied to. This allows test
1019           classes that use "num_method_tests" to be subclassed easily.
1020
1021           For example, consider the creation of a subclass of Object::Test
1022           that ensures that all the opened objects are read-only:
1023
1024             package Special::Object::Test;
1025             use base qw(Object::Test);
1026             use Test::More;
1027
1028             sub test_objects : Test(+1) {
1029                 my $self = shift;
1030                 $self->SUPER::test_objects;
1031                 my @bad_objects = grep {! $_->read_only} (@{$self->{objects}});
1032                 ok(@bad_objects == 0, "all objects read only");
1033             }
1034             ...
1035             # This runs three tests
1036             Special::Object::Test->new(objects => [$o1, $o2]);
1037
1038           Since the call to "num_method_tests" in Object::Test only affects
1039           the "test_objects" of Object::Test, the above works as you would
1040           expect.
1041
1042       num_tests
1043             $n = $Tests->num_tests
1044             $Tests->num_tests($n)
1045             $n = CLASS->num_tests
1046             CLASS->num_tests($n)
1047
1048           Set or return the number of expected tests associated with the
1049           currently running test method. This is the same as calling
1050           num_method_tests() with a method name of current_method().
1051
1052           For example:
1053
1054             sub txt_files_readable : Tests {
1055                 my $self = shift;
1056                 my @files = <*.txt>;
1057                 $self->num_tests(scalar(@files));
1058                 ok(-r $_, "$_ readable") foreach (@files);
1059             }
1060
1061           Setting the number of expected tests at run time, rather than just
1062           having a "no_plan" test method, allows runtests() to display
1063           appropriate diagnostic messages if the method runs a different
1064           number of tests.
1065
1066   Support methods
1067       builder
1068             $Tests->builder
1069
1070           Returns the underlying Test::Builder object that Test::Class uses.
1071           For example:
1072
1073             sub test_close : Test {
1074                 my $self = shift;
1075                 my ($o, $dbh) = ($self->{object}, $self->{dbh});
1076                 $self->builder->ok($o->close($dbh), "closed ok");
1077             }
1078
1079       current_method
1080             $method_name = $Tests->current_method
1081             $method_name = CLASS->current_method
1082
1083           Returns the name of the test method currently being executed by
1084           runtests(), or "undef" if runtests() has not been called.
1085
1086           The method name is also available in the setup and teardown methods
1087           that run before and after the test method. This can be useful in
1088           producing diagnostic messages, for example:
1089
1090             sub test_invarient : Test(teardown => 1) {
1091                 my $self = shift;
1092                 my $m = $self->current_method;
1093                 ok($self->invarient_ok, "class okay after $m");
1094             }
1095
1096       BAILOUT
1097             $Tests->BAILOUT($reason)
1098             CLASS->BAILOUT($reason)
1099
1100           Things are going so badly all testing should terminate, including
1101           running any additional test scripts invoked by Test::Harness. This
1102           is exactly the same as doing:
1103
1104             $self->builder->BAILOUT
1105
1106           See "BAILOUT" in Test::Builder for details. Any teardown and
1107           shutdown methods are not run.
1108
1109       FAIL_ALL
1110             $Tests->FAIL_ALL($reason)
1111             CLASS->FAIL_ALL($reason)
1112
1113           Things are going so badly all the remaining tests in the current
1114           script should fail. Exits immediately with the number of tests
1115           failed, or 254 if more than 254 tests were run. Any teardown
1116           methods are not run.
1117
1118           This does not affect the running of any other test scripts invoked
1119           by Test::Harness.
1120
1121           For example, if all your tests rely on the ability to create
1122           objects then you might want something like this as an early test:
1123
1124             sub _test_new : Test(3) {
1125                 my $self = shift;
1126                 isa_ok(Object->new, "Object")
1127                     || $self->FAIL_ALL('cannot create Objects');
1128                 ...
1129             }
1130
1131       SKIP_ALL
1132             $Tests->SKIP_ALL($reason)
1133             CLASS->SKIP_ALL($reason)
1134
1135           Things are going so badly all the remaining tests in the current
1136           script should be skipped. Exits immediately with 0 - teardown
1137           methods are not run.
1138
1139           This does not affect the running of any other test scripts invoked
1140           by Test::Harness.
1141
1142           For example, if you had a test script that only applied to the
1143           darwin OS you could write:
1144
1145             sub _darwin_only : Test(setup) {
1146                 my $self = shift;
1147                 $self->SKIP_ALL("darwin only") unless $^O eq "darwin";
1148             }
1149
1150       add_testinfo
1151             CLASS->add_testinfo($name, $type, $num_tests)
1152
1153           Chiefly for use by libraries like Test::Class::Sugar, which can't
1154           use the ":Test(...)" interfaces make test methods. "add_testinfo"
1155           informs the class about a test method that has been defined without
1156           a "Test", "Tests" or other attribute.
1157
1158           $name is the name of the method, $type must be one of "startup",
1159           "setup", "test", "teardown" or "shutdown", and $num_tests has the
1160           same meaning as "N" in the description of the Test attribute.
1161
1162       add_filter
1163               CLASS->add_filter($filter_coderef);
1164
1165           Adds a filtering coderef. Each filter is passed a test class and
1166           method name and returns a boolean. All filters are applied globally
1167           in the order they were added. If any filter returns false the test
1168           method is not run or included in the number of tests.
1169
1170           Note that filters will only be run for normal test methods, they
1171           are ignored for startup, shutdown, setup, and teardown test
1172           methods.
1173
1174           See the section on the "GENERAL FILTERING OF TESTS" for more
1175           information.
1176
1177       fail_if_returned_early
1178           Controls what happens if a method returns before it has run all of
1179           its tests.  It is called with no arguments in boolean context; if
1180           it returns true, then the missing tests fail, otherwise, they skip.
1181           See "Returning Early" and "Skipped Tests".
1182

HELP FOR CONFUSED JUNIT USERS

1184       This section is for people who have used JUnit (or similar) and are
1185       confused because they don't see the TestCase/Suite/Runner class
1186       framework they were expecting. Here we take each of the major classes
1187       in JUnit and compare them with their equivalent Perl testing modules.
1188
1189       Class Assert
1190           The test assertions provided by Assert correspond to the test
1191           functions provided by the Test::Builder based modules (Test::More,
1192           Test::Exception, Test::Differences, etc.)
1193
1194           Unlike JUnit the test functions supplied by Test::More et al do not
1195           throw exceptions on failure. They just report the failure to STDOUT
1196           where it is collected by Test::Harness. This means that where you
1197           have
1198
1199             sub foo : Test(2) {
1200                 ok($foo->method1);
1201                 ok($foo->method2);
1202             }
1203
1204           The second test will run if the first one fails. You can emulate
1205           the JUnit way of doing it by throwing an explicit exception on test
1206           failure:
1207
1208             sub foo : Test(2) {
1209                 ok($foo->method1) or die "method1 failed";
1210                 ok($foo->method2);
1211             }
1212
1213           The exception will be caught by Test::Class and the other test
1214           automatically failed.
1215
1216       Class TestCase
1217           Test::Class corresponds to TestCase in JUnit.
1218
1219           In Test::Class setup, test and teardown methods are marked
1220           explicitly using the Test attribute. Since we need to know the
1221           total number of tests to provide a test plan for Test::Harness, we
1222           also state how many tests each method runs.
1223
1224           Unlike JUnit you can have multiple setup/teardown methods in a
1225           class.
1226
1227       Class TestSuite
1228           Test::Class also does the work that would be done by TestSuite in
1229           JUnit.
1230
1231           Since the methods are marked with attributes, Test::Class knows
1232           what is and isn't a test method. This allows it to run all the test
1233           methods without having the developer create a suite manually, or
1234           use reflection to dynamically determine the test methods by name.
1235           See the runtests() method for more details.
1236
1237           The running order of the test methods is fixed in Test::Class.
1238           Methods are executed in alphabetical order.
1239
1240           To run individual test methods, see "RUNNING INDIVIDUAL TESTS".
1241
1242       Class TestRunner
1243           Test::Harness does the work of the TestRunner in JUnit. It collects
1244           the test results (sent to STDOUT) and collates the results.
1245
1246           Unlike JUnit there is no distinction made by Test::Harness between
1247           errors and failures. However, it does support skipped and todo test
1248           - which JUnit does not.
1249
1250           If you want to write your own test runners you should look at
1251           Test::Harness::Straps.
1252

OTHER MODULES FOR XUNIT TESTING IN PERL

1254       In addition to Test::Class there are two other distributions for xUnit
1255       testing in perl. Both have a longer history than Test::Class and might
1256       be more suitable for your needs.
1257
1258       I am biased since I wrote Test::Class - so please read the following
1259       with appropriate levels of scepticism. If you think I have
1260       misrepresented the modules please let me know.
1261
1262       Test::SimpleUnit
1263           A very simple unit testing framework. If you are looking for a
1264           lightweight single module solution this might be for you.
1265
1266           The advantage of Test::SimpleUnit is that it is simple! Just one
1267           module with a smallish API to learn.
1268
1269           Of course this is also the disadvantage.
1270
1271           It's not class based so you cannot create testing classes to reuse
1272           and extend.
1273
1274           It doesn't use Test::Builder so it's difficult to extend or
1275           integrate with other testing modules. If you are already familiar
1276           with Test::Builder, Test::More and friends you will have to learn a
1277           new test assertion API. It does not support todo tests.
1278
1279       Test::Unit
1280           Test::Unit is a port of JUnit <http://www.junit.org/> into perl. If
1281           you have used JUnit then the Test::Unit framework should be very
1282           familiar.
1283
1284           It is class based so you can easily reuse your test classes and
1285           extend by subclassing. You get a nice flexible framework you can
1286           tweak to your heart's content. If you can run Tk you also get a
1287           graphical test runner.
1288
1289           However, Test::Unit is not based on Test::Builder. You cannot
1290           easily move Test::Builder based test functions into Test::Unit
1291           based classes. You have to learn another test assertion API.
1292
1293           Test::Unit implements it's own testing framework separate from
1294           Test::Harness. You can retrofit *.t scripts as unit tests, and
1295           output test results in the format that Test::Harness expects, but
1296           things like todo tests and skipping tests are not supported.
1297

BUGS

1299       None known at the time of writing.
1300
1301       If you find any bugs please let me know by e-mail at
1302       <adrianh@quietstars.com>, or report the problem with
1303       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Class>.
1304

COMMUNITY

1306   perl-qa
1307       If you are interested in testing using Perl I recommend you visit
1308       <http://qa.perl.org/> and join the excellent perl-qa mailing list. See
1309       <http://lists.perl.org/showlist.cgi?name=perl-qa> for details on how to
1310       subscribe.
1311
1312   perlmonks
1313       You can find users of Test::Class, including the module author, on
1314       <http://www.perlmonks.org/>. Feel free to ask questions on Test::Class
1315       there.
1316
1317   CPAN::Forum
1318       The CPAN Forum is a web forum for discussing Perl's CPAN modules.   The
1319       Test::Class forum can be found at
1320       <http://www.cpanforum.com/dist/Test-Class>.
1321

TO DO

1323       If you think this module should do something that it doesn't (or does
1324       something that it shouldn't) please let me know.
1325
1326       You can see my current to do list at
1327       <http://adrianh.tadalist.com/lists/public/4798>, with an RSS feed of
1328       changes at <http://adrianh.tadalist.com/lists/feed_public/4798>.
1329

ACKNOWLEDGMENTS

1331       This is yet another implementation of the ideas from Kent Beck's
1332       Testing Framework paper <http://www.xprogramming.com/testfram.htm>.
1333
1334       Thanks to Adam Kennedy, agianni, Alexander D'Archangel, Andrew
1335       Grangaard, Apocalypse, Ask Bjorn Hansen, Chris Dolan, Chris Williams,
1336       Corion, Cosimo Streppone, Daniel Berger, Dave Evans, Dave O'Neill,
1337       David Cantrell, David Wheeler, Diab Jerius, Emil Jansson, Gunnar Wolf,
1338       Hai Pham, Hynek, imacat, Jeff Deifik, Jim Brandt, Jochen Stenzel, Johan
1339       Lindstrom, John West, Jonathan R. Warden, Joshua ben Jore, Jost
1340       Krieger, Ken Fox, Kenichi Ishigaki Lee Goddard, Mark Morgan, Mark
1341       Reynolds, Mark Stosberg, Martin Ferrari, Mathieu Sauve-Frankel, Matt
1342       Trout, Matt Williamson, Michael G Schwern, Murat Uenalan, Naveed
1343       Massjouni, Nicholas Clark, Ovid, Piers Cawley, Rob Kinyon, Sam Raymer,
1344       Scott Lanning, Sebastien Aperghis-Tramoni, Steve Kirkup, Stray Toaster,
1345       Ted Carnahan, Terrence Brannon, Todd W, Tom Metro, Tony Bowden, Tony
1346       Edwardson, William McKee, various anonymous folk and all the fine
1347       people on perl-qa for their feedback, patches, suggestions and nagging.
1348
1349       This module wouldn't be possible without the excellent Test::Builder.
1350       Thanks to chromatic and Michael G Schwern for creating such a useful
1351       module.
1352

AUTHORS

1354       Adrian Howard <adrianh@quietstars.com>, Curtis "Ovid" Poe, <ovid at
1355       cpan.org>, Mark Morgan <makk384@gmail.com>.
1356
1357       If you use this module, and can spare the time please let us know or
1358       rate it at <http://cpanratings.perl.org/rate/?distribution=Test-Class>.
1359

SEE ALSO

1361       Test::Class::Load
1362           Simple way to load "Test::Class" classes automatically.
1363
1364       Test::Class::Most
1365           Test::Class with additional conveniences to reduce need for some
1366           boilerplate code. Also makes Test::Most testing functions
1367           available.
1368
1369       Test::Class::Moose
1370           Testing framework allows you to write your tests in Moose and test
1371           Moose and non-Moose code.  It offers reporting, extensibility, test
1372           inheritance, parallel testing and more.
1373
1374       <http://del.icio.us/tag/Test::Class>
1375           Delicious links on Test::Class.
1376
1377       Perl Testing: A Developer's Notebook by Ian Langworth and chromatic
1378           Chapter 8 covers using Test::Class.
1379
1380       Advanced Perl Programming, second edition by Simon Cozens
1381           Chapter 8 has a few pages on using Test::Class.
1382
1383       The Perl Journal, April 2003
1384           Includes the article "Test-Driven Development in Perl" by Piers
1385           Cawley that uses Test::Class.
1386
1387       Test::Class Tutorial series written by Curtis "Ovid" Poe
1388           ·   <http://www.modernperlbooks.com/mt/2009/03/organizing-test-suites-with-testclass.html>
1389
1390           ·   <http://www.modernperlbooks.com/mt/2009/03/reusing-test-code-with-testclass.html>
1391
1392           ·   <http://www.modernperlbooks.com/mt/2009/03/making-your-testing-life-easier.html>
1393
1394           ·   <http://www.modernperlbooks.com/mt/2009/03/using-test-control-methods-with-testclass.html>
1395
1396           ·   <http://www.modernperlbooks.com/mt/2009/03/working-with-testclass-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       <http://qa.perl.org/test-modules.html>
1405           Overview of some of the many testing modules available on CPAN.
1406
1407       <http://del.icio.us/tag/perl+testing>
1408           Delicious links on perl testing.
1409
1410       Test::Object
1411           Another approach to object oriented testing.
1412
1413       Test::Group and Test::Block
1414           Alternatives to grouping sets of tests together.
1415
1416       The following modules use Test::Class as part of their test suite. You
1417       might want to look at them for usage examples:
1418
1419           App-GitGot, Aspect, Bricolage (<http://www.bricolage.cc/>), CHI,
1420           Cinnamon, Class::StorageFactory, CGI::Application::Search,
1421           DBIx::Romani, Xmldoom, Object::Relational, File::Random,
1422           Geography::JapanesePrefectures, Google::Adwords, Merge::HashRef,
1423           PerlBuildSystem, Ubic, Pixie, Yahoo::Marketing, and XUL-Node
1424
1425       The following modules are not based on Test::Builder, but may be of
1426       interest as alternatives to Test::Class.
1427
1428       Test::Unit
1429           Perl unit testing framework closely modeled on JUnit.
1430
1431       Test::SimpleUnit
1432           A very simple unit testing framework.
1433

LICENCE

1435       Copyright 2002-2010 Adrian Howard, All Rights Reserved.
1436
1437       This program is free software; you can redistribute it and/or modify it
1438       under the same terms as Perl itself.
1439
1440
1441
1442perl v5.32.0                      2020-07-28                    Test::Class(3)
Impressum