man Test::SimpleUnit (3): Simplified Perl unit-testing framework

SYNOPSIS

use Test::SimpleUnit qw{:functions};
runTests(
{name => "test1", test => sub {...}},
{name => "testN", test => sub {...}}
);

EXAMPLE

  use Test::SimpleUnit qw{:functions};
  
  # If a setup or teardown function fails, skip the rest of the tests
  Test::SimpleUnit::AutoskipFailedSetup( 1 );
  Test::SimpleUnit::AutoskipFailedTeardown( 1 );
  
  my $Instance;
  my $RequireWasOkay = 0;
  
  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 the setup function know the module loaded okay
        $RequireWasOkay = 1;
      },
    },
    
    # Setup function (this will be run before any tests which follow)
    {
      name => 'setup',
      test => sub {
        # If the previous test didn't finish, it's untestable, so just skip the
        # rest of the tests
        skipAll "Module failed to load" unless $RequireWasOkay;
        $Instance = new MyClass;
      },
    },
    
    # Teardown function (this will be run after any tests which follow)
    {
      name => 'teardown',
      test => sub {
        undef $Instance;
      },
    },
    
    # Test the connect() and disconnect() methods
    {
      name => 'connect() and disconnect()',
      test => sub {
          my $rval;
          
          assertNoException { $rval = $Instance->connect };
          assert $rval, "Connect failed without error.";
          assertNoException { $Instance->disconnect };
      },
    },
    
    # One-time setup function -- overrides the previous setup, but is
    # immediately discarded after executing once.
    {
      name => 'setup',
      func => sub {
          MyClass::prepNetwork();
      },
    },
    
    # Now override the previous setup function with a new one that does
    # a connect() before each remaining test.
    {
      name => 'setup',
      test => sub {
          $Instance = new MyClass;
          $Instance->connect;
      },
    }
    
    # Same thing for teardown/disconnect()
    {
      name => 'teardown',
      test => sub {
        $Instance->disconnect;
        undef $Instance;
      },
    },
    
    ...
    
  );
  
  runTests( @testSuite );

DESCRIPTION

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

Testing

Testing in Test::SimpleUnit is done by running a test suite, either via 'make test', which uses the Test::Harness 'test' target written by ExtUtils::MakeMaker, or as a standalone script.

If errors occur while running tests via the 'make test' method, you can get more verbose output about the test run by adding "TEST_VERBOSE=1" to the end of the "make" invocation:

  $ make test TEST_VERBOSE=1

If you want to display only the messages caused by failing assertions, you can add a "VERBOSE=1" to the end of the "make" invocation instead:

  $ make test VERBOSE=1

Test Suites

A test suite is one or more test cases, each of which tests a specific unit of functionality.

Test Cases

A test case is a unit of testing which consists of one or more tests, combined with setup and teardown functions that make the necessary preparations for testing.

You may wish to split test cases up into separate files under a "t/" directory so they will run under a Test::Harness-style "make test".

Tests

A test is a hashref which contains two key-value pairs: a name key with the name of the test as the value, and a code reference under a test key:

  {
    name => 'This is the name of the test',
    test => sub { ...testing code... }
  }

Each test'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 test case should be skipped by calling one of the provided Skip Functions.

Setup and Teardown Functions

If a test has the name 'setup' or 'teardown', it is run before or after each test that follows it, respectively. A second or succeeding setup or teardown function will supersede any function of the same type which preceded it. This allows a test designer to change the setup function as the tests progress. See the EXAMPLE section for an example of how to use this.

If a test is preceded by multiple new setup/teardown functions, the last one to be specified is kept, and any others are discarded after being executed once. This allows one to specify one-time setup and/or teardown functions at a given point of testing.

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.

Saving Test Data

If the test suite requires configuration, or some other data which should persist between test cases, it can be dumped via Data::Dumper to a file with the saveTestData() function. In succeeding tests, it can be reloaded using the loadTestData() function.

REQUIRES

Carp, Data::Compare, Data::Dumper, Exporter, Fcntl, IO::File, IO::Handle, Scalar::Util

EXPORTS

Nothing by default.

This module exports several useful assertion functions for the following tags:

:asserts: assert, assertNot, assertDefined, assertUndef, assertNoException, assertException, assertExceptionType, assertExceptionMatches, assertEquals, assertMatches, assertRef, assertNotRef, assertInstanceOf, assertKindOf, fail
:skips: skipOne, skipAll
:testFunctions: runTests
:testdata: loadTestData, saveTestData
:functions: All of the above.

AUTHOR

Michael Granger <[email protected]>

