# Test::Unit::TestSuite - phpMan

## NAME
    [Test::Unit::TestSuite] - 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]'));

## AUTHOR
    Copyright (c) 2000-2002, 2005 the PerlUnit Development Team (see
    [Test::Unit] or the AUTHORS file included in this distribution).

    All rights reserved. This program is free software; you can redistribute
    it and/or modify it under the same terms as Perl itself.

## SEE ALSO
    *   [Test::Unit::TestRunner]

    *   [Test::Unit::TkTestRunner]

    *   For further examples, take a look at the framework self test
        collection ([t::tlib::AllTests]).