Test2:...::Mock(3perl)

📦

version 5.44.0 · 8 versions

💖 Test2::Tools::Mock — the `Test2:...::Mock(3perl)` manual, bestie edition ✨

okay so you wanna do some mocking in your tests? say less. this is Test2::Tools::Mock, and it lives in the Perl Programmers Reference Guide, and it is literally here to make your test suite iconic.

🌸 NAME 🌸

Test2::Tools::Mock — Class/Instance mocking for Test2. 💅

🦋 DESCRIPTION 🦋

so, mocking? essential part of testing, no cap. this library covers some of the most common mocking needs you're gonna run into. it's heavily influenced</> by Mock::Quick, except the API got a glow-up. and it's also built to play nice with other plugins in ways that Mock::Quick would simply be unable to. it's giving teamwork, it's giving growth. 🫶

✨ SYNOPSIS ✨

here's the vibe, look:

    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.

yes the argument keys may be repeated. yes that's intentional. periodt. 💅

🎀 EXPORTS 🎀

💜 DEFAULT 💜

mock — this is the one-stop shop function, bestie. it delegates to one of the other methods depending on how you use it. if a function with a lot of potential behaviors makes you nervous, you can always just use one of the other functions directly. no judgment. 🌈
@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 to you. a lil vibe check for your packages. 🔍
$mock = mock $class => ( ... );
$mock = mock $instance => ( ... )
$mock = mock 'class', $class => ( ... ) — these forms delegate to mock_class() to mock a package. the third form exists so you can be explicit about what type of mocking you want. main character energy: state your intentions. 👑
$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. ✨ poof, methods.
mock $mock => sub { ... }
mock $method => ( ... ) — these two go together, ok? 🤝 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. and 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, it's right below, keep scrolling bestie).

$mock = mock_class $class => ( ... )
$mock = mock_class $instance => ( ... )
$mock = mock_class ... => sub { ... } — this creates a new instance of Test2::Mock to control the package you specified. if you hand it a blessed reference, it'll just use the class of the instance. easy. ✨

arguments can be any method available to Test2::Mock followed by an argument. if the very first argument is a hashref, it will be blessed as your new object.

and if you provide a coderef instead of key/value pairs, the coderef runs to build the mock. (again: see BUILDING MOCKS).

🧚 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 once the sub is complete. it had its moment. 🎬
$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. it'll generate a sub like this:

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

$sub = mock_getter $field — generate a read only accessor for the specified field. generated sub looks like:

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

$sub = mock_setter $field — generate a write accessor for the specified field. generated sub looks like:

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

%pairs = mock_accessors(qw/name1 name2 name3/) — generates several read/write accessors at once, and returns key/value pairs where the key is the field name and the value is the coderef. bulk slay. 💅
%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 see that one 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 or whatever. ⭐

🌸 MAINTAINERS 🌸

Chad Granum <exodist@cpan.org>

🎀 AUTHORS 🎀