NAME

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

EXPERIMENTAL CODE WARNING

This is an experimental release! Test-Stream, and all its components are still in an experimental phase. This dist has been released to cpan in order to allow testers and early adopters the chance to write experimental new tools with it, or to add experimental support for it into old tools.

PLEASE DO NOT COMPLETELY CONVERT OLD TOOLS YET. This experimental release is very likely to see a lot of code churn. API's may break at any time. Test-Stream should NOT be depended on by any toolchain level tools until the experimental phase is over.

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://www.perl.com/perl/misc/Artistic.html

cpanm Test::Stream

perl -MCPAN -e shell
install Test::Stream