1Test::Class(3) User Contributed Perl Documentation Test::Class(3)
2
6 Test::Class - Easily create test classes in an xUnit/JUnit style
7
9 version 0.51
10
12 package Example::Test;
13 use base qw(Test::Class);
14 use Test::More;
15 # 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 # 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 # 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 # 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 later in a nearby .t file
45 #! /usr/bin/perl
47 use Example::Test;
48 # run all the test methods in Example::Test
50 Test::Class->runtests;
51 Outputs:
53 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
64 Test::Class provides a simple way of creating classes and objects to
65 test your code in an xUnit style.
66 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 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
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 Later Kent Beck and Erich Gamma created JUnit for testing Java
83 <http://www.junit.org/>. It was popular too.
84 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 While xUnit frameworks are traditionally associated with unit testing
89 they are also useful in the creation of functional/acceptance tests.
90 Test::Class is (yet another) implementation of xUnit style testing in
92 Perl.
93 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 • 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 • 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 • 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 • Skipping tests and todo tests are supported.
111 • 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 • 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 • 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 • 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 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 • 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 • 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
146 A test class is just a class that inherits from Test::Class. Defining a
147 test class is as simple as doing:
148 package Example::Test;
150 use base qw(Test::Class);
151 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 use Test::More;
157 to import the test functions into your test class.
159
161 There are three different types of method you can define using
162 Test::Class.
163 1) Test methods
165 You define test methods using the Test attribute. For example:
166 package Example::Test;
168 use base qw(Test::Class);
169 use Test::More;
170 sub subtraction : Test {
172 is( 2-1, 1, 'subtraction works' );
173 }
174 This declares the "subtraction" method as a test method that runs one
176 test.
177 If your test method runs more than one test, you should put the number
179 of tests in brackets like this:
180 sub addition : Test(2) {
182 is(10 + 20, 30, 'addition works');
183 is(20 + 10, 30, ' both ways');
184 }
185 If you don't know the number of tests at compile time you can use
187 "no_plan" like this.
188 sub check_class : Test(no_plan) {
190 my $objects = shift->{objects};
191 isa_ok($_, "Object") foreach @$objects;
192 }
193 or use the :Tests attribute, which acts just like ":Test" but defaults
195 to "no_plan" if no number is given:
196 sub check_class : Tests {
198 my $objects = shift->{objects};
199 isa_ok($_, "Object") foreach @$objects;
200 }
201 2) Setup and teardown methods
203 Setup and teardown methods are run before and after every test. For
204 example:
205 sub before : Test(setup) { diag("running before test") }
207 sub after : Test(teardown) { diag("running after test") }
208 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 sub pig : Test(setup) {
214 my $self = shift;
215 $self->{test_pig} = Pig->new;
216 }
217 sub born_hungry : Test {
219 my $pig = shift->{test_pig};
220 is($pig->hungry, 'pigs are born hungry');
221 }
222 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 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 sub pig_alive : Test(teardown => 1) {
235 my $pig = shift->{test_pig};
236 ok($pig->alive, 'pig survived tests' );
237 }
238 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 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 sub db_connect : Test(startup) {
250 shift->{dbi} = DBI->connect;
251 }
252 sub db_disconnect : Test(shutdown) {
254 shift->{dbi}->disconnect;
255 }
256 Just like setup and teardown methods you can pass an optional number of
258 tests to startup and shutdown methods. For example:
259 sub example : Test(startup => 1) {
261 ok(1, 'a startup method with one test');
262 }
263 If you want to run an unknown number of tests within your startup
265 method, you need to say e.g.
266 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 as the : Tests attribute behaves exactly like : Test in this context.
273 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
278 You run test methods with runtests(). Doing:
279 Test::Class->runtests
281 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 #! /usr/bin/perl
287 # 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 # and run them all
295 Test::Class->runtests;
296 You can use Test::Class::Load to automatically load all the test
298 classes in a given set of directories.
299 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 Example::Test->new->runtests
305 You can also pass runtests() a list of test objects to run. For
307 example:
308 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 Since, by definition, the base Test::Class has no tests, you could also
315 have written:
316 my $o1 = Example::Test->new;
318 my $o2 = Another::Test->new;
319 Test::Class->runtests($o1, $o2);
320 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 Test::Class->runtests(qw( Example::Test Another::Test ))
325 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 What happens if you run test classes and normal tests in the same
331 script? For example:
332 Test::Class->runtests;
334 ok(Example->new->foo, 'a test not in the test class');
335 ok(Example->new->bar, 'ditto');
336 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 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 Test::Class->runtests(+2);
346 ok(Example->new->foo, 'a test not in the test class');
347 ok(Example->new->bar, 'ditto');
348 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 Since runtests() will not output a test plan if one has already been
354 set, the previous example can be written as:
355 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 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 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
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 is $something, $something_else, 'a description of my test';
377 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 sub one_plus_one_is_two : Test {
384 is 1+1, 2;
385 }
386 will result in:
388 ok 1 - one plus one is two
390
392 Methods of each type are run in the following order:
393 1. All of the startup methods in alphabetical order
395 2. For each test method, in alphabetical order:
397 • All of the setup methods in alphabetical order
399 • The test method.
401 • All of the teardown methods in alphabetical order
403 3. All of the shutdown methods in alphabetical order.
405 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 sub _check_new {
411 my $self = shift;
412 isa_ok(Object->new, "Object") or $self->BAILOUT('new fails!');
413 }
414 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
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 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 will produce the following if the first test failed:
430 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 This can considerably simplify testing code that throws exceptions.
442 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 use Test::Exception;
449 my $file;
451 lives_ok { $file = read_file('test.txt') } 'file read';
452 is($file, "content", 'test file read');
453 with:
455 sub read_file : Test {
457 is(read_file('test.txt'), "content", 'test file read');
458 }
459 If more than one test remains after an exception then the first one is
461 failed, and the remaining ones are skipped.
462 If the setup method of a test method dies, then all of the remaining
464 setup and shutdown methods are also skipped.
465 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
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 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 package MyClass;
479 use base 'Test::Class';
480 sub fail_if_returned_early { 1 }
481 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
489 If a test method runs too many tests, by default the test plan
490 succeeds.
491 However, if the class's "fail_if_returned_late" method returns true,
493 then the extra tests will trigger a failure. For example,
494 package MyClass;
496 use base 'Test::Class';
497 sub fail_if_returned_late { 1 }
498 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
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 This makes managing tests that can be skipped for multiple reasons very
511 simple. For example:
512 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 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 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 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 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 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 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 You can make a test class skip all of its tests by setting SKIP_CLASS()
553 before runtests() is called.
554
556 You can create todo tests just as you do in Test::More and
557 Test::Builder using the $TODO variable. For example:
558 sub live_test : Test {
560 local $TODO = "live currently unimplemented";
561 ok(Object->live, "object live");
562 }
563 See "Todo tests" in Test::Harness for more information.
565
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 package Pig::Test;
571 use base qw(Test::Class);
572 use Test::More;
573 sub testing_class { "Pig" }
575 sub new_args { (-age => 3) }
576 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 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 sub check_fields : Test {
591 my $pig = shift->{pig}
592 is($pig->age, 3, "age accessed");
593 }
594 Next consider "NamedPig" a subclass of "Pig" where you can give your
596 pig a name.
597 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 package NamedPig::Test;
603 use base qw(Pig::Test);
604 use Test::More;
605 sub testing_class { "NamedPig" }
607 sub new_args { (shift->SUPER::new_args, -name => 'Porky') }
608 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 sub check_fields : Test(2) {
614 my $self = shift;
615 $self->SUPER::check_fields;
616 is($self->{pig}->name, 'Porky', 'name accessed');
617 }
618 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 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 sub check_fields : Test(+1) {
629 my $self = shift;
630 $self->SUPER::check_fields;
631 is($self->{pig}->name, 'Porky', 'name accessed');
632 }
633 With the above definition you can add tests to "check_fields" in
635 "Pig::Test" without affecting "NamedPig::Test".
636
638 NOTE: The exact mechanism for running individual tests is likely to
639 change in the future.
640 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 One easy way of doing this is by specifying the environment variable
649 before the "runtests" method is called.
650 Running a test named "customer_profile":
652 #! /usr/bin/perl
654 use Example::Test;
655 $ENV{TEST_METHOD} = 'customer_profile';
657 Test::Class->runtests;
658 Running all tests with "customer" in their name:
660 #! /usr/bin/perl
662 use Example::Test;
663 $ENV{TEST_METHOD} = '.*customer.*';
665 Test::Class->runtests;
666 If you specify an invalid regular expression, your tests will not be
668 run:
669 #! /usr/bin/perl
671 use Example::Test;
672 $ENV{TEST_METHOD} = 'C++';
674 Test::Class->runtests;
675 And when you run it:
677 TEST_METHOD (C++) is not a valid regular expression: Search pattern \
679 not terminated at (eval 17) line 1.
680
682 You can, of course, organise your test modules as you wish. My personal
683 preferences is:
684 • Name test classes with a suffix of "::Test" so the test class for
686 the "Foo::Bar" module would be "Foo::Bar::Test".
687 • Place all test classes in t/lib.
689 The Test::Class::Load provides a simple mechanism for easily loading
691 all of the test classes in a given set of directories.
692
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 This can be problematic if you want to dynamically load Test::Class
699 modules. Basically while:
700 require $some_test_class;
702 will break, doing:
704 BEGIN { require $some_test_class }
706 will work just fine. For more information on CHECK blocks see "BEGIN,
708 CHECK, INIT and END" in perlmod.
709 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 # sub test_something : Test(3) {...}
714 # becomes
715 sub test_something {...}
716 __PACKAGE__->add_testinfo('test_something', test => 3);
717 See the add_testinfo method for more details.
719 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
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 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 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 An example of this mechanism that mostly simulates the use of
743 TEST_METHOD above is:
744 package MyTests;
746 use Test::More;
748 use base qw( Test::Class );
750 my $MYTEST_METHOD = qr/^t_not_filtered$/;
752 my $filter = sub {
754 my ( $test_class, $test_method ) = @_;
755 return $test_method =~ $MYTEST_METHOD;
757 }
758 Test::Class->add_filter( $filter );
759 sub t_filtered : Test( 1 ) {
761 fail( "filtered test run" );
762 }
763 sub t_not_filtered : Test( 1 ) {
765 pass( "unfiltered test run" );
766 }
767
769 Creating and running tests
770 Test
771 # test methods
772 sub method_name : Test { ... }
773 sub method_name : Test(N) { ... }
774 # setup methods
776 sub method_name : Test(setup) { ... }
777 sub method_name : Test(setup => N) { ... }
778 # teardown methods
780 sub method_name : Test(teardown) { ... }
781 sub method_name : Test(teardown => N) { ... }
782 # startup methods
784 sub method_name : Test(startup) { ... }
785 sub method_name : Test(startup => N) { ... }
786 # shutdown methods
788 sub method_name : Test(shutdown) { ... }
789 sub method_name : Test(shutdown => N) { ... }
790 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 N specifies the number of tests the method runs.
796 • If N is an integer then the method should run exactly N tests.
798 • 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 • If N is the string "no_plan" then the method can run an
804 arbitrary number of tests.
805 If N is not specified it defaults to 1 for test methods, and 0 for
807 startup, setup, teardown and shutdown methods.
808 You can change the number of tests that a method runs using
810 num_method_tests() or num_tests().
811 Tests
813 sub method_name : Tests { ... }
814 sub method_name : Tests(N) { ... }
815 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 sub silly1 :Test( no_plan ) { ok(1) foreach (1 .. rand 5) }
821 sub silly2 :Tests { ok(1) foreach (1 .. rand 5) }
822 new
824 $Tests = CLASS->new(KEY => VAL ...)
825 $Tests2 = $Tests->new(KEY => VAL ...)
826 Creates a new test object (blessed hashref) containing the
828 specified key/value pairs.
829 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 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 sub make_fixture : Test(setup) {
838 my $self = shift;
839 $self->{object} = Object->new();
840 $self->{dbh} = Mock::DBI->new(-type => normal);
841 }
842 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 See num_method_tests() for an example of overriding "new".
850 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 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 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 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 "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 "expected_tests" is useful when you're integrating one or more test
875 classes into a more traditional test script, for example:
876 use Test::More;
878 use My::Test::Class;
879 plan tests => My::Test::Class->expected_tests(+2);
881 ok(whatever, 'a test');
883 ok(whatever, 'another test');
884 My::Test::Class->runtests;
885 runtests
887 $allok = $Tests->runtests
888 $allok = CLASS->runtests
889 $allok = $Tests->runtests(TEST, ...)
890 $allok = CLASS->runtests(TEST, ...)
891 "runtests" is used to run test classes. At its most basic doing:
893 $test->runtests
895 will run the test methods of the test object $test, unless
897 "$test->SKIP_CLASS" returns a true value.
898 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 If the environment variable "TEST_VERBOSE" is set "runtests" will
904 display the name of each test method before it runs like this:
905 # My::Test::Class->my_test
907 ok 1 - fribble
908 # My::Test::Class->another_test
909 ok 2 - bar
910 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 For example, you can run all the tests in test classes A, B and C,
917 plus one additional normal test by doing:
918 Test::Class->runtests(qw(A B C), +1);
920 ok(1==1, 'non class test');
921 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 #! /usr/bin/perl
927 # Test all the Foo stuff
928 use Foo::Test;
930 use Foo::Bar::Test;
931 use Foo::Ni::Test;
932 # run all the Foo*Test modules we just loaded
934 Test::Class->runtests;
935 SKIP_CLASS
937 $reason = CLASS->SKIP_CLASS;
938 CLASS->SKIP_CLASS( $reason );
939 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 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 My::Abstract::Test->SKIP_CLASS( 1 );
949 This will not affect any sub-classes of "My::Abstract::Test" which
951 will run as normal.
952 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 My::Postgres::Test->SKIP_CLASS(
958 $ENV{POSTGRES_HOME} ? 0 : '$POSTGRES_HOME needs to be set'
959 );
960 will output something like this if "POSTGRES_HOME" is not set
962 ... other tests ...
964 ok 123 # skip My::Postgres::Test - $POSTGRES_HOME needs to be set
965 ... more tests ...
966 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 sub My::Postgres::Test::SKIP_CLASS {
972 $ENV{POSTGRES_HOME} ? 0 : '$POSTGRES_HOME needs to be set'
973 }
974 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 Fetch or set the number of tests that the named method is expected
983 to run.
984 If the method has an undetermined number of tests then $n should be
986 the string "no_plan".
987 If the method is extending the number of tests run by the method in
989 a superclass then $n should have a "+" prefix.
990 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 When called as an object method any change to the expected number
996 of tests applies to that object alone.
997 "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 For example, the following test class will run a different number
1003 of tests depending on the number of objects supplied.
1004 package Object::Test;
1006 use base qw(Test::Class);
1007 use Test::More;
1008 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 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 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 "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 For example, consider the creation of a subclass of Object::Test
1038 that ensures that all the opened objects are read-only:
1039 package Special::Object::Test;
1041 use base qw(Object::Test);
1042 use Test::More;
1043 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 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 num_tests
1059 $n = $Tests->num_tests
1060 $Tests->num_tests($n)
1061 $n = CLASS->num_tests
1062 CLASS->num_tests($n)
1063 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 For example:
1069 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 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 Support methods
1083 builder
1084 $Tests->builder
1085 Returns the underlying Test::Builder object that Test::Class uses.
1087 For example:
1088 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 current_method
1096 $method_name = $Tests->current_method
1097 $method_name = CLASS->current_method
1098 Returns the name of the test method currently being executed by
1100 runtests(), or "undef" if runtests() has not been called.
1101 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 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 BAILOUT
1113 $Tests->BAILOUT($reason)
1114 CLASS->BAILOUT($reason)
1115 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 $self->builder->BAILOUT
1121 See "BAILOUT" in Test::Builder for details. Any teardown and
1123 shutdown methods are not run.
1124 FAIL_ALL
1126 $Tests->FAIL_ALL($reason)
1127 CLASS->FAIL_ALL($reason)
1128 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 This does not affect the running of any other test scripts invoked
1135 by Test::Harness.
1136 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 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 SKIP_ALL
1148 $Tests->SKIP_ALL($reason)
1149 CLASS->SKIP_ALL($reason)
1150 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 This does not affect the running of any other test scripts invoked
1156 by Test::Harness.
1157 For example, if you had a test script that only applied to the
1159 darwin OS you could write:
1160 sub _darwin_only : Test(setup) {
1162 my $self = shift;
1163 $self->SKIP_ALL("darwin only") unless $^O eq "darwin";
1164 }
1165 add_testinfo
1167 CLASS->add_testinfo($name, $type, $num_tests)
1168 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 $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 add_filter
1179 CLASS->add_filter($filter_coderef);
1180 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 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 See the section on the "GENERAL FILTERING OF TESTS" for more
1191 information.
1192 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 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
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 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 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 sub foo : Test(2) {
1222 ok($foo->method1);
1223 ok($foo->method2);
1224 }
1225 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 sub foo : Test(2) {
1231 ok($foo->method1) or die "method1 failed";
1232 ok($foo->method2);
1233 }
1234 The exception will be caught by Test::Class and the other test
1236 automatically failed.
1237 Class TestCase
1239 Test::Class corresponds to TestCase in JUnit.
1240 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 Unlike JUnit you can have multiple setup/teardown methods in a
1247 class.
1248 Class TestSuite
1250 Test::Class also does the work that would be done by TestSuite in
1251 JUnit.
1252 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 The running order of the test methods is fixed in Test::Class.
1260 Methods are executed in alphabetical order.
1261 To run individual test methods, see "RUNNING INDIVIDUAL TESTS".
1263 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 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 If you want to write your own test runners you should look at
1273 Test::Harness::Straps.
1274
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 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 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 The advantage of Test::SimpleUnit is that it is simple! Just one
1289 module with a smallish API to learn.
1290 Of course this is also the disadvantage.
1292 It's not class based so you cannot create testing classes to reuse
1294 and extend.
1295 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 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 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 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 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
1321 Bugs may be submitted through GitHub issues
1322 <https://github.com/szabgab/test-class/issues>
1323 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
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 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
1336 This is yet another implementation of the ideas from Kent Beck's
1337 Testing Framework paper <http://www.xprogramming.com/testfram.htm>.
1338 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 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
1359 Adrian Howard <adrianh@quietstars.com>, Curtis "Ovid" Poe, <ovid at
1360 cpan.org>, Mark Morgan <makk384@gmail.com>.
1361
1363 Test::Class::Load
1364 Simple way to load "Test::Class" classes automatically.
1365 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 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 Perl Testing: A Developer's Notebook by Ian Langworth and chromatic
1377 Chapter 8 covers using Test::Class.
1378 Advanced Perl Programming, second edition by Simon Cozens
1380 Chapter 8 has a few pages on using Test::Class.
1381 The Perl Journal, April 2003
1383 Includes the article "Test-Driven Development in Perl" by Piers
1384 Cawley that uses Test::Class.
1385 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 • Reusing Test Code with Test::Class
1392 <http://www.modernperlbooks.com/mt/2009/03/reusing-test-code-
1393 with-testclass.html>
1394 • Making Your Testing Life Easier
1396 <http://www.modernperlbooks.com/mt/2009/03/making-your-testing-
1397 life-easier.html>
1398 • Using Test Control Methods with Test::Class
1400 <http://www.modernperlbooks.com/mt/2009/03/using-test-control-
1401 methods-with-testclass.html>
1402 • Working with Test::Class Test Suites
1404 <http://www.modernperlbooks.com/mt/2009/03/working-with-
1405 testclass-test-suites.html>
1406 Test::Builder
1408 Support module for building test libraries.
1409 Test::Simple & Test::More
1411 Basic utilities for writing tests.
1412 <https://qa.perl.org/test-modules.html>
1414 Overview of some of the many testing modules available on CPAN.
1415 Test::Object
1417 Another approach to object oriented testing.
1418 Test::Group and Test::Block
1420 Alternatives to grouping sets of tests together.
1421 The following modules use Test::Class as part of their test suite. You
1423 might want to look at them for usage examples:
1424 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 The following modules are not based on Test::Builder, but may be of
1432 interest as alternatives to Test::Class.
1433 Test::Unit
1435 Perl unit testing framework closely modeled on JUnit.
1436 Test::SimpleUnit
1438 A very simple unit testing framework.
1439
1441 Copyright 2002-2010 Adrian Howard, All Rights Reserved.
1442 This program is free software; you can redistribute it and/or modify it
1444 under the same terms as Perl itself.
1445perl v5.36.0 2022-07-22 Test::Class(3)