Test::Unit::TestCase(3pm)

1Test::Unit::TestCase(3)User Contributed Perl DocumentatioTnest::Unit::TestCase(3)
2
3
4

NAME

6       Test::Unit::TestCase - unit testing framework base class
7

SYNOPSIS

9           package FooBar;
10           use base qw(Test::Unit::TestCase);
11
12           sub new {
13               my $self = shift()->SUPER::new(@_);
14               # your state for fixture here
15               return $self;
16           }
17
18           sub set_up {
19               # provide fixture
20           }
21           sub tear_down {
22               # clean up after test
23           }
24           sub test_foo {
25               my $self = shift;
26               my $obj = ClassUnderTest->new(...);
27               $self->assert_not_null($obj);
28               $self->assert_equals('expected result', $obj->foo);
29               $self->assert(qr/pattern/, $obj->foobar);
30           }
31           sub test_bar {
32               # test the bar feature
33           }
34

DESCRIPTION

36       Test::Unit::TestCase is the 'workhorse' of the PerlUnit framework.
37       When writing tests, you generally subclass Test::Unit::TestCase, write
38       "set_up" and "tear_down" functions if you need them, a bunch of
39       "test_*" test methods, then do
40
41           $ TestRunner.pl My::TestCase::Class
42
43       and watch as your tests fail/succeed one after another. Or, if you want
44       your tests to work under Test::Harness and the standard perlish 'make
45       test', you'd write a t/foo.t that looked like:
46
47           use Test::Unit::HarnessUnit;
48           my $r = Test::Unit::HarnessUnit->new();
49           $r->start('My::TestCase::Class');
50
51   How To Use Test::Unit::TestCase
52       (Taken from the JUnit TestCase class documentation)
53
54       A test case defines the "fixture" (resources need for testing) to run
55       multiple tests. To define a test case:
56
57       1.  implement a subclass of TestCase
58
59       2.  define instance variables that store the state of the fixture (I
60           suppose if you are using Class::MethodMaker this is possible...)
61
62       3.  initialize the fixture state by overriding "set_up()"
63
64       4.  clean-up after a test by overriding "tear_down()".
65
66       Implement your tests as methods.  By default, all methods that match
67       the regex "/^test/" are taken to be test methods (see "list_tests()"
68       and "get_matching_methods()").  Note that, by default all the tests
69       defined in the current class and all of its parent classes will be run.
70       To change this behaviour, see "NOTES".
71
72       By default, each test runs in its own fixture so there can be no side
73       effects among test runs. Here is an example:
74
75             package MathTest;
76             use base qw(Test::Unit::TestCase);
77
78             sub new {
79                 my $self = shift()->SUPER::new(@_);
80                     $self->{value_1} = 0;
81                     $self->{value_2} = 0;
82                     return $self;
83             }
84
85             sub set_up {
86                     my $self = shift;
87                     $self->{value_1} = 2;
88                     $self->{value_2} = 3;
89             }
90
91       For each test implement a method which interacts with the fixture.
92       Verify the expected results with assertions specified by calling
93       "$self->assert()" with a boolean value.
94
95             sub test_add {
96                     my $self = shift;
97                     my $result = $self->{value_1} + $self->{value_2};
98                     $self->assert($result == 5);
99             }
100
101       Once the methods are defined you can run them. The normal way to do
102       this uses reflection to implement "run_test". It dynamically finds and
103       invokes a method. For this the name of the test case has to correspond
104       to the test method to be run. The tests to be run can be collected into
105       a TestSuite. The framework provides different test runners, which can
106       run a test suite and collect the results. A test runner either expects
107       a method "suite()" as the entry point to get a test to run or it will
108       extract the suite automatically.
109
110   Writing Test Methods
111       The return value of your test method is completely irrelevant. The
112       various test runners assume that a test is executed successfully if no
113       exceptions are thrown. Generally, you will not have to deal directly
114       with exceptions, but will write tests that look something like:
115
116           sub test_something {
117               my $self = shift;
118               # Execute some code which gives some results.
119               ...
120               # Make assertions about those results
121               $self->assert_equals('expected value', $resultA);
122               $self->assert_not_null($result_object);
123               $self->assert(qr/some_pattern/, $resultB);
124           }
125
126       The assert methods throw appropriate exceptions when the assertions
127       fail, which will generally stringify nicely to give you sensible error
128       reports.
129
130       Test::Unit::Assert has more details on the various different "assert"
131       methods.
132
133       Test::Unit::Exception describes the Exceptions used within the
134       "Test::Unit::*" framework.
135
136   Helper methods
137       make_test_from_coderef (CODEREF, [NAME])
138           Takes a coderef and an optional name and returns a Test case that
139           inherits from the object on which it was called, which has the
140           coderef installed as its "run_test" method. Class::Inner has more
141           details on how this is generated.
142
143       list_tests
144           Returns the list of test methods in this class and its parents. You
145           can override this in your own classes, but remember to call
146           "SUPER::list_tests" in there too.  Uses "get_matching_methods".
147
148       get_matching_methods (REGEXP)
149           Returns the list of methods in this class matching REGEXP.
150
151       set_up
152       tear_down
153           If you don't have any setup or tear down code that needs to be run,
154           we provide a couple of null methods. Override them if you need to.
155
156       annotate (MESSAGE)
157           You can accumulate helpful debugging for each testcase method via
158           this method, and it will only be outputted if the test fails or
159           encounters an error.
160
161   How it All Works
162       The PerlUnit framework is achingly complex. The basic idea is that you
163       get to write your tests independently of the manner in which they will
164       be run, either via a "make test" type script, or through one of the
165       provided TestRunners, the framework will handle all that for you. And
166       it does. So for the purposes of someone writing tests, in the majority
167       of cases the answer is 'It just does.'.
168
169       Of course, if you're trying to extend the framework, life gets a little
170       more tricky. The core class that you should try and grok is probably
171       Test::Unit::Result, which, in tandem with whichever TestRunner is being
172       used mediates the process of running tests, stashes the results and
173       generally sits at the centre of everything.
174
175       Better docs will be forthcoming.
176

