Test2::Mock(3)		Perl Programmers Reference Guide	  Test2::Mock(3)

NAME
     Test2::Mock - Module for managing mocked classes and instances.

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.

SYNOPSIS
	 use Test2::Mock;
	 use MyClass;

	 my $mock = Test2::Mock->new(
	     track => $BOOL, # enable call tracking if desired
	     class => 'MyClass',
	     override => [
		 name => sub { 'fred' },
		 ...
	     ],
	     add => [
		 is_mocked => sub { 1 }
		 ...
	     ],
	     ...
	 );

	 # Unmock the 'name' sub
	 $mock->restore('name');

	 ...

	 $mock = undef; # Will remove all the mocking

CONSTRUCTION
METHODS
     $mock = Test2::Mock->new(class => $CLASS, ...)
	 This will create a new instance of Test2::Mock that manages mocking for
	 the specified $CLASS.

	 Any "Test2::Mock" 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 add() method:

	     my $mock = Test2::Mock->new(
		 class => 'AClass',
		 add => [foo => sub { 'foo' }],
	     );

	 is identical to this:

	     my $mock = Test2::Mock->new(
		 class => 'AClass',
	     );
	     $mock->add(foo => sub { 'foo' });

     $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 "$mock->tracking".
	 Changing the tracking toggle will not affect subs already altered, but
	 will affect any additional alterations.

     $hashref = $mock->sub_tracking
	 The tracking data looks like this:

	     {
		 sub_name => [
		     {sub_name => $sub_name, sub_ref => $mock_subref, args => [... copy of @_ from the call ... ]},
		     ...,
		     ...,
		 ],
	     }

	 Unlike call_tracking, this lists all calls by sub, so you can choose to
	 only look at the sub specific calls.

	 Please note: The hashref items with the subname and args are shared
	 with call_tracking, modifying one modifies the other, so copy first!

     $arrayref = $mock->call_tracking
	 The tracking data looks like this:

	     [
		 {sub_name => $sub_name, sub_ref => $mock_subref, args => [... copy of @_ from the call ... ]},
		 ...,
		 ...,
	     ]

	 Unlike sub_tracking this lists all calls to any mocked sub, in the or-
	 der they were called. To filter by sub use sub_tracking.

	 Please note: The hashref items with the subname and args are shared
	 with sub_tracking, modifying one modifies the other, so copy first!

     $mock->clear_sub_tracking()
     $mock->clear_sub_tracking(\@subnames)
	 Clear tracking data. With no arguments ALL tracking data is cleared.
	 When arguments are provided then only those specific keys will be
	 cleared.

     $mock->clear_call_tracking()
	 Clear all items from call_tracking.

     $mock->add('symbol' => ..., 'symbol2' => ...)
     $mock->override('symbol1' => ..., 'symbol2' => ...)
     $mock->set('symbol1' => ..., 'symbol2' => ...)
	 add() and override() are the primary ways to add/modify methods for a
	 class. Both accept the exact same type of arguments. The difference is
	 that "override" will fail unless the symbol you are overriding already
	 exists, "add" on the other hand will fail if the symbol does already
	 exist.

	 set() 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.

	 Note: Think of override as a push operation. If you call override on
	 the same symbol multiple times it will track that. You can use re-
	 store() as a pop operation to go back to the previous mock. "reset" can
	 be used to remove all the mocking for a symbol.

	 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:

	     $mock->override(foo => sub { 'overridden foo' });
	     my $val = $class->foo; # Runs our override
	     # $val is now set to 'overridden foo'

	 You can also simply provide a value and it will be wrapped in a sub for
	 you:

	     $mock->override( foo => 'foo' );

	 The example above will generate a sub that always returns the string
	 'foo'.

	 There are three *special* values that can be used to generate acces-
	 sors:

	     $mock->add(
		 name => 'rw',	 # Generates a read/write accessor
		 age  => 'ro',	 # Generates a read only accessor
		 size => 'wo',	 # Generates a write only accessor
	     );

	 If you want to have a sub that actually returns one of the three spe-
	 cial strings, or that returns a coderef, you can use a hashref as the
	 spec:

	     my $ref = sub { 'my sub' };
	     $mock->add(
		 rw_string => { val => 'rw' },
		 ro_string => { val => 'ro' },
		 wo_string => { val => 'wo' },
		 coderef   => { val => $ref }, # the coderef method returns $ref each time
	     );

	 You can also override/add other symbol types, such as hash:

	     package Foo;
	     ...

	     $mock->add('%foo' => {a => 1});

	     print $Foo::foo{a}; # prints '1'

	 You can also tell mock to deduce the symbol type for the add/override
	 from the reference, rules are similar to glob assignments:

	     $mock->add(
		 -foo => sub { 'foo' },	    # Adds the &foo sub to the package
		 -foo => { foo => 1 },	    # Adds the %foo hash to the package
		 -foo => [ 'f', 'o', 'o' ], # Adds the @foo array to the package
		 -foo => \"foo",	    # Adds the $foo scalar to the package
	     );

     $mock->restore($SYMBOL)
	 Restore the symbol to what it was before the last override. If the sym-
	 bol 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 "override" as a push operation, and "restore" as the
	 pop operation.

     $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.

     $mock->orig($SYMBOL)
	 This will return the original symbol, before any mocking. For symbols
	 that were added this will return undef.

     $mock->current($SYMBOL)
	 This will return the current symbol.

     $mock->reset_all
	 Remove all added symbols, and restore all overridden symbols to their
	 originals.

     $mock->add_constructor($NAME => $TYPE)
     $mock->override_constructor($NAME => $TYPE)
	 This can be used to inject constructors. The first argument should be
	 the name of the constructor. The second argument specifies the con-
	 structor type.

	 The "hash" type is the most common, all arguments are used to create a
	 new hash that is blessed.

	     hash => sub  {
		 my ($class, %params) = @_;
		 return bless \%params, $class;
	     };

	 The "array" type is similar to the hash type, but accepts a list in-
	 stead of key/value pairs:

	     array => sub {
		 my ($class, @params) = @_;
		 return bless \@params, $class;
	     };

	 The "ref" type takes a reference and blesses it. This will modify your
	 original input argument.

	     ref => sub {
		 my ($class, $params) = @_;
		 return bless $params, $class;
	     };

	 The "ref_copy" type will copy your reference and bless the copy:

	     ref_copy => sub {
		 my ($class, $params) = @_;
		 my $type = reftype($params);

		 return bless {%$params}, $class
		     if $type eq 'HASH';

		 return bless [@$params], $class
		     if $type eq 'ARRAY';

		 croak "Not sure how to construct a '$class' from '$params'";
	     };

     $mock->before($NAME, sub { ... })
	 This will replace the original sub $NAME 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 un-
	 modified arguments.

     $mock->after($NAME, sub { ... })
	 This is similar to before, except your callback runs after the original
	 code.	The return from your callback is ignored.

     $mock->around($NAME, sub { ... })
	 This gives you the chance to wrap the original sub:

	     $mock->around(foo => sub {
		 my $orig = shift;
		 my $self = shift;
		 my (@args) = @_;

		 ...
		 $self->$orig(@args);
		 ...

		 return ...;
	     });

	 The original sub is passed in as the first argument, even before $self.
	 You are responsible for making sure your wrapper sub returns the cor-
	 rect thing.

     $mock->autoload
	 This will inject an "AUTOLOAD" sub into the class. This autoload will
	 automatically generate read-write accessors for any sub called that
	 does not already exist.

     $mock->block_load
	 This will prevent the real class from loading until the mock is de-
	 stroyed. This will fail if the class is already loaded. This will let
	 you mock a class completely without loading the original module.

     $pm_file = $mock->file
	 This returns the relative path to the file for the module. This corre-
	 sponds to the %INC entry.

     $bool = $mock->purge_on_destroy($bool)
	 When true, this will cause the package stash to be completely obliter-
	 ated when the mock object falls out of scope or is otherwise destroyed.
	 You do not normally want this.

     $stash = $mock->stash
	 This returns the stash for the class being mocked. This is the equiva-
	 lent of:

	     my $stash = \%{"${class}\::"};

	 This saves you from needing to turn off strict.

     $class = $mock->class
	 The class being mocked by this instance.

     $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.

     $c = $mock->child
	 Returns the child mock, if any.

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

MAINTAINERS
     Chad Granum <exodist@cpan.org>

AUTHORS
     Chad Granum <exodist@cpan.org>

COPYRIGHT
     Copyright Chad Granum <exodist@cpan.org>.

     This program is free software; you can redistribute it and/or modify it un-
     der the same terms as Perl itself.

     See <https://dev.perl.org/licenses/>

perl v5.44.0			   2026-06-22			  Test2::Mock(3)