.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::SubCalls 3pm" .TH Test::SubCalls 3pm "2022-06-28" "perl v5.34.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::SubCalls \- Track the number of times subs are called .SH "VERSION" .IX Header "VERSION" version 1.10 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Test::SubCalls; \& \& # Start tracking calls to a named sub \& sub_track( \*(AqFoo::foo\*(Aq ); \& \& # Run some test code \& ... \& \& # Test that some sub deep in the codebase was called \& # a specific number of times. \& sub_calls( \*(AqFoo::foo\*(Aq, 5 ); \& sub_calls( \*(AqFoo::foo\*(Aq, 5, \*(AqUse a custom test message\*(Aq ); \& \& # Reset the counts for one or all subs \& sub_reset( \*(AqFoo::foo\*(Aq ); \& sub_reset_all(); .Ve .SH "DESCRIPTION" .IX Header "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. .PP This module provides a number of functions for doing testing in this way in association with your normal Test::More (or similar) test scripts. .SH "FUNCTIONS" .IX Header "FUNCTIONS" In the nature of test modules, all functions are exported by default. .ie n .SS "sub_track $subname" .el .SS "sub_track \f(CW$subname\fP" .IX Subsection "sub_track $subname" The \f(CW\*(C`sub_track\*(C'\fR function creates a new call tracker for a named function. .PP The sub to track must be provided by name, references to the function itself are insufficient. .PP Returns true if added, or dies on error. .ie n .SS "sub_calls $subname, $expected_calls [, $message ]" .el .SS "sub_calls \f(CW$subname\fP, \f(CW$expected_calls\fP [, \f(CW$message\fP ]" .IX Subsection "sub_calls $subname, $expected_calls [, $message ]" The \f(CW\*(C`sub_calls\*(C'\fR function is the primary (and only) testing function provided by \f(CW\*(C`Test::SubCalls\*(C'\fR. A single call will represent one test in your plan. .PP It takes the subroutine name as originally provided to \f(CW\*(C`sub_track\*(C'\fR, the expected number of times the subroutine should have been called, and an optional test message. .PP If no message is provided, a default message will be provided for you. .PP Test is ok if the number of times the sub has been called matches the expected number, or not ok if not. .ie n .SS "sub_reset $subname" .el .SS "sub_reset \f(CW$subname\fP" .IX Subsection "sub_reset $subname" To prevent repeat users from having to take before and after counts when they start testing from after zero, the \f(CW\*(C`sub_reset\*(C'\fR function has been provided to reset a sub call counter to zero. .PP Returns true or dies if the sub name is invalid or not currently tracked. .SS "sub_reset_all" .IX Subsection "sub_reset_all" Provided mainly as a convenience, the \f(CW\*(C`sub_reset_all\*(C'\fR function will reset all the counters currently defined. .PP Returns true. .SH "SUPPORT" .IX Header "SUPPORT" Bugs should be submitted via the \s-1CPAN\s0 bug tracker, located at .PP .PP For other issues, or commercial enhancement or support, contact the author. .SH "AUTHOR" .IX Header "AUTHOR" Adam Kennedy .SH "SEE ALSO" .IX Header "SEE ALSO" , Test::Builder, Test::More, Hook::LexWrap .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2005 \- 2009 Adam Kennedy. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP The full text of the license can be found in the \&\s-1LICENSE\s0 file included with this module.