--- name: "Test2::Tools::Mock" section: "3pm" platform: "linux" package: "libtest-simple-perl" version: "1.302210-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Test2::Tools::Mock/3pm" --- # Test2::Tools::Mock(3pm) Class/Instance mocking for Test2. ## 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 \. ## MAINTAINERS - Chad Granum \ ## AUTHORS - Chad Granum \ ## COPYRIGHT Copyright Chad Granum \. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See \