NOTES

178       Here's a few things to remember when you're writing your test suite:
179
180       Tests are run in 'random' order; the list of tests in your TestCase are
181       generated automagically from its symbol table, which is a hash, so
182       methods aren't sorted there.
183
184       If you need to specify the test order, you can do one of the following:
185
186       •   Set @TESTS
187
188             our @TESTS = qw(my_test my_test_2);
189
190           This is the simplest, and recommended way.
191
192       •   Override the "list_tests()" method
193
194           to return an ordered list of methodnames
195
196       •   Provide a "suite()" method
197
198           which returns a Test::Unit::TestSuite.
199
200       However, even if you do manage to specify the test order, be careful,
201       object data will not be retained from one test to another, if you want
202       to use persistent data you'll have to use package lexicals or globals.
203       (Yes, this is probably a bug).
204
205       If you only need to restrict which tests are run, there is a filtering
206       mechanism available.  Override the "filter()" method in your testcase
207       class to return a hashref whose keys are filter tokens and whose values
208       are either arrayrefs of test method names or coderefs which take the
209       method name as the sole parameter and return true if and only if it
210       should be filtered, e.g.
211
212         sub filter {{
213             slow => [ qw(my_slow_test my_really_slow_test) ],
214             matching_foo => sub {
215                 my $method = shift;
216                 return $method =~ /foo/;
217             }
218         }}
219
220       Then, set the filter state in your runner before the test run starts:
221
222         # @filter_tokens = ( 'slow', ... );
223         $runner->filter(@filter_tokens);
224         $runner->start(@args);
225
226       This interface is public, but currently undocumented (see doc/TODO).
227

BUGS

229       See note 1 for at least one bug that's got me scratching my head.
230       There's bound to be others.
231

AUTHOR

233       Copyright (c) 2000-2002, 2005 the PerlUnit Development Team (see
234       Test::Unit or the AUTHORS file included in this distribution).
235
236       All rights reserved. This program is free software; you can
237       redistribute it and/or modify it under the same terms as Perl itself.
238

NAME

SYNOPSIS

DESCRIPTION

NOTES

BUGS

AUTHOR

SEE ALSO