Test::SimpleUnit
                      a simplified unit testing framework

Authors
-------

 Michael Granger <ged@FaerieMUD.org>


General Information
-------------------

Test::SimpleUnit is a simplified unit-testing framework intended to be run on
top of Test::Harness or as a standalone test suite that is easy to create and
maintain, while still providing a modicum of power.

This is a simplified XUnit-style test framework for creating unit tests to be
run either standalone or under Test::Harness.

Tests in Test::SimpleUnit consist of one or more test suites, each of which has
one or more test cases, and setup/teardown functions.

A test suite is an array of test cases which are run, in order, by passing the
array to the runTests() function.  You may wish to split test suites up into
separate files under a "t/" directory so they will run under a
Test::Harness-style "make test".

A test case is a hashref which contains two key-value pairs: a name key with the
name of the test case as the value, and a code reference value under a test
key. If a test case has the name 'setup' or 'teardown', it is added to a list of
functions to be run before or after each test case, respectively. The code
reference value within a setup or teardown test case can optionally be named
"func" instead of "test" for clarity. If there are both "func" and "test"
key-value pairs in a setup or teardown case, the "test" pair is silently
ignored.

Each test case's test function can make one or more assertions by using the
Assertion Functions provided, or can indicate that it or any trailing tests in
the same suite should be skipped by calling one of the provided Skip Functions.


Example
-------

  use Test::SimpleUnit qw{:functions};

  # If a setup function fails, skip the rest of the tests
  Test::SimpleUnit->AutoskipFailedSetup( 1 );

  my $LoadedOkay = 0;
  my $Instance;

  my @tests = (

    # Require the module
    {
      name => 'require',
      test => sub {

        # Make sure we can load the module to be tested.
        assertNoException { require MyClass };

        # Try to import some functions, generating a custom error message if it
        # fails.
        assertNoException { MyClass->import(':myfuncs') } "Failed to import :myfuncs";

        # Make sure calling 'import()' actually imported the functions
        assertRef 'CODE', *::myfunc{CODE};
        assertRef 'CODE', *::myotherfunc{CODE};

        # Set the flag to let setup know everything's loaded
        $LoadedOkay = 1;
      },
    },

    # Setup function (this will be run before any tests which follow)
    {
      name => 'setup',
      test => sub {
        assert $LoadedOkay;
        assertNoException { $Instance = new MyClass };
      },
    },

    # Teardown function (this will be run after any tests which follow)
    {
      name => 'teardown',
      test => sub {
        undef $Instance;
      },
    },

    # Test the do_something method
    {
      name => 'do_something',
      test => sub {
          my $rval;

          assertNoException { $rval = $Instance->do_something };
          assertEquals 'foo', $rval;

          
      },
    },

Caveats
-------

*IMPORTANT*: This is an *beta* release. I have used it extensively for various
projects, but your mileage may vary.

I would greatly appreciate feedback on any aspect of this software. Suggestions,
feature requests, questions, design critiques, and bug reports are most
welcome. Relevant patches are particularly helpful. I may be reached at
<ged@FaerieMUD.org>.


Installation
------------

 perl Makefile.PL
 make
 make test
 make install


== Legal

This module is Open Source Software which is Copyright (c) 2001,2002 by The
FaerieMUD Consortium.

You may use, modify, and/or redistribute this software under the terms of either
the Perl Artistic License or the GNU Public License (version 2 or later),
whichever you prefer.  A copy of the Artistic license should have been included
in this distribution (See the file Artistic). If it was not, a copy of it may be
obtained from http://language.perl.com/misc/Artistic.html or
http://www.faeriemud.org/artistic.html).

THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND
FITNESS FOR A PARTICULAR PURPOSE.


Rev: $Id: README,v 1.3 2002/04/22 22:14:18 deveiant Exp $