This module is free software. You may use, modify, and/or redistribute this software under the terms of the Perl Artistic License. (See http://language.perl.com/misc/Artistic.html)

FUNCTIONS

AutoskipFailedDataLoad( $trueOrFalse ): If set to a true value, any failure to reload test data via loadTestData() will cause the test to be skipped instead of running.
AutoskipFailedSetup( $trueOrFalse ): If set to a true value, any failed setup functions will cause the test to be skipped instead of running.
AutoskipFailedTeardown( $trueOrFalse ): If set to a true value, any failed teardown functions will cause the test to be skipped instead of running.
Debug( $trueOrFalse ): If set to a true value, the test suite will be dumped to STDERR before running.
OutputHandle( $handle ): Set the handle that will be used to output test progress information. This can be used to run tests under Test::Harness without influencing the test result, such as when invoking runTests() from within an assertion. It defaults to STDOUT, which will be what it is restored to if it is called with no argument. The argument is tested for support for the 'print', 'flush', and 'printf' methods, and dies if it does not support them. This function is mostly to support self-testing.
runTests( @testSuite ): Run the tests in the specified testSuite, generating output appropriate for the harness under which it is running. The testSuite should consist of one or more hashrefs of the following form:

Assertion Functions

assert( $value[, $failureMessage] ): Die with a failure message if the specified value is not true. If the optional failureMessage is not given, one will be generated.
assertDefined( $value[, $failureMessage] ): Die with a failure message if the specified value is undefined. If the optional failureMessage is not given, one will be generated.
assertEquals( $wanted, $tested[, $failureMessage] ): Die with a failure message if the specified wanted value doesn't equal the specified tested value. The comparison is done with Data::Compare, so arbitrarily complex data structures may be compared, as long as they contain no GLOB, CODE, or REF references. If the optional failureMessage is not given, one will be generated.
assertException( \&code[, $failureMessage] ): Evaluate the specified coderef, and die with a failure message if it does not generate an exception. If the optional failureMessage is not given, one will be generated.
assertExceptionMatches( \&code, $regex[, $failureMessage] ): Evaluate the specified coderef, and die with a failure message if it does not generate an exception which matches the specified regex. If the optional failureMessage is not given, one will be generated.
assertExceptionType( \&code, $type[, $failureMessage] ): Evaluate the specified coderef, and die with a failure message if it does not generate an exception which is an object blessed into the specified type or one of its subclasses (ie., the exception must return true to "$exception-"isa($type)>. If the optional failureMessage is not given, one will be generated.
assertInstanceOf( $wantedClass, $testedValue[, $failureMessage] ): Die with a failure message if the specified testedValue is not an instance of the specified wantedClass. If the optional failureMessage is not given, one will be generated.
assertKindOf( $wantedClass, $testedValue[, $failureMessage] ): Die with a failure message if the specified testedValue is not an instance of the specified wantedClass or one of its derivatives. If the optional failureMessage is not given, one will be generated.
assertMatches( $wantedRegexp, $testedValue[, $failureMessage] ): Die with a failure message if the specified tested value doesn't match the specified wanted regular expression. If the optional failureMessage is not given, one will be generated.
assertNoException( \&code[, $failureMessage] ): Evaluate the specified coderef, and die with a failure message if it generates an exception. If the optional failureMessage is not given, one will be generated.
assertNot( $value[, $failureMessage] ): Die with a failure message if the specified value is true. If the optional failureMessage is not given, one will be generated.
assertNotRef( $testedValue[, $failureMessage] ): Die with a failure message if the specified testedValue is a reference of any kind. If the optional failureMessage is not given, one will be generated.
assertRef( $wantedType, $testedValue[, $failureMessage] ): Die with a failure message if the specified testedValue is not of the specified wantedType. The wantedType can either be a ref-type like 'ARRAY' or 'GLOB' or a package name for testing object classes. If the optional failureMessage is not given, one will be generated.
assertUndef( $value[, $failureMessage] ): Die with a failure message if the specified value is defined. If the optional failureMessage is not given, one will be generated.
fail( [$failureMessage] ): Die with a failure message unconditionally. If the optional failureMessage is not given, a generic failure message will be used instead.

Private Functions

_CountAssertion(): Add 1 to the count of assertions run in the current counter frame.
_CountSuccess(): Add 1 to the count of successful assertions in the current counter frame.
_PopAssertionCounter(): Remove the current assertion counter, and return a list of the number of assertions run, and the number of assertions which succeeded.
_PushAssertionCounter(): Add a pair of assertion counters to the stack. Assertion counters are used to count assertion runs/successes, and this adds a level in case of recursive runTests() calls.

Protected Functions

_prepSuite( @tests ): Split the specified array of test hashrefs into three arrays: setupFuncs, tests, and teardownFuncs. Return references to the three arrays.
_runTests( \@setupFuncs, \@tests, \@teardownFuncs ): Run the specified tests, running any setupFuncs before each one, and any teardownFuncs after each one.

Skip Functions

skipAll( [$message] ): Skip all the remaining tests, optionally outputting a message as to why the they were skipped.
skipOne( [$message] ): Skip the rest of this test, optionally outputting a message as to why the rest of the test was skipped.

Test Data Functions

loadTestData( $filename ): Load key/data pairs from a data file that was saved from previous tests. Returns a reference to a hash of data items.
saveTestData( $filename, %datahash ): Save the key/value pairs in %datahash to a file with the specified filename for later loading via loadTestData().