.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test2::Tools::Mock 3perl"
.TH Test2::Tools::Mock 3perl 2024-09-01 "perl v5.40.0" "Perl Programmers Reference Guide"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Test2::Tools::Mock \- Class/Instance mocking for Test2.
.SH DESCRIPTION
.IX Header "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.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    my $mock = mock \*(AqSome::Class\*(Aq => (
\&        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.
.Ve
.SH EXPORTS
.IX Header "EXPORTS"
.SS DEFAULT
.IX Subsection "DEFAULT"
.IP mock 4
.IX Item "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.
.ie n .IP "@mocks = mocked($object)" 4
.el .IP "\f(CW@mocks\fR = mocked($object)" 4
.IX Item "@mocks = mocked($object)"
.PD 0
.ie n .IP "@mocks = mocked($class)" 4
.el .IP "\f(CW@mocks\fR = mocked($class)" 4
.IX Item "@mocks = mocked($class)"
.PD
Check if an object or class is mocked. If it is mocked the \f(CW$mock\fR object(s)
(Test2::Mock) will be returned.
.ie n .IP "$mock = mock $class => ( ... );" 4
.el .IP "\f(CW$mock\fR = mock \f(CW$class\fR => ( ... );" 4
.IX Item "$mock = mock $class => ( ... );"
.PD 0
.ie n .IP "$mock = mock $instance => ( ... )" 4
.el .IP "\f(CW$mock\fR = mock \f(CW$instance\fR => ( ... )" 4
.IX Item "$mock = mock $instance => ( ... )"
.ie n .IP "$mock = mock 'class', $class => ( ... )" 4
.el .IP "\f(CW$mock\fR = mock 'class', \f(CW$class\fR => ( ... )" 4
.IX Item "$mock = mock 'class', $class => ( ... )"
.PD
These forms delegate to \f(CWmock_class()\fR to mock a package. The third form is to
be explicit about what type of mocking you want.
.ie n .IP "$obj = \fBmock()\fR" 4
.el .IP "\f(CW$obj\fR = \fBmock()\fR" 4
.IX Item "$obj = mock()"
.PD 0
.ie n .IP "$obj = mock { ... }" 4
.el .IP "\f(CW$obj\fR = mock { ... }" 4
.IX Item "$obj = mock { ... }"
.ie n .IP "$obj = mock 'obj', ...;" 4
.el .IP "\f(CW$obj\fR = mock 'obj', ...;" 4
.IX Item "$obj = mock 'obj', ...;"
.PD
These forms delegate to \f(CWmock_obj()\fR to create instances of anonymous packages
where methods are vivified into existence as needed.
.ie n .IP "mock $mock => sub { ... }" 4
.el .IP "mock \f(CW$mock\fR => sub { ... }" 4
.IX Item "mock $mock => sub { ... }"
.PD 0
.ie n .IP "mock $method => ( ... )" 4
.el .IP "mock \f(CW$method\fR => ( ... )" 4
.IX Item "mock $method => ( ... )"
.PD
These forms go together, the first form will set \f(CW$mock\fR 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 \f(CWmock_build()\fR.
.Sp
The second form calls the specified method on the current build. This second
form delegates to \f(CWmock_do()\fR.
.SS "BY REQUEST"
.IX Subsection "BY REQUEST"
\fIDEFINING MOCKS\fR
.IX Subsection "DEFINING MOCKS"
.ie n .IP "$obj = mock_obj( ... )" 4
.el .IP "\f(CW$obj\fR = mock_obj( ... )" 4
.IX Item "$obj = mock_obj( ... )"
.PD 0
.ie n .IP "$obj = mock_obj { ... } => ( ... )" 4
.el .IP "\f(CW$obj\fR = mock_obj { ... } => ( ... )" 4
.IX Item "$obj = mock_obj { ... } => ( ... )"
.ie n .IP "$obj = mock_obj sub { ... }" 4
.el .IP "\f(CW$obj\fR = mock_obj sub { ... }" 4
.IX Item "$obj = mock_obj sub { ... }"
.ie n .IP "$obj = mock_obj { ... } => sub { ... }" 4
.el .IP "\f(CW$obj\fR = mock_obj { ... } => sub { ... }" 4
.IX Item "$obj = mock_obj { ... } => sub { ... }"
.PD
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.
.Sp
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.
.Sp
If you provide a coderef instead of key/value pairs, the coderef will be run to
build the mock. (See the "BUILDING MOCKS" section).
.ie n .IP "$mock = mock_class $class => ( ... )" 4
.el .IP "\f(CW$mock\fR = mock_class \f(CW$class\fR => ( ... )" 4
.IX Item "$mock = mock_class $class => ( ... )"
.PD 0
.ie n .IP "$mock = mock_class $instance => ( ... )" 4
.el .IP "\f(CW$mock\fR = mock_class \f(CW$instance\fR => ( ... )" 4
.IX Item "$mock = mock_class $instance => ( ... )"
.ie n .IP "$mock = mock_class ... => sub { ... }" 4
.el .IP "\f(CW$mock\fR = mock_class ... => sub { ... }" 4
.IX Item "$mock = mock_class ... => sub { ... }"
.PD
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.
.Sp
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.
.Sp
If you provide a coderef instead of key/value pairs, the coderef will be run to
build the mock. (See the "BUILDING MOCKS" section).
.PP
\fIBUILDING MOCKS\fR
.IX Subsection "BUILDING MOCKS"
.ie n .IP "mock_build $mock => sub { ... }" 4
.el .IP "mock_build \f(CW$mock\fR => sub { ... }" 4
.IX Item "mock_build $mock => sub { ... }"
Set \f(CW$mock\fR as the current build, then run the specified code. \f(CW$mock\fR will
no longer be the current build when the sub is complete.
.ie n .IP "$mock = \fBmock_building()\fR" 4
.el .IP "\f(CW$mock\fR = \fBmock_building()\fR" 4
.IX Item "$mock = mock_building()"
Get the current building \f(CW$mock\fR object.
.ie n .IP "mock_do $method => $args" 4
.el .IP "mock_do \f(CW$method\fR => \f(CW$args\fR" 4
.IX Item "mock_do $method => $args"
Run the specified method on the currently building object.
.PP
\fIMETHOD GENERATORS\fR
.IX Subsection "METHOD GENERATORS"
.ie n .IP "$sub = mock_accessor $field" 4
.el .IP "\f(CW$sub\fR = mock_accessor \f(CW$field\fR" 4
.IX Item "$sub = mock_accessor $field"
Generate a read/write accessor for the specified field. This will generate a sub like the following:
.Sp
.Vb 5
\&    $sub = sub {
\&        my $self = shift;
\&        ($self\->{$field}) = @_ if @_;
\&        return $self\->{$field};
\&    };
.Ve
.ie n .IP "$sub = mock_getter $field" 4
.el .IP "\f(CW$sub\fR = mock_getter \f(CW$field\fR" 4
.IX Item "$sub = mock_getter $field"
Generate a read only accessor for the specified field. This will generate a sub like the following:
.Sp
.Vb 4
\&    $sub = sub {
\&        my $self = shift;
\&        return $self\->{$field};
\&    };
.Ve
.ie n .IP "$sub = mock_setter $field" 4
.el .IP "\f(CW$sub\fR = mock_setter \f(CW$field\fR" 4
.IX Item "$sub = mock_setter $field"
Generate a write accessor for the specified field. This will generate a sub like the following:
.Sp
.Vb 4
\&    $sub = sub {
\&        my $self = shift;
\&        ($self\->{$field}) = @_;
\&    };
.Ve
.ie n .IP "%pairs = mock_accessors(qw/name1 name2 name3/)" 4
.el .IP "\f(CW%pairs\fR = mock_accessors(qw/name1 name2 name3/)" 4
.IX Item "%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.
.ie n .IP "%pairs = mock_getters(qw/name1 name2 name3/)" 4
.el .IP "\f(CW%pairs\fR = mock_getters(qw/name1 name2 name3/)" 4
.IX Item "%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.
.ie n .IP "%pairs = mock_setters(qw/name1 name2 name3/)" 4
.el .IP "\f(CW%pairs\fR = mock_setters(qw/name1 name2 name3/)" 4
.IX Item "%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.
.SH "MOCK CONTROL OBJECTS"
.IX Header "MOCK CONTROL OBJECTS"
.Vb 1
\&    my $mock = mock(...);
.Ve
.PP
Mock objects are instances of Test2::Mock. See it for their methods.
.SH SOURCE
.IX Header "SOURCE"
The source code repository for Test2\-Suite can be found at
<https://github.com/Test\-More/Test2\-Suite/>.
.SH MAINTAINERS
.IX Header "MAINTAINERS"
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.SH AUTHORS
.IX Header "AUTHORS"
.PD 0
.IP "Chad Granum <exodist@cpan.org>" 4
.IX Item "Chad Granum <exodist@cpan.org>"
.PD
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2018 Chad Granum <exodist@cpan.org>.
.PP
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.PP
See <https://dev.perl.org/licenses/>