Test::SubCalls(3) User Contributed Perl Documentation Test::SubCalls(3)

# [NAME](#NAME)

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

# [SYNOPSIS](#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](#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](#FUNCTIONS)

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

## [sub\_track $subname](#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 \]](#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](#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](#sub_reset_all)

Provided mainly as a convenience, the "sub\_reset\_all" function will reset all the counters currently defined.

Returns true.

# [SUPPORT](#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](#AUTHOR)

Adam Kennedy <adamk@cpan.org>

# [SEE ALSO](#SEE_ALSO)

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

# [COPYRIGHT](#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.

2026-06-30 perl v5.42.2

---

Document: Test::SubCalls(3pm) from perl-test-subcalls 1.10-r4 (Chainguard OS)
Source: https://github.com/karenetheridge/Test-SubCalls