| 1 | package Test::Unit::TestSuite; | ||
| 2 | BEGIN { | ||
| 3 | 6 | ▶ | $Test::Unit::TestSuite::VERSION = '0.25_1325'; # added by dist-tools/SetVersion.pl |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 4 | } | ||
| 5 | 6 | ▶ | use strict; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 6 | |||
| 7 | =head1 NAME | ||
| 8 | |||
| 9 | Test::Unit::TestSuite - unit testing framework base class | ||
| 10 | |||
| 11 | =cut | ||
| 12 | |||
| 13 | 6 | ▶ | use base 'Test::Unit::Test'; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 14 | |||
| 15 | 6 | ▶ | use Carp; |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 16 | |||
| 17 | 6 | ▶ | use Test::Unit::Debug qw(debug); |
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||
| 18 | 6 | ▶ | use Test::Unit::TestCase; |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 19 | use Test::Unit::Loader; | ||
| 20 | use Test::Unit::Warning; | ||
| 21 | |||
| 22 | =head1 SYNOPSIS | ||
| 23 | |||
| 24 | package MySuite; | ||
| 25 | |||
| 26 | use base qw(Test::Unit::TestSuite); | ||
| 27 | |||
| 28 | sub name { 'My very own test suite' } | ||
| 29 | sub include_tests { qw(MySuite1 MySuite2 MyTestCase1 ...) } | ||
| 30 | |||
| 31 | This is the easiest way of building suites; there are many more. Read on ... | ||
| 32 | |||
| 33 | =head1 DESCRIPTION | ||
| 34 | |||
| 35 | This class provides the functionality for building test suites in | ||
| 36 | several different ways. | ||
| 37 | |||
| 38 | Any module can be a test suite runnable by the framework if it | ||
| 39 | provides a C<suite()> method which returns a C<Test::Unit::TestSuite> | ||
| 40 | object, e.g. | ||
| 41 | |||
| 42 | use Test::Unit::TestSuite; | ||
| 43 | |||
| 44 | # more code here ... | ||
| 45 | |||
| 46 | sub suite { | ||
| 47 | my $class = shift; | ||
| 48 | |||
| 49 | # Create an empty suite. | ||
| 50 | my $suite = Test::Unit::TestSuite->empty_new("A Test Suite"); | ||
| 51 | # Add some tests to it via $suite->add_test() here | ||
| 52 | |||
| 53 | return $suite; | ||
| 54 | } | ||
| 55 | |||
| 56 | This is useful if you want your test suite to be contained in the module | ||
| 57 | it tests, for example. | ||
| 58 | |||
| 59 | Alternatively, you can have "standalone" test suites, which inherit directly | ||
| 60 | from C<Test::Unit::TestSuite>, e.g.: | ||
| 61 | |||
| 62 | package MySuite; | ||
| 63 | |||
| 64 | use base qw(Test::Unit::TestSuite); | ||
| 65 | |||
| 66 | sub new { | ||
| 67 | my $class = shift; | ||
| 68 | my $self = $class->SUPER::empty_new(); | ||
| 69 | # Build your suite here | ||
| 70 | return $self; | ||
| 71 | } | ||
| 72 | |||
| 73 | sub name { 'My very own test suite' } | ||
| 74 | |||
| 75 | or if your C<new()> is going to do nothing more interesting than add | ||
| 76 | tests from other suites and testcases via C<add_test()>, you can use the | ||
| 77 | C<include_tests()> method as shorthand: | ||
| 78 | |||
| 79 | package MySuite; | ||
| 80 | |||
| 81 | use base qw(Test::Unit::TestSuite); | ||
| 82 | |||
| 83 | sub name { 'My very own test suite' } | ||
| 84 | sub include_tests { qw(MySuite1 MySuite2 MyTestCase1 ...) } | ||
| 85 | |||
| 86 | This is the easiest way of building suites. | ||
| 87 | |||
| 88 | =head1 CONSTRUCTORS | ||
| 89 | |||
| 90 | =head2 empty_new ([NAME]) | ||
| 91 | |||
| 92 | my $suite = Test::Unit::TestSuite->empty_new('my suite name'); | ||
| 93 | |||
| 94 | Creates a fresh suite with no tests. | ||
| 95 | |||
| 96 | =cut | ||
| 97 | |||
| 98 | sub empty_new { | ||
| 99 | my $this = shift; | ||
| 100 | my $classname = ref $this || $this; | ||
| 101 | my $name = shift || ''; | ||
| 102 | |||
| 103 | my $self = { | ||
| 104 | _Tests => [], | ||
| 105 | _Name => $name, | ||
| 106 | }; | ||
| 107 | bless $self, $classname; | ||
| 108 | |||
| 109 | debug(ref($self), "::empty_new($name) called\n"); | ||
| 110 | return $self; | ||
| 111 | } | ||
| 112 | |||
| 113 | =head2 new ([ CLASSNAME | TEST ]) | ||
| 114 | |||
| 115 | If a test suite is provided as the argument, it merely returns that | ||
| 116 | suite. If a test case is provided, it extracts all test case methods | ||
| 117 | from the test case (see L<Test::Unit::TestCase/list_tests>) into a new | ||
| 118 | test suite. | ||
| 119 | |||
| 120 | If the class this method is being run in has an C<include_tests> method | ||
| 121 | which returns an array of class names, it will also automatically add | ||
| 122 | the tests from those classes into the newly constructed suite object. | ||
| 123 | |||
| 124 | =cut | ||
| 125 | |||
| 126 | sub new { | ||
| 127 | my $class = shift; | ||
| 128 | my $classname = shift || ''; # Avoid a warning | ||
| 129 | debug("$class\::new($classname) called\n"); | ||
| 130 | |||
| 131 | my $self = $class->empty_new(); | ||
| 132 | |||
| 133 | if ($classname) { | ||
| 134 | Test::Unit::Loader::compile_class($classname); | ||
| 135 | if (eval { $classname->isa('Test::Unit::TestCase') }) { | ||
| 136 | $self->{_Name} = "suite extracted from $classname"; | ||
| 137 | my @testcases = Test::Unit::Loader::extract_testcases($classname); | ||
| 138 | foreach my $testcase (@testcases) { | ||
| 139 | $self->add_test($testcase); | ||
| 140 | } | ||
| 141 | } | ||
| 142 | elsif (eval { $classname->can('suite') }) { | ||
| 143 | return $classname->suite(); | ||
| 144 | } | ||
| 145 | else { | ||
| 146 | my $error = "Class $classname was not a test case or test suite.\n"; | ||
| 147 | #$self->add_warning($error); | ||
| 148 | die $error; | ||
| 149 | } | ||
| 150 | } | ||
| 151 | |||
| 152 | if ($self->can('include_tests')) { | ||
| 153 | foreach my $test ($self->include_tests()) { | ||
| 154 | $self->add_test($test); | ||
| 155 | } | ||
| 156 | } | ||
| 157 | |||
| 158 | return $self; | ||
| 159 | } | ||
| 160 | |||
| 161 | =head1 METHODS | ||
| 162 | |||
| 163 | =cut | ||
| 164 | |||
| 165 | sub suite { | ||
| 166 | my $class = shift; | ||
| 167 | croak "suite() is not an instance method" if ref $class; | ||
| 168 | $class->new(@_); | ||
| 169 | } | ||
| 170 | |||
| 171 | =head2 name() | ||
| 172 | |||
| 173 | Returns the suite's human-readable name. | ||
| 174 | |||
| 175 | =cut | ||
| 176 | |||
| 177 | sub name { | ||
| 178 | my $self = shift; | ||
| 179 | croak "Override name() in subclass to set name\n" if @_; | ||
| 180 | return $self->{_Name}; | ||
| 181 | } | ||
| 182 | |||
| 183 | =head2 names() | ||
| 184 | |||
| 185 | Returns an arrayref of the names of all tests in the suite. | ||
| 186 | |||
| 187 | =cut | ||
| 188 | |||
| 189 | sub names { | ||
| 190 | my $self = shift; | ||
| 191 | my @test_list = @{$self->tests}; | ||
| 192 | return [ map {$_->name} @test_list ] if @test_list; | ||
| 193 | } | ||
| 194 | |||
| 195 | =head2 list (SHOW_TESTCASES) | ||
| 196 | |||
| 197 | Produces a human-readable indented lists of the suite and the subsuites | ||
| 198 | it contains. If the first parameter is true, also lists any testcases | ||
| 199 | contained in the suite and its subsuites. | ||
| 200 | |||
| 201 | =cut | ||
| 202 | |||
| 203 | sub list { | ||
| 204 | my $self = shift; | ||
| 205 | my $show_testcases = shift; | ||
| 206 | my $first = ($self->name() || 'anonymous Test::Unit::TestSuite'); | ||
| 207 | $first .= " - " . ref($self) unless ref($self) eq __PACKAGE__; | ||
| 208 | $first .= "\n"; | ||
| 209 | my @lines = ( $first ); | ||
| 210 | foreach my $test (@{ $self->tests() }) { | ||
| 211 | push @lines, map " $_", @{ $test->list($show_testcases) }; | ||
| 212 | } | ||
| 213 | return \@lines; | ||
| 214 | } | ||
| 215 | |||
| 216 | =head2 add_test (TEST_CLASSNAME | TEST_OBJECT) | ||
| 217 | |||
| 218 | You can add a test object to a suite with this method, by passing | ||
| 219 | either its classname, or the object itself as the argument. | ||
| 220 | |||
| 221 | Of course, there are many ways of getting the object too ... | ||
| 222 | |||
| 223 | # Get and add an existing suite. | ||
| 224 | $suite->add_test('MySuite1'); | ||
| 225 | |||
| 226 | # This is exactly equivalent: | ||
| 227 | $suite->add_test(Test::Unit::TestSuite->new('MySuite1')); | ||
| 228 | |||
| 229 | # So is this, provided MySuite1 inherits from Test::Unit::TestSuite. | ||
| 230 | use MySuite1; | ||
| 231 | $suite->add_test(MySuite1->new()); | ||
| 232 | |||
| 233 | # Extract yet another suite by way of suite() method and add it to | ||
| 234 | # $suite. | ||
| 235 | use MySuite2; | ||
| 236 | $suite->add_test(MySuite2->suite()); | ||
| 237 | |||
| 238 | # Extract test case methods from MyModule::TestCase into a | ||
| 239 | # new suite and add it to $suite. | ||
| 240 | $suite->add_test(Test::Unit::TestSuite->new('MyModule::TestCase')); | ||
| 241 | |||
| 242 | =cut | ||
| 243 | |||
| 244 | sub add_test { | ||
| 245 | my $self = shift; | ||
| 246 | my ($test) = @_; | ||
| 247 | debug('+ ', ref($self), "::add_test($test) called\n"); | ||
| 248 | $test = Test::Unit::Loader::load_test($test) unless ref $test; | ||
| 249 | croak "`$test' could not be interpreted as a Test::Unit::Test object" | ||
| 250 | unless eval { $test->isa('Test::Unit::Test') }; | ||
| 251 | push @{$self->tests}, $test; | ||
| 252 | } | ||
| 253 | |||
| 254 | sub count_test_cases { | ||
| 255 | my $self = shift; | ||
| 256 | my $count; | ||
| 257 | $count += $_->count_test_cases for @{$self->tests}; | ||
| 258 | return $count; | ||
| 259 | } | ||
| 260 | |||
| 261 | sub run { | ||
| 262 | my $self = shift; | ||
| 263 | my ($result, $runner) = @_; | ||
| 264 | |||
| 265 | debug("$self\::run($result, ", $runner || 'undef', ") called\n"); | ||
| 266 | |||
| 267 | $result ||= create_result(); | ||
| 268 | $result->tell_listeners(start_suite => $self); | ||
| 269 | |||
| 270 | $self->add_warning("No tests found in " . $self->name()) | ||
| 271 | unless @{ $self->tests() }; | ||
| 272 | |||
| 273 | for my $t (@{$self->tests()}) { | ||
| 274 | if ($runner && $self->filter_test($runner, $t)) { | ||
| 275 | debug(sprintf "+ skipping '%s'\n", $t->name()); | ||
| 276 | next; | ||
| 277 | } | ||
| 278 | debug(sprintf "+ didn't skip '%s'\n", $t->name()); | ||
| 279 | |||
| 280 | last if $result->should_stop(); | ||
| 281 | $t->run($result, $runner); | ||
| 282 | } | ||
| 283 | |||
| 284 | $result->tell_listeners(end_suite => $self); | ||
| 285 | |||
| 286 | return $result; | ||
| 287 | } | ||
| 288 | |||
| 289 | sub filter_test { | ||
| 290 | my $self = shift; | ||
| 291 | my ($runner, $test) = @_; | ||
| 292 | |||
| 293 | debug(sprintf "checking whether to filter '%s'\n", $test->name); | ||
| 294 | |||
| 295 | my @filter_tokens = $runner->filter(); | ||
| 296 | |||
| 297 | foreach my $token (@filter_tokens) { | ||
| 298 | my $filtered = $test->filter_method($token); | ||
| 299 | debug(" - by token $token? ", $filtered ? 'yes' : 'no', "\n"); | ||
| 300 | return 1 if $filtered; | ||
| 301 | } | ||
| 302 | |||
| 303 | return 0; | ||
| 304 | } | ||
| 305 | |||
| 306 | sub test_at { | ||
| 307 | my $self = shift; | ||
| 308 | my ($index) = @_; | ||
| 309 | return $self->tests()->[$index]; | ||
| 310 | } | ||
| 311 | |||
| 312 | sub test_count { | ||
| 313 | my $self = shift; | ||
| 314 | return scalar @{$self->tests()}; | ||
| 315 | } | ||
| 316 | |||
| 317 | sub tests { | ||
| 318 | my $self = shift; | ||
| 319 | return $self->{_Tests}; | ||
| 320 | } | ||
| 321 | |||
| 322 | sub to_string { | ||
| 323 | my $self = shift; | ||
| 324 | return $self->name(); | ||
| 325 | } | ||
| 326 | |||
| 327 | sub add_warning { | ||
| 328 | my $self = shift; | ||
| 329 | $self->add_test(Test::Unit::Warning->new(join '', @_)); | ||
| 330 | } | ||
| 331 | |||
| 332 | 1; | ||
| 333 | __END__ | ||