NAME
    Test::SubCalls - Track the number of times subs are called

SYNOPSIS
      use Test::SubCalls;
      
  # Start tracking calls to a named sub
      sub_track( 'Foo::foo' );
      
  # Run some test code
      ...
      
  # Test that some sub deep in the codebase was called
      # a specific number of times.
      sub_calls( 'Foo::foo', 5 );
      sub_calls( 'Foo::foo', 5, 'Use a custom test message' );
      
  # Reset the counts for one or all subs
      sub_reset( 'Foo::foo' );
      sub_reset_all();

DESCRIPTION
    There are a number of different situations (like testing caching code)
    where you want to want to do a number of tests, and then verify that
    some underlying subroutine deep within the code was called a specific
    number of times.

    This module provides a number of functions for doing testing in this way
    in association with your normal Test::More (or similar) test scripts.

FUNCTIONS
    In the nature of test modules, all functions are exported by default.

  sub_track $subname
    The "sub_track" function creates a new call tracker for a named
    function.

    The sub to track must be provided by name, references to the function
    itself are insufficient.

    Returns true if added, or dies on error.

  sub_calls $subname, $expected_calls [, $message ]
    The "sub_calls" function is the primary (and only) testing function
    provided by "Test::SubCalls". A single call will represent one test in
    your plan.

    It takes the subroutine name as originally provided to "sub_track", the
    expected number of times the subroutine should have been called, and an
    optional test message.

    If no message is provided, a default message will be provided for you.

    Test is ok if the number of times the sub has been called matches the
    expected number, or not ok if not.

  sub_reset $subname
    To prevent repeat users from having to take before and after counts when
    they start testing from after zero, the "sub_reset" function has been
    provided to reset a sub call counter to zero.

    Returns true or dies if the sub name is invalid or not currently
    tracked.

  sub_reset_all
    Provided mainly as a convenience, the "sub_reset_all" function will
    reset all the counters currently defined.

    Returns true.

SUPPORT
    Bugs should be submitted via the CPAN bug tracker, located at

    <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-SubCalls>

    For other issues, or commercial enhancement or support, contact the
    author.

AUTHOR
    Adam Kennedy <adamk@cpan.org>

SEE ALSO
    <http://ali.as/>, Test::Builder, Test::More, Hook::LexWrap

COPYRIGHT
    Copyright 2005 - 2009 Adam Kennedy.

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

    The full text of the license can be found in the LICENSE file included
    with this module.

