NAME

Test::Unit - Simple Framework for Unit Testing

SYNOPSIS

  use Test::Unit;

  # the lazy way

  sub test_ok { Test::Unit->assert(1 == 1) };
  sub test_fail { Test::Unit->assert(23 == 42) };
  Test::Unit->create_suite()->run(); 

  # the convenient way to provide test fixture

  my $setup = sub { print STDERR "Creating fixture ...\n" };
  my $teardown = sub { print STDERR "Cleaning up ...\n" };
  Test::Unit->create_suite(setup => $setup, 
                           teardown => $teardown)->run();

  # the detailed way

  my $test_ok = sub { Test::Unit->assert(1 == 1) };
  my $test_fail = sub { Test::Unit->assert(23 == 42) };
  my $testcase_ok = new Test::Unit(name => "Testcase 1",
                                test => $test_ok,
                                setup => $setup,
                                teardown => $teardown,
                                );
  $testcase_ok->run(); 
  my $testcase_fail = new Test::Unit(name => "Testcase 2",
                                test => $test_fail,
                                setup => $setup,
                                teardown => $teardown,
                                );
  $testcase_fail->run();
  $testcase_ok->add($testcase_fail);
  $testcase_ok->run(); 

DESCRIPTION

Test::Unit provides a simple framework for convenient unit testing.

You test a given unit (a script, a module, whatever) by creating a new Test::Unit object and configuring this object with three subroutine references: the test to run, a setup to provide resources you need for the test, and a corresponding teardown of the resources created in the setup routine. You may omit any of these.

You can build trees of test suites by adding Test::Unit objects to each other by calling the add() method. A Test::Unit object will run all tests for all Test::Unit objects added to it.

For convenience, you can automatically build a test suite for a given package by calling Test::Unit->create_suite(). This will build a test case for each subroutine in the package given that has a name starting with "test" and pack them all together into one Test::Unit object for easy testing. If you dont give a package name to Test::Unit->create_suite(), the current package is taken as default.

Test output is one status line (a "." for every successful test run, or an "F" for any failed test run, to indicate progress), one result line ("OK (n tests)" or "!!!FAILURES!!!"), and possibly many lines reporting detailed error messages for any failed tests.

assert()

    Verify if a condition holds. No options. Must be called via
    the package name.

    Example:

    Test::Unit->assert(1 == 1);

new()

    Create new Test::Unit objects. Options are:
    
    name:     A name for the testcase.
    test:     A reference to a subroutine that does the testing
              for the testcase. Will often call Test::Unit->assert().
    setup:    A reference to a subroutine that prepares resources 
              needed for testing. The subroutine will be called for 
              each test case in a suite.
    teardown: A reference to a subroutine that cleans up 
              resources used for testing. The subroutine will be 
              called for each test case in a suite.
    
    Examples:
    
    my $obj = Test::Unit->new(test => $test);

    my $obj = Test::Unit->new(name => $name, 
                              test => $test, 
                              setup => $setup, 
                              teardown => $teardown,
                              );

create_suite()

    Create a new Test::Unit object that contains testcases for all 
    subroutines in the package given that have names starting with
    "test". Options are:
    
    package:  The package to test. Defaults to the current package.
    name:     A name for the testcase.
    test:     A reference to a subroutine that does the testing
              for the testcase. Will often call Test::Unit->assert().
    setup:    A reference to a subroutine that prepares resources 
              needed for testing. The subroutine will be called for 
              each test case in a suite.
    teardown: A reference to a subroutine that cleans up 
              resources used for testing. The subroutine will be 
              called for each test case in a suite.
    
    Examples:
    
    my $obj = Test::Unit->create_suite();
    
    my $obj = Test::Unit->create_suite(package => $pkg,
                                       name => $name, 
                                       test => $test, 
                                       setup => $setup, 
                                       teardown => $teardown,
                                       );

run()

    Call a Test::Unit object to run its tests. No Options.

    Example:
    
    my $obj = Test::Unit->create_suite();
    $obj->run();

add()

    Add a Test::Unit object to the test suite of another Test::Unit
    object. The object that is called with this method will
    perform its own test first, then it will call its children
    to perform their tests. 

    Example:

    my $parent = Test::Unit->create_suite();
    my $child1 = Test::Unit->new(name => "child2", test => $child2_test);
    my $child2 = Test::Unit->new(name => "child2", test => $child2_test);
    $parent->add($child1);
    $parent->add($child2);
    $parent->run(); # will also run $child1 and $child2
    

AUTHOR

Christian Lemburg <lemburg@acm.org>

SEE ALSO

Refactoring. Improving The Design Of Existing Code. Martin Fowler. Addison-Wesley, 1999.

http://www.xProgramming.com/