Test2::Tools::Mock(3)

📦 version 1.302214, in opensuse-leap 16.0

💅 Test2::Tools::Mock — the mocking page (from the `Test2::Tools::Mock(3)` perl manual) 🎀

okay so bestie, welcome to Test2::Tools::Mock — class/instance mocking for Test2, and honestly it's giving main character energy for your test suite ✨

🌸 DESCRIPTION 🌸

Mocking is lowkey an essential part of testing, fr fr. This library covers some of the most common mocking needs and it's heavily influenced by Mock::Quick — but with an improved API, periodt. It's also designed to play nice with other plugins in ways Mock::Quick literally couldn't. 🫶

✨ 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 — okay so this is the one-stop shop function, and it delegates to one of the other methods depending on how you use it. If you're not comfy with a function that has a lot of potential behaviors (it's giving multitudes 💀), you can always use one of the other functions directly. no pressure bestie.
@mocks = mocked($object) and @mocks = mocked($class) — check if an object or class is mocked 🕵️‍♀️. If it is mocked, you get the $mock object(s) (Test2::Mock) returned. slay.
$mock = mock $class => ( ... );, $mock = mock $instance => ( ... ), and $mock = mock 'class', $class => ( ... ) — these forms delegate to mock_class() to mock a package. That third form is for when you wanna be explicit about what type of mocking you want 👑
$obj = mock(), $obj = mock { ... }, and $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 { ... } and mock $method => ( ... ) — these two go together 🫶. The first form sets $mock as the current mock build, then runs the sub. Inside 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 { ... }, and $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 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 => ( ... ), and $mock = mock_class ... => sub { ... } — this creates a new instance of Test2::Mock to control the package specified. If you give it a blessed reference it'll 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. clean ✨
$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 generates 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 generates 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 generates 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 Test2::Mock — go check that page for their methods, iykyk 💅

🌟 SOURCE 🌟

The source code repository for Test2-Suite can be found at <https://github.com/Test-More/test-more/>. go star it bestie ⭐

💖 MAINTAINERS 💖

Chad Granum <exodist@cpan.org>

🦋 AUTHORS 🦋