NAME
    Test::GlassBox::Heavy - Non-invasive testing of subroutines within Perl
    programs

VERSION
    This document refers to version 0.01 of Test::GlassBox::Heavy

SYNOPSIS
     use Test::GlassBox::Heavy qw(load_subs);
 
     # set up any globals to match those in your Perl program
     my $global = 'foo';
 
     load_subs( $perl_program_file );
     # subs from $perl_program are now available for calling directly
 
     # OR
 
     load_subs( $perl_program_file, $namespace );
     # subs from $perl_program are now available for calling in $namespace

PURPOSE
    You have a (possibly ancient) Perl program for which you'd like to write
    some unit tests. The program code cannot be modified to accommodate
    this, and you want to test subroutines but not actually *run* the
    program. This module takes away the pain of setting up an environment
    for this, so you can run the subroutines in (relative) safety.

DESCRIPTION
    If you have a Perl program to test, one approach is to run the program
    with various command line options and environment settings and observe
    the output. This might be called *black box testing* because you're
    treating the program as an opaque blob.

    Some time later you need to refactor a part of the program, so you want
    to move on and begin unit testing the subroutines in the program. This
    is tricky to do without accidentally running the program itself. At this
    point you're *glass box testing* because you can inspect the internals
    of the program, although you're not actually changing them.

    This module takes a rather heavyweight approach to the above using some
    of Perl's deep magic, such as the "Devel::" and "B::" namespace modules.
    It stops the Perl program from being run, but allows you to call any
    subroutine defined in the program. Essentially it turns the program into
    a package.

    You'll need to set-up any environment the subroutines may need, such as
    global lexical variables, and also be aware that side effects from the
    subroutines will still occur (e.g. database updates).

USAGE
    Load the module like so:

     use Test::GlassBox::Heavy qw(load_subs);

    Then use "load_subs()" to inspect your program and make available the
    subroutines within it. Let's say your program is "/usr/bin/myperlapp".
    The simplest call exports the program's subroutines into your own
    namespace so you can call them directly:

     load_subs( '/usr/bin/myperlapp' );
     # and then...
     $retval = &myperlapp_sub($a,$b);

    If the subroutines happen to use global lexicals in the program, then
    you do need to set these up in your own namespace, otherwise
    "load_subs()" will croak with an error message. Note that they must be
    lexicals - i.e. using "my".

    If you don't want your own namespace polluted, then load the subroutines
    into another namespace:

     load_subs( '/usr/bin/myperlapp', 'Other::Place' );
     # and then...
     $retval = &Other::Place::myperlapp_sub($a,$b);

    Finally, should you want it, you can have the subroutines exported to
    both another namespace and your own, by passing a true value as a third
    argument:

     load_subs( '/usr/bin/myperlapp', 'Other::Place', 1 );

    To be honest I'm not quite sure why I put that feature in.

CAVEATS
    *   You have to call the subroutines with leading "&" to placate strict
        mode.

    *   Warnings are disabled when the program is loaded, although strict
        mode remains on.

    *   You have to create any required global lexicals in your own
        namespace.

BUGS
    Oh, there are probably plenty. I was asked to hack this up for a
    colleague's project, and I've not tested it thoroughly. The module
    certainly uses other modules which have grave warnings about treading on
    Perl's toes with all this deep magic.

    There's another way to do this - much simpler and without needing the
    deep magic modules. "batman" from IRC put this together, here:
    <http://trac.flodhest.net/pm/wiki/ImportSubs>. There are pros and cons
    to both methods.

SEE ALSO
    Code::Splice

REQUIREMENTS
    Other than the standard contents of the Perl distribution, you will
    need:

    Devel::LexAlias
    PadWalker
    Devel::Symdump
    File::Slurp

AUTHOR
    Oliver Gorwits "<oliver.gorwits@oucs.ox.ac.uk>"

ACKNOWLEDGEMENTS
    Some folks on IRC were particularly helpful with suggestions: "batman",
    "mst" and "tomboh". Thanks, guys!

COPYRIGHT & LICENSE
    Copyright (c) The University of Oxford 2008. All Rights Reserved.

    This program is free software; you can redistribute it and/or modify it
    under the terms of version 2 of the GNU General Public License as
    published by the Free Software Foundation.

    This program 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 this program; if not, write to the Free Software Foundation, Inc.,
    51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA