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