NAME

Test::Mimic - Perl module for automatic package and object mocking via recorded data.

SYNOPSIS

# Mimic the Foo::Bar package with defaults.
use Test::Mimic { 'packages' => { 'Foo::Bar' => {} } };

# Mimic the Foo::Bar package with alternatives.
use Test::Mimic {
    'save'      => '.test_mimic_data',
    'string'    => sub {}, # The sub {} construction simply represents a subroutine reference.
    'destring'  => sub {}, # See below for appropriate contracts.

    'key'           => sub {},
    'monitor_args'  => sub {},
    'play_args'     => sub {},

    'packages'  => {
        'Foo::Bar'  => {
            'scalars'   => [ qw< x y z > ],

            'key'           => sub {},
            'monitor_args'  => sub {},
            'play_args'     => sub {},

            'subs' => {
                'foo' => {
                    'key'           => sub {},
                    'monitor_args'  => sub {},
                    'play_args'     => sub {},
                },
            },
        },
    },
};

DESCRIPTION

Test::Mimic allows one to easily mock a package by first recording its behavior and then playing it back. All that is required is to use Test::Mimic prior to loading the real packages and then run the desired program. The first run will be the recording phase and your program should behave normally. Subsequent runs will use the recorded data to simulate the mimicked packages. This is the playback phase.

Test::Mimic->import($preferences)

The $preferences hash reference passed to import is fairly simply and the majority of its structure can be deduced from the synopsis above. Several of the elements themselves, however, require explanation.

'save' => a directory name where recorded data should be written/read from. The directory need not exist.

'string' => a reference to a subroutine that accepts a single argument and returns it in a stringified form. It should minimally handle non-reference scalars, array references, hash references and references to scalars.

'destring' => a reference to a subroutine that is the inverse of the 'string' subroutine. For example, is_deeply( $x, $preferences->{'destring'}->( $preferences->{'string'}->($x) ) ) from the Test::More module should pass.

'key' => a reference to a subroutine that accepts a reference to an array of arguments and returns a hash key based upon them. It is VITALLY IMPORTANT that you run Test::Mimic::Library::get_id on any argument before examining its state. See the documentation for Test::Mimic::Library for more information.

'monitor_args' => a reference to a subroutine that accepts a reference to an array of arguments and begins recording the desired ones. You will probably want to use Test::Mimic::Library::monitor. Returns a scalar that will later be passed to the subroutine keyed by 'play_args'.

'play_args' => a reference to a subroutine that accepts first a reference to an array of arguments and then the scalar returned by the subroutine keyed by 'monitor_args'. It should hijack the desired arguments. You will probably want to apply the soon to be written Test::Mimic::Library::hijack.

'scalars' => a reference to an array of package scalar names that you wish to record.

'key', 'monitor_args', and 'play_args' can be repeated at several levels of the hash. The most specific one possible will be used in each case. Also, all subroutines, arrays and hashes in a package will be recorded.

EXPORT

Nothing is available for export.

SEE ALSO

Test::MockObject

Other members of the Test::Mimic suite: Test::Mimic::Recorder Test::Mimic::Library Test::Mimic::Generator

The latest source for the Test::Mimic suite is available at:

git://github.com/brendanr/Test--Mimic.git

AUTHOR

Concept by Tye McQueen. Made possible by WhitePages Inc.

Development by Brendan Roof, <brendanroof@gmail.com<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Brendan Roof

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.