Test::Stream::Plugin::Mock(3)

NAME
Test::Stream::Plugin::Mock - Class/Instance mocking for Test::Stream.

DEPRECATED
This distribution is deprecated in favor of Test2, Test2::Suite, and Test2::Workflow.

See Test::Stream::Manual::ToTest2 for a conversion guide.

DESCRIPTION
Mocking is often an essential part of testing. This library covers some of the most common mocking needs. This plugin is heavily influenced by Mock::Quick, but with an improved API. This plugin is also intended to play well with other plugins in ways Mock::Quick would be unable to.

SYNOPSIS
    my $mock = mock 'Some::Class' => (
        add => [
            new_method => sub { ... },
        ],
        override => [
            replace_method => sub { ... },
        ],
    );

    Some::Class->new_method();        # Calls the newly injected method
    Some::Class->replace_method();    # Calls our replacement method.

    $mock->override(...) # Override some more

    $mock = undef; # Undoes all the mocking, restoring all original methods.

MOCKING + SPEC TESTING
This plugin plays nicely with Test::Stream::Plugin::Spec. Mocks are treated as a "before_each" if you use the mock functions without saving the returned object. The mock will also apply to any describe block in which they are defined.

    describe stuff => sub {
        # The mock specification
        mock 'My::Class' => (...);

        # Mock applies here, inside the describe block

        tests foo => sub {
            # Mock applies here inside any nested blocks, even though they run
            # later
        };
    };

    # Mock does not apply out here

EXPORTS

  DEFAULT

mock
    This is a 1-stop shop function that delgates to one of the other methods depending on how it is used. If you are not comfortable with a function that has a lot of potential behaviors, you can use one of the other functions directly.

$mock = mocked($object)
$mock = mocked($class)
    Check if an object or class is mocked. If it is mocked the $mock object (Test::Stream::Mock) will be returned.

$mock = mock $class => ( ... );
$mock = mock $instance => ( ... )
$mock = mock 'class', $class => ( ... )
    These forms delegate to mock_class() to mock a package. The third form is to be explicit about what type of mocking you want.

$obj = mock()
$obj = mock { ... }
$obj = mock 'obj', ...;
    These forms delegate to mock_obj() to create instances of anonymous packages where methods are vivified into existance as needed.

mock $mock => sub { ... }
mock $method => ( ... )
    These forms go together, the first form will set $mock as the current mock build, then run the sub. Within the sub you can declare mock specifications using the second form. The first form delgates to mock_build().

    The second form calls the specified method on the current build. This second form delgates to mock_do().

  BY REQUEST
DEFINING MOCKS

$obj = mock_obj( ... )
$obj = mock_obj { ... } => ( ... )
$obj = mock_obj sub { ... }
$obj = mock_obj { ... } => sub { ... }
    This method lets you quickly generate a blessed object. The object will be an instance of a randomly generated package name. Methods will vivify as read/write accessors as needed.

    Arguments can be any method available to Test::Stream::Mock followed by an argument. If the very first argument is a hashref then it will be blessed as your new object.

    If you provide a coderef instead of key/value pairs, the coderef will be run to build the mock. (See the "BUILDING MOCKS" section).

$mock = mock_class $class => ( ... )
$mock = mock_class $instance => ( ... )
$mock = mock_class ... => sub { ... }
    This will create a new instance of Test::Stream::Mock to control the package specified. If you give it a blessed reference it will use the class of the instance.

    Arguments can be any method available to Test::Stream::Mock followed by an argument. If the very first argument is a hashref then it will be blessed as your new object.

    If you provide a coderef instead of key/value pairs, the coderef will be run to build the mock. (See the "BUILDING MOCKS" section).

BUILDING MOCKS

mock_build $mock => sub { ... }
    Set $mock as the current build, then run the specified code. $mock will no longer be the current build when the sub is complete.

$mock = mock_building()
    Get the current building $mock object.

mock_do $method => $args
    Run the specified method on the currently building object.

METHOD GENERATORS

$sub = mock_accessor $field
    Generate a read/write accessor for the specified field. This will generate a sub like the following:

        $sub = sub {
            my $self = shift;
            ($self->{$field}) = @_ if @_;
            return $self->{$field};
        };

$sub = mock_getter $field
    Generate a read obly accessor for the specified field. This will generate a sub like the following:

        $sub = sub {
            my $self = shift;
            return $self->{$field};
        };

$sub = mock_setter $field
    Generate a write accessor for the specified field. This will generate a sub like the following:

        $sub = sub {
            my $self = shift;
            ($self->{$field}) = @_;
        };

%pairs = mock_accessors(qw/name1 name2 name3/)
    Generates several read/write accessors at once, returns key/value pairs where the key is the field name, and the value is the coderef.

%pairs = mock_getters(qw/name1 name2 name3/)
    Generates several read only accessors at once, returns key/value pairs where the key is the field name, and the value is the coderef.

%pairs = mock_setters(qw/name1 name2 name3/)
    Generates several write accessors at once, returns key/value pairs where the key is the field name, and the value is the coderef.

MOCK CONTROL OBJECTS
    my $mock = mock(...);

Mock objects are instances of Test::Stream::Mock, see it for their methods.

SOURCE
The source code repository for Test::Stream can be found at http://github.com/Test-More/Test-Stream/.

MAINTAINERS

Chad Granum <exodist@cpan.org>

AUTHORS

Chad Granum <exodist@cpan.org>

COPYRIGHT
Copyright 2015 Chad Granum <exodist7@gmail.com>.

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

See http://dev.perl.org/licenses/