Test2::Tools::Mock(3)                      User Contributed Perl Documentation


NAME
       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}) = @_;
               };

       %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. See it for their methods.

SOURCE
       The source code repository for Test2-Suite can be found at
       <https://github.com/Test-More/Test2-Suite/>.

MAINTAINERS
       Chad Granum <exodist@cpan.org>

AUTHORS
       Chad Granum <exodist@cpan.org>

COPYRIGHT
       Copyright 2018 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/>

perl v5.38.2                      2024-05-12             Test2::Tools::Mock(3)