.\" -*- 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::Mock 3perl"
.TH Test2::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::Mock \- Module for managing mocked classes and instances.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module lets you add and override methods for any package temporarily. When
the instance is destroyed it will restore the package to its original state.
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&    use Test2::Mock;
\&    use MyClass;
\&
\&    my $mock = Test2::Mock\->new(
\&        track => $BOOL, # enable call tracking if desired
\&        class => \*(AqMyClass\*(Aq,
\&        override => [
\&            name => sub { \*(Aqfred\*(Aq },
\&            ...
\&        ],
\&        add => [
\&            is_mocked => sub { 1 }
\&            ...
\&        ],
\&        ...
\&    );
\&
\&    # Unmock the \*(Aqname\*(Aq sub
\&    $mock\->restore(\*(Aqname\*(Aq);
\&
\&    ...
\&
\&    $mock = undef; # Will remove all the mocking
.Ve
.SH CONSTRUCTION
.IX Header "CONSTRUCTION"
.SH METHODS
.IX Header "METHODS"
.ie n .IP "$mock = Test2::Mock\->new(class => $CLASS, ...)" 4
.el .IP "\f(CW$mock\fR = Test2::Mock\->new(class => \f(CW$CLASS\fR, ...)" 4
.IX Item "$mock = Test2::Mock->new(class => $CLASS, ...)"
This will create a new instance of Test2::Mock that manages mocking
for the specified \f(CW$CLASS\fR.
.Sp
Any \f(CW\*(C`Test2::Mock\*(C'\fR method can be used as a constructor argument, each
should be followed by an arrayref of arguments to be used within the method. For
instance the \f(CWadd()\fR method:
.Sp
.Vb 4
\&    my $mock = Test2::Mock\->new(
\&        class => \*(AqAClass\*(Aq,
\&        add => [foo => sub { \*(Aqfoo\*(Aq }],
\&    );
.Ve
.Sp
is identical to this:
.Sp
.Vb 4
\&    my $mock = Test2::Mock\->new(
\&        class => \*(AqAClass\*(Aq,
\&    );
\&    $mock\->add(foo => sub { \*(Aqfoo\*(Aq });
.Ve
.ie n .IP $mock\->track($bool) 4
.el .IP \f(CW$mock\fR\->track($bool) 4
.IX Item "$mock->track($bool)"
Turn tracking on or off. Any sub added/overridden/set when tracking is on will
log every call in a hash retrievable via \f(CW\*(C`$mock\->tracking\*(C'\fR. Changing the
tracking toggle will not affect subs already altered, but will affect any
additional alterations.
.ie n .IP "$hashref = $mock\->sub_tracking" 4
.el .IP "\f(CW$hashref\fR = \f(CW$mock\fR\->sub_tracking" 4
.IX Item "$hashref = $mock->sub_tracking"
The tracking data looks like this:
.Sp
.Vb 7
\&    {
\&        sub_name => [
\&            {sub_name => $sub_name, sub_ref => $mock_subref, args => [... copy of @_ from the call ... ]},
\&            ...,
\&            ...,
\&        ],
\&    }
.Ve
.Sp
Unlike call_tracking, this lists all calls by sub, so you can choose to only
look at the sub specific calls.
.Sp
\&\fBPlease note:\fR The hashref items with the subname and args are shared with
call_tracking, modifying one modifies the other, so copy first!
.ie n .IP "$arrayref = $mock\->call_tracking" 4
.el .IP "\f(CW$arrayref\fR = \f(CW$mock\fR\->call_tracking" 4
.IX Item "$arrayref = $mock->call_tracking"
The tracking data looks like this:
.Sp
.Vb 5
\&    [
\&        {sub_name => $sub_name, sub_ref => $mock_subref, args => [... copy of @_ from the call ... ]},
\&        ...,
\&        ...,
\&    ]
.Ve
.Sp
Unlike sub_tracking this lists all calls to any mocked sub, in the order they
were called. To filter by sub use sub_tracking.
.Sp
\&\fBPlease note:\fR The hashref items with the subname and args are shared with
sub_tracking, modifying one modifies the other, so copy first!
.ie n .IP $mock\->\fBclear_sub_tracking()\fR 4
.el .IP \f(CW$mock\fR\->\fBclear_sub_tracking()\fR 4
.IX Item "$mock->clear_sub_tracking()"
.PD 0
.ie n .IP $mock\->clear_sub_tracking(\e@subnames) 4
.el .IP \f(CW$mock\fR\->clear_sub_tracking(\e@subnames) 4
.IX Item "$mock->clear_sub_tracking(@subnames)"
.PD
Clear tracking data. With no arguments ALL tracking data is cleared. When
arguments are provided then only those specific keys will be cleared.
.ie n .IP $mock\->\fBclear_call_tracking()\fR 4
.el .IP \f(CW$mock\fR\->\fBclear_call_tracking()\fR 4
.IX Item "$mock->clear_call_tracking()"
Clear all items from call_tracking.
.ie n .IP "$mock\->add('symbol' => ..., 'symbol2' => ...)" 4
.el .IP "\f(CW$mock\fR\->add('symbol' => ..., 'symbol2' => ...)" 4
.IX Item "$mock->add('symbol' => ..., 'symbol2' => ...)"
.PD 0
.ie n .IP "$mock\->override('symbol1' => ..., 'symbol2' => ...)" 4
.el .IP "\f(CW$mock\fR\->override('symbol1' => ..., 'symbol2' => ...)" 4
.IX Item "$mock->override('symbol1' => ..., 'symbol2' => ...)"
.ie n .IP "$mock\->set('symbol1' => ..., 'symbol2' => ...)" 4
.el .IP "\f(CW$mock\fR\->set('symbol1' => ..., 'symbol2' => ...)" 4
.IX Item "$mock->set('symbol1' => ..., 'symbol2' => ...)"
.PD
\&\f(CWadd()\fR and \f(CWoverride()\fR are the primary ways to add/modify methods for a
class. Both accept the exact same type of arguments. The difference is that
\&\f(CW\*(C`override\*(C'\fR will fail unless the symbol you are overriding already exists,
\&\f(CW\*(C`add\*(C'\fR on the other hand will fail if the symbol does already exist.
.Sp
\&\f(CWset()\fR was more recently added for cases where you may not know if the sub
already exists. These cases are rare, and set should be avoided (think of it
like 'no strict'). However there are valid use cases, so it was added.
.Sp
\&\fBNote:\fR Think of override as a push operation. If you call override on the
same symbol multiple times it will track that. You can use \f(CWrestore()\fR as a
pop operation to go back to the previous mock. \f(CW\*(C`reset\*(C'\fR can be used to remove
all the mocking for a symbol.
.Sp
Arguments must be a symbol name, with optional sigil, followed by a new
specification of the symbol. If no sigil is specified then '&' (sub) is
assumed. A simple example of overriding a sub:
.Sp
.Vb 3
\&    $mock\->override(foo => sub { \*(Aqoverridden foo\*(Aq });
\&    my $val = $class\->foo; # Runs our override
\&    # $val is now set to \*(Aqoverridden foo\*(Aq
.Ve
.Sp
You can also simply provide a value and it will be wrapped in a sub for you:
.Sp
.Vb 1
\&    $mock\->override( foo => \*(Aqfoo\*(Aq );
.Ve
.Sp
The example above will generate a sub that always returns the string 'foo'.
.Sp
There are three *special* values that can be used to generate accessors:
.Sp
.Vb 5
\&    $mock\->add(
\&        name => \*(Aqrw\*(Aq,   # Generates a read/write accessor
\&        age  => \*(Aqro\*(Aq,   # Generates a read only accessor
\&        size => \*(Aqwo\*(Aq,   # Generates a write only accessor
\&    );
.Ve
.Sp
If you want to have a sub that actually returns one of the three special strings, or
that returns a coderef, you can use a hashref as the spec:
.Sp
.Vb 7
\&    my $ref = sub { \*(Aqmy sub\*(Aq };
\&    $mock\->add(
\&        rw_string => { val => \*(Aqrw\*(Aq },
\&        ro_string => { val => \*(Aqro\*(Aq },
\&        wo_string => { val => \*(Aqwo\*(Aq },
\&        coderef   => { val => $ref }, # the coderef method returns $ref each time
\&    );
.Ve
.Sp
You can also override/add other symbol types, such as hash:
.Sp
.Vb 2
\&    package Foo;
\&    ...
\&
\&    $mock\->add(\*(Aq%foo\*(Aq => {a => 1});
\&
\&    print $Foo::foo{a}; # prints \*(Aq1\*(Aq
.Ve
.Sp
You can also tell mock to deduce the symbol type for the add/override from the
reference, rules are similar to glob assignments:
.Sp
.Vb 6
\&    $mock\->add(
\&        \-foo => sub { \*(Aqfoo\*(Aq },     # Adds the &foo sub to the package
\&        \-foo => { foo => 1 },      # Adds the %foo hash to the package
\&        \-foo => [ \*(Aqf\*(Aq, \*(Aqo\*(Aq, \*(Aqo\*(Aq ], # Adds the @foo array to the package
\&        \-foo => \e"foo",            # Adds the $foo scalar to the package
\&    );
.Ve
.ie n .IP $mock\->restore($SYMBOL) 4
.el .IP \f(CW$mock\fR\->restore($SYMBOL) 4
.IX Item "$mock->restore($SYMBOL)"
Restore the symbol to what it was before the last override. If the symbol was
recently added this will remove it. If the symbol has been overridden multiple
times this will ONLY restore it to the previous state. Think of \f(CW\*(C`override\*(C'\fR as a
push operation, and \f(CW\*(C`restore\*(C'\fR as the pop operation.
.ie n .IP $mock\->reset($SYMBOL) 4
.el .IP \f(CW$mock\fR\->reset($SYMBOL) 4
.IX Item "$mock->reset($SYMBOL)"
Remove all mocking of the symbol and restore the original symbol. If the symbol
was initially added then it will be completely removed.
.ie n .IP $mock\->orig($SYMBOL) 4
.el .IP \f(CW$mock\fR\->orig($SYMBOL) 4
.IX Item "$mock->orig($SYMBOL)"
This will return the original symbol, before any mocking. For symbols that were
added this will return undef.
.ie n .IP $mock\->current($SYMBOL) 4
.el .IP \f(CW$mock\fR\->current($SYMBOL) 4
.IX Item "$mock->current($SYMBOL)"
This will return the current symbol.
.ie n .IP $mock\->reset_all 4
.el .IP \f(CW$mock\fR\->reset_all 4
.IX Item "$mock->reset_all"
Remove all added symbols, and restore all overridden symbols to their originals.
.ie n .IP "$mock\->add_constructor($NAME => $TYPE)" 4
.el .IP "\f(CW$mock\fR\->add_constructor($NAME => \f(CW$TYPE\fR)" 4
.IX Item "$mock->add_constructor($NAME => $TYPE)"
.PD 0
.ie n .IP "$mock\->override_constructor($NAME => $TYPE)" 4
.el .IP "\f(CW$mock\fR\->override_constructor($NAME => \f(CW$TYPE\fR)" 4
.IX Item "$mock->override_constructor($NAME => $TYPE)"
.PD
This can be used to inject constructors. The first argument should be the name
of the constructor. The second argument specifies the constructor type.
.Sp
The \f(CW\*(C`hash\*(C'\fR type is the most common, all arguments are used to create a new
hash that is blessed.
.Sp
.Vb 4
\&    hash => sub  {
\&        my ($class, %params) = @_;
\&        return bless \e%params, $class;
\&    };
.Ve
.Sp
The \f(CW\*(C`array\*(C'\fR type is similar to the hash type, but accepts a list instead of
key/value pairs:
.Sp
.Vb 4
\&    array => sub {
\&        my ($class, @params) = @_;
\&        return bless \e@params, $class;
\&    };
.Ve
.Sp
The \f(CW\*(C`ref\*(C'\fR type takes a reference and blesses it. This will modify your
original input argument.
.Sp
.Vb 4
\&    ref => sub {
\&        my ($class, $params) = @_;
\&        return bless $params, $class;
\&    };
.Ve
.Sp
The \f(CW\*(C`ref_copy\*(C'\fR type will copy your reference and bless the copy:
.Sp
.Vb 3
\&    ref_copy => sub {
\&        my ($class, $params) = @_;
\&        my $type = reftype($params);
\&
\&        return bless {%$params}, $class
\&            if $type eq \*(AqHASH\*(Aq;
\&
\&        return bless [@$params], $class
\&            if $type eq \*(AqARRAY\*(Aq;
\&
\&        croak "Not sure how to construct a \*(Aq$class\*(Aq from \*(Aq$params\*(Aq";
\&    };
.Ve
.ie n .IP "$mock\->before($NAME, sub { ... })" 4
.el .IP "\f(CW$mock\fR\->before($NAME, sub { ... })" 4
.IX Item "$mock->before($NAME, sub { ... })"
This will replace the original sub \f(CW$NAME\fR with a new sub that calls your
custom code just before calling the original method. The return from your
custom sub is ignored. Your sub and the original both get the unmodified
arguments.
.ie n .IP "$mock\->after($NAME, sub { ... })" 4
.el .IP "\f(CW$mock\fR\->after($NAME, sub { ... })" 4
.IX Item "$mock->after($NAME, sub { ... })"
This is similar to before, except your callback runs after the original code.
The return from your callback is ignored.
.ie n .IP "$mock\->around($NAME, sub { ... })" 4
.el .IP "\f(CW$mock\fR\->around($NAME, sub { ... })" 4
.IX Item "$mock->around($NAME, sub { ... })"
This gives you the chance to wrap the original sub:
.Sp
.Vb 4
\&    $mock\->around(foo => sub {
\&        my $orig = shift;
\&        my $self = shift;
\&        my (@args) = @_;
\&
\&        ...
\&        $self\->$orig(@args);
\&        ...
\&
\&        return ...;
\&    });
.Ve
.Sp
The original sub is passed in as the first argument, even before \f(CW$self\fR. You
are responsible for making sure your wrapper sub returns the correct thing.
.ie n .IP $mock\->autoload 4
.el .IP \f(CW$mock\fR\->autoload 4
.IX Item "$mock->autoload"
This will inject an \f(CW\*(C`AUTOLOAD\*(C'\fR sub into the class. This autoload will
automatically generate read-write accessors for any sub called that does not
already exist.
.ie n .IP $mock\->block_load 4
.el .IP \f(CW$mock\fR\->block_load 4
.IX Item "$mock->block_load"
This will prevent the real class from loading until the mock is destroyed. This
will fail if the class is already loaded. This will let you mock a class
completely without loading the original module.
.ie n .IP "$pm_file = $mock\->file" 4
.el .IP "\f(CW$pm_file\fR = \f(CW$mock\fR\->file" 4
.IX Item "$pm_file = $mock->file"
This returns the relative path to the file for the module. This corresponds to
the \f(CW%INC\fR entry.
.ie n .IP "$bool = $mock\->purge_on_destroy($bool)" 4
.el .IP "\f(CW$bool\fR = \f(CW$mock\fR\->purge_on_destroy($bool)" 4
.IX Item "$bool = $mock->purge_on_destroy($bool)"
When true, this will cause the package stash to be completely obliterated when
the mock object falls out of scope or is otherwise destroyed. You do not
normally want this.
.ie n .IP "$stash = $mock\->stash" 4
.el .IP "\f(CW$stash\fR = \f(CW$mock\fR\->stash" 4
.IX Item "$stash = $mock->stash"
This returns the stash for the class being mocked. This is the equivalent of:
.Sp
.Vb 1
\&    my $stash = \e%{"${class}\e::"};
.Ve
.Sp
This saves you from needing to turn off strict.
.ie n .IP "$class = $mock\->class" 4
.el .IP "\f(CW$class\fR = \f(CW$mock\fR\->class" 4
.IX Item "$class = $mock->class"
The class being mocked by this instance.
.ie n .IP "$p = $mock\->parent" 4
.el .IP "\f(CW$p\fR = \f(CW$mock\fR\->parent" 4
.IX Item "$p = $mock->parent"
If you mock a class twice the first instance is the parent, the second is the
child. This prevents the parent from being destroyed before the child, which
would lead to a very unpleasant situation.
.ie n .IP "$c = $mock\->child" 4
.el .IP "\f(CW$c\fR = \f(CW$mock\fR\->child" 4
.IX Item "$c = $mock->child"
Returns the child mock, if any.
.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/>