NAME

Test::Weaken::ExtraBits -- various extras for Test::Weaken

SYNOPSIS

 use Test::Weaken::ExtraBits;

DESCRIPTION

This is a few helper functions for use with Test::Weaken.

EXPORTS

Nothing is exported by default, but the functions can be requested individually in the usual Exporter style (see Exporter).

    use Test::Weaken::ExtraBits qw(ignore_Class_Singleton);

FUNCTIONS

$io = Test::Weaken::ExtraBits::contents_glob_IO ($ref)

If $ref is a globref then return the contents of its IO slot. This is the underlying Perl I/O of a file handle.

Note that Test::Weaken 3.006 doesn't track IO objects by default so to detect leaks of them add to tracked_types too,

    leaks (constructor => sub { ... },
           contents => \&Test::Weaken::ExtraBits::contents_glob_IO,
           tracked_types => ['IO']);

This is good for detecting an open file leaked through a Perl-level dup (see "open" in perlfunc) even after its original $fh handle is destroyed and freed.

    open my $dupfh, '<', $fh;
    # $dupfh holds and uses *$fh{IO}

Ignores

$bool = Test::Weaken::ExtraBits::ignore_global_functions ($ref)

Return true if $ref is a coderef to a global function like

    sub foo {}

A global function is identified by the $ref having a name and the current function under that name equal to this $ref. Plain functions created as sub foo {} etc work, but redefinitions or function-creating modules like Memoize or constant generally don't.

The name in a coderef is essentially just a string from its original creation. Things like Memoize etc often end up with anonymous functions. constant only ends up with a name in the symtab optimization case.

See Sub::Name to add a name to a coderef, though you probably wouldn't want that merely to make ignore_global_functions() work. (Though a name can help caller() and stack backtraces too.)

$bool = ignore_functions ($ref, $funcname, $funcname, ...)

Return true if $ref is a coderef to any of the given named functions. This is designed for use when making an ignore handler,

    sub my_ignore_callback {
      my ($ref) = @_;
      return (ignore_functions ($ref, 'Foo::Bar::somefunc',
                                      'Quux::anotherfunc')
              || ...);
    }

Each $funcname argument should be a fully-qualified string like Foo::Bar::somefunc. Any functions which doesn't exist are skipped, so it doesn't matter if a particular package is loaded yet, etc.

If you've got coderefs to functions you want to ignore then there's no need for ignore_functions(), just test $ref==$mycoderef etc.

$bool = Test::Weaken::ExtraBits::ignore_Class_Singleton ($ref)

Return true if $ref is the singleton instance object of a class using Class::Singleton. If Class::Singleton is not loaded or not used by the $ref object then return false.

Generally Class::Singleton objects are permanent, existing for the duration of the program. This ignore helps skip them.

The current implementation requires Class::Singleton version 1.04 for its has_instance() method.

$bool = Test::Weaken::ExtraBits::ignore_DBI_globals ($ref)

Return true if $ref is one of the various DBI module global objects.

This is slightly dependent on the DBI implementation but currently means any DBI::dr driver object. A driver object is created permanently for each driver loaded. DBI::db handles (created and destroyed in the usual way) refer to their respective driver object.

A bug in Perl through to at least 5.10.1 related to lvalue substr() means certain scratchpad temporaries holding "ImplementorClass" strings in DBI end up still alive after DBI::db and DBI::st objects have finished with them, looking like leaks, but not. They aren't recognised by ignore_DBI_globals currently. A workaround is to do a dummy DBI::db handle creation to flush out the old scratchpad.

HOME PAGE

http://user42.tuxfamily.org/test-variousbits/index.html

COPYRIGHT

Test-VariousBits is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.

Test-VariousBits is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Test-VariousBits. If not, see http://www.gnu.org/licenses/.