man Test::Unit::TestSuite (3): unit testing framework base class

SYNOPSIS

package MySuite;
use base qw(Test::Unit::TestSuite);
sub name { 'My very own test suite' }
sub include_tests { qw(MySuite1 MySuite2 MyTestCase1 ...) }

This is the easiest way of building suites; there are many more. Read on ...

DESCRIPTION

This class provides the functionality for building test suites in several different ways.

Any module can be a test suite runnable by the framework if it provides a "suite()" method which returns a "Test::Unit::TestSuite" object, e.g.

    use Test::Unit::TestSuite;
    # more code here ...
    sub suite {
        my $class = shift;
        # Create an empty suite.
        my $suite = Test::Unit::TestSuite->empty_new("A Test Suite");
        # Add some tests to it via $suite->add_test() here
        return $suite;
    }

This is useful if you want your test suite to be contained in the module it tests, for example.

Alternatively, you can have ``standalone'' test suites, which inherit directly from "Test::Unit::TestSuite", e.g.:

    package MySuite;
    use base qw(Test::Unit::TestSuite);
    sub new {
        my $class = shift;
        my $self = $class->SUPER::empty_new();
        # Build your suite here
        return $self;
    }
    sub name { 'My very own test suite' }

or if your "new()" is going to do nothing more interesting than add tests from other suites and testcases via "add_test()", you can use the "include_tests()" method as shorthand:

    package MySuite;
    use base qw(Test::Unit::TestSuite);
    sub name { 'My very own test suite' } 
    sub include_tests { qw(MySuite1 MySuite2 MyTestCase1 ...) }

This is the easiest way of building suites.

CONSTRUCTORS

empty_new ([NAME])

    my $suite = Test::Unit::TestSuite->empty_new('my suite name');

Creates a fresh suite with no tests.

new ([ CLASSNAME | TEST ])

If a test suite is provided as the argument, it merely returns that suite. If a test case is provided, it extracts all test case methods from the test case (see ``list_tests'' in Test::Unit::TestCase) into a new test suite.

If the class this method is being run in has an "include_tests" method which returns an array of class names, it will also automatically add the tests from those classes into the newly constructed suite object.

METHODS

name()

Returns the suite's human-readable name.

names()

Returns an arrayref of the names of all tests in the suite.

list (SHOW_TESTCASES)

Produces a human-readable indented lists of the suite and the subsuites it contains. If the first parameter is true, also lists any testcases contained in the suite and its subsuites.

add_test (TEST_CLASSNAME | TEST_OBJECT)

You can add a test object to a suite with this method, by passing either its classname, or the object itself as the argument.

Of course, there are many ways of getting the object too ...

    # Get and add an existing suite.
    $suite->add_test('MySuite1');
    # This is exactly equivalent:
    $suite->add_test(Test::Unit::TestSuite->new('MySuite1'));
    # So is this, provided MySuite1 inherits from Test::Unit::TestSuite.
    use MySuite1;
    $suite->add_test(MySuite1->new());
    # Extract yet another suite by way of suite() method and add it to
    # $suite.
    use MySuite2;
    $suite->add_test(MySuite2->suite());
    
    # Extract test case methods from MyModule::TestCase into a
    # new suite and add it to $suite.
    $suite->add_test(Test::Unit::TestSuite->new('MyModule::TestCase'));