---
name: "Test::Unit::TestSuite"
section: "3pm"
platform: "linux"
package: "libtest-unit-perl"
version: "0.27-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Test::Unit::TestSuite"
---

# Test::Unit::TestSuite(3pm)

unit testing framework base class

## 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).