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.50
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 You can skip the rest of the tests in a method by returning from the
490 method before all the test have finished running (but see "Returning
491 Early" for how to change this). The value returned is used as the
492 reason for the tests being skipped.
493 This makes managing tests that can be skipped for multiple reasons very
495 simple. For example:
496 sub flying_pigs : Test(5) {
498 my $pig = Pig->new;
499 isa_ok($pig, 'Pig') or return("cannot breed pigs")
500 can_ok($pig, 'takeoff') or return("pigs don't fly here");
501 ok($pig->takeoff, 'takeoff') or return("takeoff failed");
502 ok( $pig->altitude > 0, 'Pig is airborne' );
503 ok( $pig->airspeed > 0, ' and moving' );
504 }
505 If you run this test in an environment where "Pig->new" worked and the
507 takeoff method existed, but failed when ran, you would get:
508 ok 1 - The object isa Pig
510 ok 2 - can takeoff
511 not ok 3 - takeoff
512 ok 4 # skip takeoff failed
513 ok 5 # skip takeoff failed
514 You can also skip tests just as you do in Test::More or Test::Builder -
516 see "Conditional tests" in Test::More for more information.
517 Note: if you want to skip tests in a method with "no_plan" tests then
519 you have to explicitly skip the tests in the method - since Test::Class
520 cannot determine how many tests (if any) should be skipped:
521 sub test_objects : Tests {
523 my $self = shift;
524 my $objects = $self->{objects};
525 if (@$objects) {
526 isa_ok($_, "Object") foreach (@$objects);
527 } else {
528 $self->builder->skip("no objects to test");
529 }
530 }
531 Another way of overcoming this problem is to explicitly set the number
533 of tests for the method at run time using num_method_tests() or
534 "num_tests".
535 You can make a test class skip all of its tests by setting SKIP_CLASS()
537 before runtests() is called.
538
540 You can create todo tests just as you do in Test::More and
541 Test::Builder using the $TODO variable. For example:
542 sub live_test : Test {
544 local $TODO = "live currently unimplemented";
545 ok(Object->live, "object live");
546 }
547 See "Todo tests" in Test::Harness for more information.
549
551 You can extend test methods by inheritance in the usual way. For
552 example consider the following test class for a "Pig" object.
553 package Pig::Test;
555 use base qw(Test::Class);
556 use Test::More;
557 sub testing_class { "Pig" }
559 sub new_args { (-age => 3) }
560 sub setup : Test(setup) {
562 my $self = shift;
563 my $class = $self->testing_class;
564 my @args = $self->new_args;
565 $self->{pig} = $class->new( @args );
566 }
567 sub _creation : Test {
569 my $self = shift;
570 isa_ok($self->{pig}, $self->testing_class)
571 or $self->FAIL_ALL('Pig->new failed');
572 }
573 sub check_fields : Test {
575 my $pig = shift->{pig}
576 is($pig->age, 3, "age accessed");
577 }
578 Next consider "NamedPig" a subclass of "Pig" where you can give your
580 pig a name.
581 We want to make sure that all the tests for the "Pig" object still work
583 for "NamedPig". We can do this by subclassing "Pig::Test" and
584 overriding the "testing_class" and "new_args" methods.
585 package NamedPig::Test;
587 use base qw(Pig::Test);
588 use Test::More;
589 sub testing_class { "NamedPig" }
591 sub new_args { (shift->SUPER::new_args, -name => 'Porky') }
592 Now we need to test the name method. We could write another test
594 method, but we also have the option of extending the existing
595 "check_fields" method.
596 sub check_fields : Test(2) {
598 my $self = shift;
599 $self->SUPER::check_fields;
600 is($self->{pig}->name, 'Porky', 'name accessed');
601 }
602 While the above works, the total number of tests for the method is
604 dependent on the number of tests in its "SUPER::check_fields". If we
605 add a test to "Pig::Test->check_fields" we will also have to update the
606 number of tests of "NamedPig::test->check_fields".
607 Test::Class allows us to state explicitly that we are adding tests to
609 an existing method by using the "+" prefix. Since we are adding a
610 single test to "check_fields", it can be rewritten as:
611 sub check_fields : Test(+1) {
613 my $self = shift;
614 $self->SUPER::check_fields;
615 is($self->{pig}->name, 'Porky', 'name accessed');
616 }
617 With the above definition you can add tests to "check_fields" in
619 "Pig::Test" without affecting "NamedPig::Test".
620
622 NOTE: The exact mechanism for running individual tests is likely to
623 change in the future.
624 Sometimes you just want to run a single test. Commenting out other
626 tests or writing code to skip them can be a hassle, so you can specify
627 the "TEST_METHOD" environment variable. The value is expected to be a
628 valid regular expression and, if present, only runs test methods whose
629 names match the regular expression. Startup, setup, teardown and
630 shutdown tests will still be run.
631 One easy way of doing this is by specifying the environment variable
633 before the "runtests" method is called.
634 Running a test named "customer_profile":
636 #! /usr/bin/perl
638 use Example::Test;
639 $ENV{TEST_METHOD} = 'customer_profile';
641 Test::Class->runtests;
642 Running all tests with "customer" in their name:
644 #! /usr/bin/perl
646 use Example::Test;
647 $ENV{TEST_METHOD} = '.*customer.*';
649 Test::Class->runtests;
650 If you specify an invalid regular expression, your tests will not be
652 run:
653 #! /usr/bin/perl
655 use Example::Test;
656 $ENV{TEST_METHOD} = 'C++';
658 Test::Class->runtests;
659 And when you run it:
661 TEST_METHOD (C++) is not a valid regular expression: Search pattern \
663 not terminated at (eval 17) line 1.
664
666 You can, of course, organise your test modules as you wish. My personal
667 preferences is:
668 · Name test classes with a suffix of "::Test" so the test class for
670 the "Foo::Bar" module would be "Foo::Bar::Test".
671 · Place all test classes in t/lib.
673 The Test::Class::Load provides a simple mechanism for easily loading
675 all of the test classes in a given set of directories.
676
678 Due to its use of subroutine attributes Test::Class based modules must
679 be loaded at compile rather than run time. This is because the :Test
680 attribute is applied by a CHECK block.
681 This can be problematic if you want to dynamically load Test::Class
683 modules. Basically while:
684 require $some_test_class;
686 will break, doing:
688 BEGIN { require $some_test_class }
690 will work just fine. For more information on CHECK blocks see "BEGIN,
692 CHECK, INIT and END" in perlmod.
693 If you still can't arrange for your classes to be loaded at runtime,
695 you could use an alternative mechanism for adding your tests:
696 # sub test_something : Test(3) {...}
698 # becomes
699 sub test_something {...}
700 __PACKAGE__->add_testinfo('test_something', test => 3);
701 See the add_testinfo method for more details.
703 Additionally, if you've forgotten to enable warnings and have two test
705 subs called the same thing, you will get the same error.
706
708 The use of $ENV{TEST_METHOD} to run just a subset of tests is useful,
709 but sometimes it doesn't give the level of granularity that you desire.
710 Another feature of this class is the ability to do filtering on other
711 static criteria. In order to permit this, a generic filtering method
712 is supported. This can be used by specifying coderefs to the
713 'add_filter' method of this class.
714 In determining which tests should be run, all filters that have
716 previously been specified via the add_filter method will be run in-turn
717 for each normal test method. If any of these filters return a false
718 value, the method will not be executed, or included in the number of
719 tests. Note that filters will only be run for normal test methods,
720 they are ignored for startup, shutdown, setup, and teardown test
721 methods.
722 Note that test filters are global, and will affect all tests in all
724 classes, not just the one that they were defined in.
725 An example of this mechanism that mostly simulates the use of
727 TEST_METHOD above is:
728 package MyTests;
730 use Test::More;
732 use base qw( Test::Class );
734 my $MYTEST_METHOD = qr/^t_not_filtered$/;
736 my $filter = sub {
738 my ( $test_class, $test_method ) = @_;
739 return $test_method =~ $MYTEST_METHOD;
741 }
742 Test::Class->add_filter( $filter );
743 sub t_filtered : Test( 1 ) {
745 fail( "filtered test run" );
746 }
747 sub t_not_filtered : Test( 1 ) {
749 pass( "unfiltered test run" );
750 }
751
753 Creating and running tests
754 Test
755 # test methods
756 sub method_name : Test { ... }
757 sub method_name : Test(N) { ... }
758 # setup methods
760 sub method_name : Test(setup) { ... }
761 sub method_name : Test(setup => N) { ... }
762 # teardown methods
764 sub method_name : Test(teardown) { ... }
765 sub method_name : Test(teardown => N) { ... }
766 # startup methods
768 sub method_name : Test(startup) { ... }
769 sub method_name : Test(startup => N) { ... }
770 # shutdown methods
772 sub method_name : Test(shutdown) { ... }
773 sub method_name : Test(shutdown => N) { ... }
774 Marks a startup, setup, test, teardown or shutdown method. See
776 runtests() for information on how to run methods declared with the
777 "Test" attribute.
778 N specifies the number of tests the method runs.
780 · If N is an integer then the method should run exactly N tests.
782 · If N is an integer with a "+" prefix then the method is
784 expected to call its "SUPER::" method and extend it by running
785 N additional tests.
786 · If N is the string "no_plan" then the method can run an
788 arbitrary number of tests.
789 If N is not specified it defaults to 1 for test methods, and 0 for
791 startup, setup, teardown and shutdown methods.
792 You can change the number of tests that a method runs using
794 num_method_tests() or num_tests().
795 Tests
797 sub method_name : Tests { ... }
798 sub method_name : Tests(N) { ... }
799 Acts just like the ":Test" attribute, except that if the number of
801 tests is not specified it defaults to "no_plan". So the following
802 are equivalent:
803 sub silly1 :Test( no_plan ) { ok(1) foreach (1 .. rand 5) }
805 sub silly2 :Tests { ok(1) foreach (1 .. rand 5) }
806 new
808 $Tests = CLASS->new(KEY => VAL ...)
809 $Tests2 = $Tests->new(KEY => VAL ...)
810 Creates a new test object (blessed hashref) containing the
812 specified key/value pairs.
813 If called as an object method the existing object's key/value pairs
815 are copied into the new object. Any key/value pairs passed to "new"
816 override those in the original object if duplicates occur.
817 Since the test object is passed to every test method as it runs, it
819 is a convenient place to store test fixtures. For example:
820 sub make_fixture : Test(setup) {
822 my $self = shift;
823 $self->{object} = Object->new();
824 $self->{dbh} = Mock::DBI->new(-type => normal);
825 }
826 sub test_open : Test {
828 my $self = shift;
829 my ($o, $dbh) = ($self->{object}, $self->{dbh});
830 ok($o->open($dbh), "opened ok");
831 }
832 See num_method_tests() for an example of overriding "new".
834 expected_tests
836 $n = $Tests->expected_tests
837 $n = CLASS->expected_tests
838 $n = $Tests->expected_tests(TEST, ...)
839 $n = CLASS->expected_tests(TEST, ...)
840 Returns the total number of tests that runtests() will run on the
842 specified class/object. This includes tests run by any setup and
843 teardown methods.
844 Will return "no_plan" if the exact number of tests is undetermined
846 (i.e. if any setup, test or teardown method has an undetermined
847 number of tests).
848 The "expected_tests" of an object after runtests() has been
850 executed will include any run time changes to the expected number
851 of tests made by num_tests() or num_method_tests().
852 "expected_tests" can also take an optional list of test objects,
854 test classes and integers. In this case the result is the total
855 number of expected tests for all the test/object classes (including
856 the one the method was applied to) plus any integer values.
857 "expected_tests" is useful when you're integrating one or more test
859 classes into a more traditional test script, for example:
860 use Test::More;
862 use My::Test::Class;
863 plan tests => My::Test::Class->expected_tests(+2);
865 ok(whatever, 'a test');
867 ok(whatever, 'another test');
868 My::Test::Class->runtests;
869 runtests
871 $allok = $Tests->runtests
872 $allok = CLASS->runtests
873 $allok = $Tests->runtests(TEST, ...)
874 $allok = CLASS->runtests(TEST, ...)
875 "runtests" is used to run test classes. At its most basic doing:
877 $test->runtests
879 will run the test methods of the test object $test, unless
881 "$test->SKIP_CLASS" returns a true value.
882 Unless you have already specified a test plan using Test::Builder
884 (or Test::More, et al) "runtests" will set the test plan just
885 before the first method that runs a test is executed.
886 If the environment variable "TEST_VERBOSE" is set "runtests" will
888 display the name of each test method before it runs like this:
889 # My::Test::Class->my_test
891 ok 1 - fribble
892 # My::Test::Class->another_test
893 ok 2 - bar
894 Just like expected_tests(), "runtests" can take an optional list of
896 test object/classes and integers. All of the test object/classes
897 are run. Any integers are added to the total number of tests shown
898 in the test header output by "runtests".
899 For example, you can run all the tests in test classes A, B and C,
901 plus one additional normal test by doing:
902 Test::Class->runtests(qw(A B C), +1);
904 ok(1==1, 'non class test');
905 Finally, if you call "runtests" on a test class without any
907 arguments it will run all of the test methods of that class, and
908 all subclasses of that class. For example:
909 #! /usr/bin/perl
911 # Test all the Foo stuff
912 use Foo::Test;
914 use Foo::Bar::Test;
915 use Foo::Ni::Test;
916 # run all the Foo*Test modules we just loaded
918 Test::Class->runtests;
919 SKIP_CLASS
921 $reason = CLASS->SKIP_CLASS;
922 CLASS->SKIP_CLASS( $reason );
923 Determines whether the test class CLASS should run it's tests. If
925 SKIP_CLASS returns a true value then runtests() will not run any
926 of the test methods in CLASS.
927 You can override the default on a class-by-class basis by supplying
929 a new value to SKIP_CLASS. For example if you have an abstract base
930 class that should not run just add the following to your module:
931 My::Abstract::Test->SKIP_CLASS( 1 );
933 This will not affect any sub-classes of "My::Abstract::Test" which
935 will run as normal.
936 If the true value returned by SKIP_CLASS is anything other than "1"
938 then a skip test is output using this value as the skip message.
939 For example:
940 My::Postgres::Test->SKIP_CLASS(
942 $ENV{POSTGRES_HOME} ? 0 : '$POSTGRES_HOME needs to be set'
943 );
944 will output something like this if "POSTGRES_HOME" is not set
946 ... other tests ...
948 ok 123 # skip My::Postgres::Test - $POSTGRES_HOME needs to be set
949 ... more tests ...
950 You can also override SKIP_CLASS for a class hierarchy. For
952 example, to prevent any subclasses of My::Postgres::Test running we
953 could override SKIP_CLASS like this:
954 sub My::Postgres::Test::SKIP_CLASS {
956 $ENV{POSTGRES_HOME} ? 0 : '$POSTGRES_HOME needs to be set'
957 }
958 Fetching and setting a method's test number
960 num_method_tests
961 $n = $Tests->num_method_tests($method_name)
962 $Tests->num_method_tests($method_name, $n)
963 $n = CLASS->num_method_tests($method_name)
964 CLASS->num_method_tests($method_name, $n)
965 Fetch or set the number of tests that the named method is expected
967 to run.
968 If the method has an undetermined number of tests then $n should be
970 the string "no_plan".
971 If the method is extending the number of tests run by the method in
973 a superclass then $n should have a "+" prefix.
974 When called as a class method any change to the expected number of
976 tests applies to all future test objects. Existing test objects are
977 unaffected.
978 When called as an object method any change to the expected number
980 of tests applies to that object alone.
981 "num_method_tests" is useful when you need to set the expected
983 number of tests at object creation time, rather than at compile
984 time.
985 For example, the following test class will run a different number
987 of tests depending on the number of objects supplied.
988 package Object::Test;
990 use base qw(Test::Class);
991 use Test::More;
992 sub new {
994 my $class = shift;
995 my $self = $class->SUPER::new(@_);
996 my $num_objects = @{$self->{objects}};
997 $self->num_method_tests('test_objects', $num_objects);
998 return($self);
999 }
1000 sub test_objects : Tests {
1002 my $self = shift;
1003 ok($_->open, "opened $_") foreach @{$self->{objects}};
1004 }
1005 ...
1006 # This runs two tests
1007 Object::Test->new(objects => [$o1, $o2]);
1008 The advantage of setting the number of tests at object creation
1010 time, rather than using a test method without a plan, is that the
1011 number of expected tests can be determined before testing begins.
1012 This allows better diagnostics from runtests(), Test::Builder and
1013 Test::Harness.
1014 "num_method_tests" is a protected method and can only be called by
1016 subclasses of Test::Class. It fetches or sets the expected number
1017 of tests for the methods of the class it was called in, not the
1018 methods of the object/class it was applied to. This allows test
1019 classes that use "num_method_tests" to be subclassed easily.
1020 For example, consider the creation of a subclass of Object::Test
1022 that ensures that all the opened objects are read-only:
1023 package Special::Object::Test;
1025 use base qw(Object::Test);
1026 use Test::More;
1027 sub test_objects : Test(+1) {
1029 my $self = shift;
1030 $self->SUPER::test_objects;
1031 my @bad_objects = grep {! $_->read_only} (@{$self->{objects}});
1032 ok(@bad_objects == 0, "all objects read only");
1033 }
1034 ...
1035 # This runs three tests
1036 Special::Object::Test->new(objects => [$o1, $o2]);
1037 Since the call to "num_method_tests" in Object::Test only affects
1039 the "test_objects" of Object::Test, the above works as you would
1040 expect.
1041 num_tests
1043 $n = $Tests->num_tests
1044 $Tests->num_tests($n)
1045 $n = CLASS->num_tests
1046 CLASS->num_tests($n)
1047 Set or return the number of expected tests associated with the
1049 currently running test method. This is the same as calling
1050 num_method_tests() with a method name of current_method().
1051 For example:
1053 sub txt_files_readable : Tests {
1055 my $self = shift;
1056 my @files = <*.txt>;
1057 $self->num_tests(scalar(@files));
1058 ok(-r $_, "$_ readable") foreach (@files);
1059 }
1060 Setting the number of expected tests at run time, rather than just
1062 having a "no_plan" test method, allows runtests() to display
1063 appropriate diagnostic messages if the method runs a different
1064 number of tests.
1065 Support methods
1067 builder
1068 $Tests->builder
1069 Returns the underlying Test::Builder object that Test::Class uses.
1071 For example:
1072 sub test_close : Test {
1074 my $self = shift;
1075 my ($o, $dbh) = ($self->{object}, $self->{dbh});
1076 $self->builder->ok($o->close($dbh), "closed ok");
1077 }
1078 current_method
1080 $method_name = $Tests->current_method
1081 $method_name = CLASS->current_method
1082 Returns the name of the test method currently being executed by
1084 runtests(), or "undef" if runtests() has not been called.
1085 The method name is also available in the setup and teardown methods
1087 that run before and after the test method. This can be useful in
1088 producing diagnostic messages, for example:
1089 sub test_invarient : Test(teardown => 1) {
1091 my $self = shift;
1092 my $m = $self->current_method;
1093 ok($self->invarient_ok, "class okay after $m");
1094 }
1095 BAILOUT
1097 $Tests->BAILOUT($reason)
1098 CLASS->BAILOUT($reason)
1099 Things are going so badly all testing should terminate, including
1101 running any additional test scripts invoked by Test::Harness. This
1102 is exactly the same as doing:
1103 $self->builder->BAILOUT
1105 See "BAILOUT" in Test::Builder for details. Any teardown and
1107 shutdown methods are not run.
1108 FAIL_ALL
1110 $Tests->FAIL_ALL($reason)
1111 CLASS->FAIL_ALL($reason)
1112 Things are going so badly all the remaining tests in the current
1114 script should fail. Exits immediately with the number of tests
1115 failed, or 254 if more than 254 tests were run. Any teardown
1116 methods are not run.
1117 This does not affect the running of any other test scripts invoked
1119 by Test::Harness.
1120 For example, if all your tests rely on the ability to create
1122 objects then you might want something like this as an early test:
1123 sub _test_new : Test(3) {
1125 my $self = shift;
1126 isa_ok(Object->new, "Object")
1127 || $self->FAIL_ALL('cannot create Objects');
1128 ...
1129 }
1130 SKIP_ALL
1132 $Tests->SKIP_ALL($reason)
1133 CLASS->SKIP_ALL($reason)
1134 Things are going so badly all the remaining tests in the current
1136 script should be skipped. Exits immediately with 0 - teardown
1137 methods are not run.
1138 This does not affect the running of any other test scripts invoked
1140 by Test::Harness.
1141 For example, if you had a test script that only applied to the
1143 darwin OS you could write:
1144 sub _darwin_only : Test(setup) {
1146 my $self = shift;
1147 $self->SKIP_ALL("darwin only") unless $^O eq "darwin";
1148 }
1149 add_testinfo
1151 CLASS->add_testinfo($name, $type, $num_tests)
1152 Chiefly for use by libraries like Test::Class::Sugar, which can't
1154 use the ":Test(...)" interfaces make test methods. "add_testinfo"
1155 informs the class about a test method that has been defined without
1156 a "Test", "Tests" or other attribute.
1157 $name is the name of the method, $type must be one of "startup",
1159 "setup", "test", "teardown" or "shutdown", and $num_tests has the
1160 same meaning as "N" in the description of the Test attribute.
1161 add_filter
1163 CLASS->add_filter($filter_coderef);
1164 Adds a filtering coderef. Each filter is passed a test class and
1166 method name and returns a boolean. All filters are applied globally
1167 in the order they were added. If any filter returns false the test
1168 method is not run or included in the number of tests.
1169 Note that filters will only be run for normal test methods, they
1171 are ignored for startup, shutdown, setup, and teardown test
1172 methods.
1173 See the section on the "GENERAL FILTERING OF TESTS" for more
1175 information.
1176 fail_if_returned_early
1178 Controls what happens if a method returns before it has run all of
1179 its tests. It is called with no arguments in boolean context; if
1180 it returns true, then the missing tests fail, otherwise, they skip.
1181 See "Returning Early" and "Skipped Tests".
1182
1184 This section is for people who have used JUnit (or similar) and are
1185 confused because they don't see the TestCase/Suite/Runner class
1186 framework they were expecting. Here we take each of the major classes
1187 in JUnit and compare them with their equivalent Perl testing modules.
1188 Class Assert
1190 The test assertions provided by Assert correspond to the test
1191 functions provided by the Test::Builder based modules (Test::More,
1192 Test::Exception, Test::Differences, etc.)
1193 Unlike JUnit the test functions supplied by Test::More et al do not
1195 throw exceptions on failure. They just report the failure to STDOUT
1196 where it is collected by Test::Harness. This means that where you
1197 have
1198 sub foo : Test(2) {
1200 ok($foo->method1);
1201 ok($foo->method2);
1202 }
1203 The second test will run if the first one fails. You can emulate
1205 the JUnit way of doing it by throwing an explicit exception on test
1206 failure:
1207 sub foo : Test(2) {
1209 ok($foo->method1) or die "method1 failed";
1210 ok($foo->method2);
1211 }
1212 The exception will be caught by Test::Class and the other test
1214 automatically failed.
1215 Class TestCase
1217 Test::Class corresponds to TestCase in JUnit.
1218 In Test::Class setup, test and teardown methods are marked
1220 explicitly using the Test attribute. Since we need to know the
1221 total number of tests to provide a test plan for Test::Harness, we
1222 also state how many tests each method runs.
1223 Unlike JUnit you can have multiple setup/teardown methods in a
1225 class.
1226 Class TestSuite
1228 Test::Class also does the work that would be done by TestSuite in
1229 JUnit.
1230 Since the methods are marked with attributes, Test::Class knows
1232 what is and isn't a test method. This allows it to run all the test
1233 methods without having the developer create a suite manually, or
1234 use reflection to dynamically determine the test methods by name.
1235 See the runtests() method for more details.
1236 The running order of the test methods is fixed in Test::Class.
1238 Methods are executed in alphabetical order.
1239 To run individual test methods, see "RUNNING INDIVIDUAL TESTS".
1241 Class TestRunner
1243 Test::Harness does the work of the TestRunner in JUnit. It collects
1244 the test results (sent to STDOUT) and collates the results.
1245 Unlike JUnit there is no distinction made by Test::Harness between
1247 errors and failures. However, it does support skipped and todo test
1248 - which JUnit does not.
1249 If you want to write your own test runners you should look at
1251 Test::Harness::Straps.
1252
1254 In addition to Test::Class there are two other distributions for xUnit
1255 testing in perl. Both have a longer history than Test::Class and might
1256 be more suitable for your needs.
1257 I am biased since I wrote Test::Class - so please read the following
1259 with appropriate levels of scepticism. If you think I have
1260 misrepresented the modules please let me know.
1261 Test::SimpleUnit
1263 A very simple unit testing framework. If you are looking for a
1264 lightweight single module solution this might be for you.
1265 The advantage of Test::SimpleUnit is that it is simple! Just one
1267 module with a smallish API to learn.
1268 Of course this is also the disadvantage.
1270 It's not class based so you cannot create testing classes to reuse
1272 and extend.
1273 It doesn't use Test::Builder so it's difficult to extend or
1275 integrate with other testing modules. If you are already familiar
1276 with Test::Builder, Test::More and friends you will have to learn a
1277 new test assertion API. It does not support todo tests.
1278 Test::Unit
1280 Test::Unit is a port of JUnit <http://www.junit.org/> into perl. If
1281 you have used JUnit then the Test::Unit framework should be very
1282 familiar.
1283 It is class based so you can easily reuse your test classes and
1285 extend by subclassing. You get a nice flexible framework you can
1286 tweak to your heart's content. If you can run Tk you also get a
1287 graphical test runner.
1288 However, Test::Unit is not based on Test::Builder. You cannot
1290 easily move Test::Builder based test functions into Test::Unit
1291 based classes. You have to learn another test assertion API.
1292 Test::Unit implements it's own testing framework separate from
1294 Test::Harness. You can retrofit *.t scripts as unit tests, and
1295 output test results in the format that Test::Harness expects, but
1296 things like todo tests and skipping tests are not supported.
1297
1299 None known at the time of writing.
1300 If you find any bugs please let me know by e-mail at
1302 <adrianh@quietstars.com>, or report the problem with
1303 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Class>.
1304
1306 perl-qa
1307 If you are interested in testing using Perl I recommend you visit
1308 <http://qa.perl.org/> and join the excellent perl-qa mailing list. See
1309 <http://lists.perl.org/showlist.cgi?name=perl-qa> for details on how to
1310 subscribe.
1311 perlmonks
1313 You can find users of Test::Class, including the module author, on
1314 <http://www.perlmonks.org/>. Feel free to ask questions on Test::Class
1315 there.
1316 CPAN::Forum
1318 The CPAN Forum is a web forum for discussing Perl's CPAN modules. The
1319 Test::Class forum can be found at
1320 <http://www.cpanforum.com/dist/Test-Class>.
1321
1323 If you think this module should do something that it doesn't (or does
1324 something that it shouldn't) please let me know.
1325 You can see my current to do list at
1327 <http://adrianh.tadalist.com/lists/public/4798>, with an RSS feed of
1328 changes at <http://adrianh.tadalist.com/lists/feed_public/4798>.
1329
1331 This is yet another implementation of the ideas from Kent Beck's
1332 Testing Framework paper <http://www.xprogramming.com/testfram.htm>.
1333 Thanks to Adam Kennedy, agianni, Alexander D'Archangel, Andrew
1335 Grangaard, Apocalypse, Ask Bjorn Hansen, Chris Dolan, Chris Williams,
1336 Corion, Cosimo Streppone, Daniel Berger, Dave Evans, Dave O'Neill,
1337 David Cantrell, David Wheeler, Diab Jerius, Emil Jansson, Gunnar Wolf,
1338 Hai Pham, Hynek, imacat, Jeff Deifik, Jim Brandt, Jochen Stenzel, Johan
1339 Lindstrom, John West, Jonathan R. Warden, Joshua ben Jore, Jost
1340 Krieger, Ken Fox, Kenichi Ishigaki Lee Goddard, Mark Morgan, Mark
1341 Reynolds, Mark Stosberg, Martin Ferrari, Mathieu Sauve-Frankel, Matt
1342 Trout, Matt Williamson, Michael G Schwern, Murat Uenalan, Naveed
1343 Massjouni, Nicholas Clark, Ovid, Piers Cawley, Rob Kinyon, Sam Raymer,
1344 Scott Lanning, Sebastien Aperghis-Tramoni, Steve Kirkup, Stray Toaster,
1345 Ted Carnahan, Terrence Brannon, Todd W, Tom Metro, Tony Bowden, Tony
1346 Edwardson, William McKee, various anonymous folk and all the fine
1347 people on perl-qa for their feedback, patches, suggestions and nagging.
1348 This module wouldn't be possible without the excellent Test::Builder.
1350 Thanks to chromatic and Michael G Schwern for creating such a useful
1351 module.
1352
1354 Adrian Howard <adrianh@quietstars.com>, Curtis "Ovid" Poe, <ovid at
1355 cpan.org>, Mark Morgan <makk384@gmail.com>.
1356 If you use this module, and can spare the time please let us know or
1358 rate it at <http://cpanratings.perl.org/rate/?distribution=Test-Class>.
1359
1361 Test::Class::Load
1362 Simple way to load "Test::Class" classes automatically.
1363 Test::Class::Most
1365 Test::Class with additional conveniences to reduce need for some
1366 boilerplate code. Also makes Test::Most testing functions
1367 available.
1368 Test::Class::Moose
1370 Testing framework allows you to write your tests in Moose and test
1371 Moose and non-Moose code. It offers reporting, extensibility, test
1372 inheritance, parallel testing and more.
1373 <http://del.icio.us/tag/Test::Class>
1375 Delicious links on Test::Class.
1376 Perl Testing: A Developer's Notebook by Ian Langworth and chromatic
1378 Chapter 8 covers using Test::Class.
1379 Advanced Perl Programming, second edition by Simon Cozens
1381 Chapter 8 has a few pages on using Test::Class.
1382 The Perl Journal, April 2003
1384 Includes the article "Test-Driven Development in Perl" by Piers
1385 Cawley that uses Test::Class.
1386 Test::Class Tutorial series written by Curtis "Ovid" Poe
1388 · <http://www.modernperlbooks.com/mt/2009/03/organizing-test-suites-with-testclass.html>
1389 · <http://www.modernperlbooks.com/mt/2009/03/reusing-test-code-with-testclass.html>
1391 · <http://www.modernperlbooks.com/mt/2009/03/making-your-testing-life-easier.html>
1393 · <http://www.modernperlbooks.com/mt/2009/03/using-test-control-methods-with-testclass.html>
1395 · <http://www.modernperlbooks.com/mt/2009/03/working-with-testclass-test-suites.html>
1397 Test::Builder
1399 Support module for building test libraries.
1400 Test::Simple & Test::More
1402 Basic utilities for writing tests.
1403 <http://qa.perl.org/test-modules.html>
1405 Overview of some of the many testing modules available on CPAN.
1406 <http://del.icio.us/tag/perl+testing>
1408 Delicious links on perl testing.
1409 Test::Object
1411 Another approach to object oriented testing.
1412 Test::Group and Test::Block
1414 Alternatives to grouping sets of tests together.
1415 The following modules use Test::Class as part of their test suite. You
1417 might want to look at them for usage examples:
1418 App-GitGot, Aspect, Bricolage (<http://www.bricolage.cc/>), CHI,
1420 Cinnamon, Class::StorageFactory, CGI::Application::Search,
1421 DBIx::Romani, Xmldoom, Object::Relational, File::Random,
1422 Geography::JapanesePrefectures, Google::Adwords, Merge::HashRef,
1423 PerlBuildSystem, Ubic, Pixie, Yahoo::Marketing, and XUL-Node
1424 The following modules are not based on Test::Builder, but may be of
1426 interest as alternatives to Test::Class.
1427 Test::Unit
1429 Perl unit testing framework closely modeled on JUnit.
1430 Test::SimpleUnit
1432 A very simple unit testing framework.
1433
1435 Copyright 2002-2010 Adrian Howard, All Rights Reserved.
1436 This program is free software; you can redistribute it and/or modify it
1438 under the same terms as Perl itself.
1439perl v5.32.0 2020-07-28 Test::Class(3)