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:

• RT: CPAN's request tracker

  http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Wiretap

• AnnoCPAN: Annotated CPAN documentation

  http://annocpan.org/dist/Test-Wiretap

• CPAN Ratings

  http://cpanratings.perl.org/d/Test-Wiretap

• Search CPAN

  http://search.cpan.org/dist/Test-Wiretap

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.