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.51
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

RETURNING LATE

489       If a test method runs too many tests, by default the test plan
490       succeeds.
491
492       However, if the class's "fail_if_returned_late" method returns true,
493       then the extra tests will trigger a failure.  For example,
494
495         package MyClass;
496         use base 'Test::Class';
497         sub fail_if_returned_late { 1 }
498
499         sub oops : Tests(1) {
500           ok 1, "just a simple test";
501           ok 1, "just a simple test"; #oops I copied and pasted too many tests
502         }
503

SKIPPED TESTS

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

TO DO TESTS

556       You can create todo tests just as you do in Test::More and
557       Test::Builder using the $TODO variable. For example:
558
559         sub live_test : Test  {
560             local $TODO = "live currently unimplemented";
561             ok(Object->live, "object live");
562         }
563
564       See "Todo tests" in Test::Harness for more information.
565

EXTENDING TEST CLASSES BY INHERITANCE

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

RUNNING INDIVIDUAL TESTS

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

ORGANISING YOUR TEST CLASSES

682       You can, of course, organise your test modules as you wish. My personal
683       preferences is:
684
685       •   Name test classes with a suffix of "::Test" so the test class for
686           the "Foo::Bar" module would be "Foo::Bar::Test".
687
688       •   Place all test classes in t/lib.
689
690       The Test::Class::Load provides a simple mechanism for easily loading
691       all of the test classes in a given set of directories.
692

A NOTE ON LOADING TEST CLASSES

694       Due to its use of subroutine attributes Test::Class based modules must
695       be loaded at compile rather than run time. This is because the :Test
696       attribute is applied by a CHECK block.
697
698       This can be problematic if you want to dynamically load Test::Class
699       modules. Basically while:
700
701         require $some_test_class;
702
703       will break, doing:
704
705         BEGIN { require $some_test_class }
706
707       will work just fine. For more information on CHECK blocks see "BEGIN,
708       CHECK, INIT and END" in perlmod.
709
710       If you still can't arrange for your classes to be loaded at runtime,
711       you could use an alternative mechanism for adding your tests:
712
713         # sub test_something : Test(3) {...}
714         # becomes
715         sub test_something {...}
716         __PACKAGE__->add_testinfo('test_something', test => 3);
717
718       See the add_testinfo method for more details.
719
720       Additionally, if you've forgotten to enable warnings and have two test
721       subs called the same thing, you will get the same error.
722

GENERAL FILTERING OF TESTS

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

METHODS

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

HELP FOR CONFUSED JUNIT USERS

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

OTHER MODULES FOR XUNIT TESTING IN PERL

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

SUPPORT

1321       Bugs may be submitted through GitHub issues
1322       <https://github.com/szabgab/test-class/issues>
1323
1324       There is also an irc channel available for users of this distribution,
1325       at "#perl-qa" on "irc.perl.org" <irc://irc.perl.org/#perl-qa>.
1326

TO DO

1328       If you think this module should do something that it doesn't (or does
1329       something that it shouldn't) please let me know.
1330
1331       You can see an old to do list at
1332       <http://adrianh.tadalist.com/lists/public/4798>, with an RSS feed of
1333       changes at <http://adrianh.tadalist.com/lists/feed_public/4798>.
1334

ACKNOWLEDGMENTS

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

AUTHORS

1359       Adrian Howard <adrianh@quietstars.com>, Curtis "Ovid" Poe, <ovid at
1360       cpan.org>, Mark Morgan <makk384@gmail.com>.
1361

SEE ALSO

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

LICENCE

1441       Copyright 2002-2010 Adrian Howard, All Rights Reserved.
1442
1443       This program is free software; you can redistribute it and/or modify it
1444       under the same terms as Perl itself.
1445
1446
1447
1448perl v5.32.1                      2021-02-17                    Test::Class(3)
Impressum