Test2::Tools::Mock#

Class/Instance mocking for Test2.

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' => (
    track => $BOOL, # Enable/Disable tracking on subs defined below

    add => [
        new_method => sub { ... },
    ],
    override => [
        replace_method => sub { ... },
    ],
    set => [
        replace_or_inject => sub { ... },
    ],

    track => $bool, # enable/disable tracking again to affect mocks made after this point
    ..., # Argument keys may be repeated
);

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.

my $simple_mock = mock {} => (
    add => [
        is_active => sub { ... }
    ]
);

$simple_mock->is_active();        # Calls our newly mocked method.

EXPORTS#

DEFAULT#

mock

This is a one-stop shop function that delegates 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.
@mocks = mocked($object)
@mocks = mocked($class)

Check if an object or class is mocked. If it is mocked the $mock object(s) (Test2::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 existence 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 delegates to mock_build().

The second form calls the specified method on the current build. This second form delegates 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 Test2::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 Test2::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 Test2::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 only 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}) = @_;
};
```
Generates several read/write accessors at once, returns key/value pairs where the key is the field name, and the value is the coderef.
Generates several read only accessors at once, returns key/value pairs where the key is the field name, and the value is the coderef.
Generates several write accessors at once, returns key/value pairs where the key is the field name, and the value is the coderef.