/ 
Test-Wiretap-1.01
River stage zero No dependents
/ Test::Wiretap

NAME

Test-Wiretap - Listen in on a function

SYNOPSIS

use Test::More tests => 3;
use Test::Wiretap;

{
  package InsultOMatic;
  sub insult {
    my ($class, $what) = @_;
    print "$what smells funny.\n";
    return 'stinky';
  }
}

my $tap = Test::Wiretap->new({
  name => 'InsultOMatic::insult',
  before => sub {
    print "Preparing for insult...\n";
  },
  after => sub {
    print "Insult complete!\n";
  },
});

InsultOMatic->insult('Limburger cheese');
# prints:
#  Preparing for insult...
#  Limburger cheese smells funny.
#  Insult complete!

is( $tap->called, 1, "Insulted one thing" );
is_deeply(
  $tap->method_args,
  [['Limburger cheese']],
  "Insulted cheese"
);
is_deeply(
  $tap->return_values,
  [['stinky']],
  "InsultOMatic agrees with me"
);

CONSTRUCTOR

use Test::Wiretap qw(wiretap);
my $tap = wiretap 'package::method', sub { ... }, %args;

is equivalent to:

use Test::Wiretap;
my $rs = Test::Wiretap->new({
  name => 'package::method',
  before => sub { ... },
  %args,
});

%args can contain any of the following named arguments:

name (required)

The name of the function which is to be monitored.

before (optional)

A code reference that will run before the tapped function. This function receives the same @_ as the tapped function does.

after (optional)

A code reference that will run after the tapped function. This function receives three arguments: a reference to the tapped function's argument list, a reference to the tapped function's return-values list, and a third parameter indicating the context in which the tapped function was called.

The third parameter is one of 'list', 'scalar', or 'void'.

That is, if you have: sub foo { map { $_ + 100 } @_ }

my $tap = Test::Wiretap->new({ name => 'main::foo', before => sub { ... }, after => sub { ... }, });

my @list = foo(1, 2, 3);

then the 'before' sub's @_ is (1, 2, 3), and the 'after' sub's @_ is ([1, 2, 3], [101, 102, 103], 'list').

capture (optional)

If true, arguments and return values will be captured. Arguments are available using the args, method_args, named_args, and named_method_args methods. See the Test::Resub documentation for details on those.

Default is not to capture arguments.

deep_copy (optional)

If true, a deep copy of all arguments and return values will be made. Otherwise, a shallow copy will be kept. This is useful if the tapped function modifies receives a reference to a data structure that it modifies, for example.

Default is to deeply copy arguments and return values.

METHODS

called

Returns the number of times the tapped subroutine/method was called. The reset method clears this data.

was_called

Returns the total number of times the tapped subroutine/method was called. This data is not cleared by the reset method.

not_called

Returns true if the tapped subroutine/method was never called. The reset method clears this data.

reset

Clears the called, not_called, return_values, and args data.

args, method_args, named_args, named_method_args

Returns data on how the replaced subroutine/method was invoked. See the Test::Resub documentation for details.

return_values

Returns a list of lists of the return values from the tapped function. Examples:

sub foo { map { $_ + 100 } @_ }

Invocations:                             C<return_values> returns:
----------------------------             -------------------------
  (none)                                   []
  foo(1, 2, 3)                             [[101, 102, 103]]
  foo(5); foo(6, 7)                        [[105], [106, 107]]
return_contexts
sub bar { }

Invocations:                             C<return_contexts> returns:
----------------------------             -------------------------
  foo();                                   ['void']
  $x = foo();                              ['scalar']
  @a = foo();                              ['list']
  $x = foo(); @a = foo(); foo();           ['scalar', 'list', 'void']

AUTHOR

AirWave Wireless, <cpan at airwave.com>

BUGS

Please report any bugs or feature requests to bug-test-wiretap at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Wiretap. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Test::Wiretap

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2008 AirWave Wireless, all rights reserved.

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