<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/Tools/Mock.md. Do not edit. -->

```{index} single: Test2::Tools::Mock
```

# 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](https://metacpan.org/pod/Mock::Quick),
but with an improved API. This plugin is also intended to play well with other
plugins in ways [Mock::Quick](https://metacpan.org/pod/Mock::Quick) would be unable to.

## SYNOPSIS

```perl
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](../Mock.md)) 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](../Mock.md) 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](../Mock.md) 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](../Mock.md) 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:

    ```perl
    $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:

    ```perl
    $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:

    ```perl
    $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

```perl
my $mock = mock(...);
```

Mock objects are instances of [Test2::Mock](../Mock.md). See it for their methods.

## SOURCE

The source code repository for Test2-Suite can be found at
[https://github.com/Test-More/test-more/](https://github.com/Test-More/test-more/).

## MAINTAINERS

- Chad Granum <exodist@cpan.org>

## AUTHORS

- Chad Granum <exodist@cpan.org>

## COPYRIGHT

Copyright Chad Granum <exodist@cpan.org>.

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

See [https://dev.perl.org/licenses/](https://dev.perl.org/licenses/)