Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::Mock.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::Mock 3pm"
61 .TH Test2::Mock 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::Mock \- Module for managing mocked classes and instances.
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This module lets you add and override methods for any package temporarily. When
71 the instance is destroyed it will restore the package to its original state.
72 .SH SYNOPSIS
73 .IX Header "SYNOPSIS"
74 .Vb 2
75 \& use Test2::Mock;
76 \& use MyClass;
77 \&
78 \& my $mock = Test2::Mock\->new(
79 \& track => $BOOL, # enable call tracking if desired
80 \& class => \*(AqMyClass\*(Aq,
81 \& override => [
82 \& name => sub { \*(Aqfred\*(Aq },
83 \& ...
84 \& ],
85 \& add => [
86 \& is_mocked => sub { 1 }
87 \& ...
88 \& ],
89 \& ...
90 \& );
91 \&
92 \& # Unmock the \*(Aqname\*(Aq sub
93 \& $mock\->restore(\*(Aqname\*(Aq);
94 \&
95 \& ...
96 \&
97 \& $mock = undef; # Will remove all the mocking
98 .Ve
99 .SH CONSTRUCTION
100 .IX Header "CONSTRUCTION"
101 .SH METHODS
102 .IX Header "METHODS"
103 .ie n .IP "$mock = Test2::Mock\->new(class => $CLASS, ...)" 4
104 .el .IP "\f(CW$mock\fR = Test2::Mock\->new(class => \f(CW$CLASS\fR, ...)" 4
105 .IX Item "$mock = Test2::Mock->new(class => $CLASS, ...)"
106 This will create a new instance of Test2::Mock that manages mocking
107 for the specified \f(CW$CLASS\fR.
108 .Sp
109 Any \f(CW\*(C`Test2::Mock\*(C'\fR method can be used as a constructor argument, each
110 should be followed by an arrayref of arguments to be used within the method. For
111 instance the \f(CWadd()\fR method:
112 .Sp
113 .Vb 4
114 \& my $mock = Test2::Mock\->new(
115 \& class => \*(AqAClass\*(Aq,
116 \& add => [foo => sub { \*(Aqfoo\*(Aq }],
117 \& );
118 .Ve
119 .Sp
120 is identical to this:
121 .Sp
122 .Vb 4
123 \& my $mock = Test2::Mock\->new(
124 \& class => \*(AqAClass\*(Aq,
125 \& );
126 \& $mock\->add(foo => sub { \*(Aqfoo\*(Aq });
127 .Ve
128 .ie n .IP $mock\->track($bool) 4
129 .el .IP \f(CW$mock\fR\->track($bool) 4
130 .IX Item "$mock->track($bool)"
131 Turn tracking on or off. Any sub added/overridden/set when tracking is on will
132 log every call in a hash retrievable via \f(CW\*(C`$mock\->tracking\*(C'\fR. Changing the
133 tracking toggle will not affect subs already altered, but will affect any
134 additional alterations.
135 .ie n .IP "$hashref = $mock\->sub_tracking" 4
136 .el .IP "\f(CW$hashref\fR = \f(CW$mock\fR\->sub_tracking" 4
137 .IX Item "$hashref = $mock->sub_tracking"
138 The tracking data looks like this:
139 .Sp
140 .Vb 7
141 \& {
142 \& sub_name => [
143 \& {sub_name => $sub_name, sub_ref => $mock_subref, args => [... copy of @_ from the call ... ]},
144 \& ...,
145 \& ...,
146 \& ],
147 \& }
148 .Ve
149 .Sp
150 Unlike call_tracking, this lists all calls by sub, so you can choose to only
151 look at the sub specific calls.
152 .Sp
153 \&\fBPlease note:\fR The hashref items with the subname and args are shared with
154 call_tracking, modifying one modifies the other, so copy first!
155 .ie n .IP "$arrayref = $mock\->call_tracking" 4
156 .el .IP "\f(CW$arrayref\fR = \f(CW$mock\fR\->call_tracking" 4
157 .IX Item "$arrayref = $mock->call_tracking"
158 The tracking data looks like this:
159 .Sp
160 .Vb 5
161 \& [
162 \& {sub_name => $sub_name, sub_ref => $mock_subref, args => [... copy of @_ from the call ... ]},
163 \& ...,
164 \& ...,
165 \& ]
166 .Ve
167 .Sp
168 Unlike sub_tracking this lists all calls to any mocked sub, in the order they
169 were called. To filter by sub use sub_tracking.
170 .Sp
171 \&\fBPlease note:\fR The hashref items with the subname and args are shared with
172 sub_tracking, modifying one modifies the other, so copy first!
173 .ie n .IP $mock\->\fBclear_sub_tracking()\fR 4
174 .el .IP \f(CW$mock\fR\->\fBclear_sub_tracking()\fR 4
175 .IX Item "$mock->clear_sub_tracking()"
176 .PD 0
177 .ie n .IP $mock\->clear_sub_tracking(\e@subnames) 4
178 .el .IP \f(CW$mock\fR\->clear_sub_tracking(\e@subnames) 4
179 .IX Item "$mock->clear_sub_tracking(@subnames)"
180 .PD
181 Clear tracking data. With no arguments ALL tracking data is cleared. When
182 arguments are provided then only those specific keys will be cleared.
183 .ie n .IP $mock\->\fBclear_call_tracking()\fR 4
184 .el .IP \f(CW$mock\fR\->\fBclear_call_tracking()\fR 4
185 .IX Item "$mock->clear_call_tracking()"
186 Clear all items from call_tracking.
187 .ie n .IP "$mock\->add(\*(Aqsymbol\*(Aq => ..., \*(Aqsymbol2\*(Aq => ...)" 4
188 .el .IP "\f(CW$mock\fR\->add(\*(Aqsymbol\*(Aq => ..., \*(Aqsymbol2\*(Aq => ...)" 4
189 .IX Item "$mock->add('symbol' => ..., 'symbol2' => ...)"
190 .PD 0
191 .ie n .IP "$mock\->override(\*(Aqsymbol1\*(Aq => ..., \*(Aqsymbol2\*(Aq => ...)" 4
192 .el .IP "\f(CW$mock\fR\->override(\*(Aqsymbol1\*(Aq => ..., \*(Aqsymbol2\*(Aq => ...)" 4
193 .IX Item "$mock->override('symbol1' => ..., 'symbol2' => ...)"
194 .ie n .IP "$mock\->set(\*(Aqsymbol1\*(Aq => ..., \*(Aqsymbol2\*(Aq => ...)" 4
195 .el .IP "\f(CW$mock\fR\->set(\*(Aqsymbol1\*(Aq => ..., \*(Aqsymbol2\*(Aq => ...)" 4
196 .IX Item "$mock->set('symbol1' => ..., 'symbol2' => ...)"
197 .PD
198 \&\f(CWadd()\fR and \f(CWoverride()\fR are the primary ways to add/modify methods for a
199 class. Both accept the exact same type of arguments. The difference is that
200 \&\f(CW\*(C`override\*(C'\fR will fail unless the symbol you are overriding already exists,
201 \&\f(CW\*(C`add\*(C'\fR on the other hand will fail if the symbol does already exist.
202 .Sp
203 \&\f(CWset()\fR was more recently added for cases where you may not know if the sub
204 already exists. These cases are rare, and set should be avoided (think of it
205 like \*(Aqno strict\*(Aq). However there are valid use cases, so it was added.
206 .Sp
207 \&\fBNote:\fR Think of override as a push operation. If you call override on the
208 same symbol multiple times it will track that. You can use \f(CWrestore()\fR as a
209 pop operation to go back to the previous mock. \f(CW\*(C`reset\*(C'\fR can be used to remove
210 all the mocking for a symbol.
211 .Sp
212 Arguments must be a symbol name, with optional sigil, followed by a new
213 specification of the symbol. If no sigil is specified then \*(Aq&\*(Aq (sub) is
214 assumed. A simple example of overriding a sub:
215 .Sp
216 .Vb 3
217 \& $mock\->override(foo => sub { \*(Aqoverridden foo\*(Aq });
218 \& my $val = $class\->foo; # Runs our override
219 \& # $val is now set to \*(Aqoverridden foo\*(Aq
220 .Ve
221 .Sp
222 You can also simply provide a value and it will be wrapped in a sub for you:
223 .Sp
224 .Vb 1
225 \& $mock\->override( foo => \*(Aqfoo\*(Aq );
226 .Ve
227 .Sp
228 The example above will generate a sub that always returns the string \*(Aqfoo\*(Aq.
229 .Sp
230 There are three *special* values that can be used to generate accessors:
231 .Sp
232 .Vb 5
233 \& $mock\->add(
234 \& name => \*(Aqrw\*(Aq, # Generates a read/write accessor
235 \& age => \*(Aqro\*(Aq, # Generates a read only accessor
236 \& size => \*(Aqwo\*(Aq, # Generates a write only accessor
237 \& );
238 .Ve
239 .Sp
240 If you want to have a sub that actually returns one of the three special strings, or
241 that returns a coderef, you can use a hashref as the spec:
242 .Sp
243 .Vb 7
244 \& my $ref = sub { \*(Aqmy sub\*(Aq };
245 \& $mock\->add(
246 \& rw_string => { val => \*(Aqrw\*(Aq },
247 \& ro_string => { val => \*(Aqro\*(Aq },
248 \& wo_string => { val => \*(Aqwo\*(Aq },
249 \& coderef => { val => $ref }, # the coderef method returns $ref each time
250 \& );
251 .Ve
252 .Sp
253 You can also override/add other symbol types, such as hash:
254 .Sp
255 .Vb 2
256 \& package Foo;
257 \& ...
258 \&
259 \& $mock\->add(\*(Aq%foo\*(Aq => {a => 1});
260 \&
261 \& print $Foo::foo{a}; # prints \*(Aq1\*(Aq
262 .Ve
263 .Sp
264 You can also tell mock to deduce the symbol type for the add/override from the
265 reference, rules are similar to glob assignments:
266 .Sp
267 .Vb 6
268 \& $mock\->add(
269 \& \-foo => sub { \*(Aqfoo\*(Aq }, # Adds the &foo sub to the package
270 \& \-foo => { foo => 1 }, # Adds the %foo hash to the package
271 \& \-foo => [ \*(Aqf\*(Aq, \*(Aqo\*(Aq, \*(Aqo\*(Aq ], # Adds the @foo array to the package
272 \& \-foo => \e"foo", # Adds the $foo scalar to the package
273 \& );
274 .Ve
275 .ie n .IP $mock\->restore($SYMBOL) 4
276 .el .IP \f(CW$mock\fR\->restore($SYMBOL) 4
277 .IX Item "$mock->restore($SYMBOL)"
278 Restore the symbol to what it was before the last override. If the symbol was
279 recently added this will remove it. If the symbol has been overridden multiple
280 times this will ONLY restore it to the previous state. Think of \f(CW\*(C`override\*(C'\fR as a
281 push operation, and \f(CW\*(C`restore\*(C'\fR as the pop operation.
282 .ie n .IP $mock\->reset($SYMBOL) 4
283 .el .IP \f(CW$mock\fR\->reset($SYMBOL) 4
284 .IX Item "$mock->reset($SYMBOL)"
285 Remove all mocking of the symbol and restore the original symbol. If the symbol
286 was initially added then it will be completely removed.
287 .ie n .IP $mock\->orig($SYMBOL) 4
288 .el .IP \f(CW$mock\fR\->orig($SYMBOL) 4
289 .IX Item "$mock->orig($SYMBOL)"
290 This will return the original symbol, before any mocking. For symbols that were
291 added this will return undef.
292 .ie n .IP $mock\->current($SYMBOL) 4
293 .el .IP \f(CW$mock\fR\->current($SYMBOL) 4
294 .IX Item "$mock->current($SYMBOL)"
295 This will return the current symbol.
296 .ie n .IP $mock\->reset_all 4
297 .el .IP \f(CW$mock\fR\->reset_all 4
298 .IX Item "$mock->reset_all"
299 Remove all added symbols, and restore all overridden symbols to their originals.
300 .ie n .IP "$mock\->add_constructor($NAME => $TYPE)" 4
301 .el .IP "\f(CW$mock\fR\->add_constructor($NAME => \f(CW$TYPE\fR)" 4
302 .IX Item "$mock->add_constructor($NAME => $TYPE)"
303 .PD 0
304 .ie n .IP "$mock\->override_constructor($NAME => $TYPE)" 4
305 .el .IP "\f(CW$mock\fR\->override_constructor($NAME => \f(CW$TYPE\fR)" 4
306 .IX Item "$mock->override_constructor($NAME => $TYPE)"
307 .PD
308 This can be used to inject constructors. The first argument should be the name
309 of the constructor. The second argument specifies the constructor type.
310 .Sp
311 The \f(CW\*(C`hash\*(C'\fR type is the most common, all arguments are used to create a new
312 hash that is blessed.
313 .Sp
314 .Vb 4
315 \& hash => sub {
316 \& my ($class, %params) = @_;
317 \& return bless \e%params, $class;
318 \& };
319 .Ve
320 .Sp
321 The \f(CW\*(C`array\*(C'\fR type is similar to the hash type, but accepts a list instead of
322 key/value pairs:
323 .Sp
324 .Vb 4
325 \& array => sub {
326 \& my ($class, @params) = @_;
327 \& return bless \e@params, $class;
328 \& };
329 .Ve
330 .Sp
331 The \f(CW\*(C`ref\*(C'\fR type takes a reference and blesses it. This will modify your
332 original input argument.
333 .Sp
334 .Vb 4
335 \& ref => sub {
336 \& my ($class, $params) = @_;
337 \& return bless $params, $class;
338 \& };
339 .Ve
340 .Sp
341 The \f(CW\*(C`ref_copy\*(C'\fR type will copy your reference and bless the copy:
342 .Sp
343 .Vb 3
344 \& ref_copy => sub {
345 \& my ($class, $params) = @_;
346 \& my $type = reftype($params);
347 \&
348 \& return bless {%$params}, $class
349 \& if $type eq \*(AqHASH\*(Aq;
350 \&
351 \& return bless [@$params], $class
352 \& if $type eq \*(AqARRAY\*(Aq;
353 \&
354 \& croak "Not sure how to construct a \*(Aq$class\*(Aq from \*(Aq$params\*(Aq";
355 \& };
356 .Ve
357 .ie n .IP "$mock\->before($NAME, sub { ... })" 4
358 .el .IP "\f(CW$mock\fR\->before($NAME, sub { ... })" 4
359 .IX Item "$mock->before($NAME, sub { ... })"
360 This will replace the original sub \f(CW$NAME\fR with a new sub that calls your
361 custom code just before calling the original method. The return from your
362 custom sub is ignored. Your sub and the original both get the unmodified
363 arguments.
364 .ie n .IP "$mock\->after($NAME, sub { ... })" 4
365 .el .IP "\f(CW$mock\fR\->after($NAME, sub { ... })" 4
366 .IX Item "$mock->after($NAME, sub { ... })"
367 This is similar to before, except your callback runs after the original code.
368 The return from your callback is ignored.
369 .ie n .IP "$mock\->around($NAME, sub { ... })" 4
370 .el .IP "\f(CW$mock\fR\->around($NAME, sub { ... })" 4
371 .IX Item "$mock->around($NAME, sub { ... })"
372 This gives you the chance to wrap the original sub:
373 .Sp
374 .Vb 4
375 \& $mock\->around(foo => sub {
376 \& my $orig = shift;
377 \& my $self = shift;
378 \& my (@args) = @_;
379 \&
380 \& ...
381 \& $self\->$orig(@args);
382 \& ...
383 \&
384 \& return ...;
385 \& });
386 .Ve
387 .Sp
388 The original sub is passed in as the first argument, even before \f(CW$self\fR. You
389 are responsible for making sure your wrapper sub returns the correct thing.
390 .ie n .IP $mock\->autoload 4
391 .el .IP \f(CW$mock\fR\->autoload 4
392 .IX Item "$mock->autoload"
393 This will inject an \f(CW\*(C`AUTOLOAD\*(C'\fR sub into the class. This autoload will
394 automatically generate read\-write accessors for any sub called that does not
395 already exist.
396 .ie n .IP $mock\->block_load 4
397 .el .IP \f(CW$mock\fR\->block_load 4
398 .IX Item "$mock->block_load"
399 This will prevent the real class from loading until the mock is destroyed. This
400 will fail if the class is already loaded. This will let you mock a class
401 completely without loading the original module.
402 .ie n .IP "$pm_file = $mock\->file" 4
403 .el .IP "\f(CW$pm_file\fR = \f(CW$mock\fR\->file" 4
404 .IX Item "$pm_file = $mock->file"
405 This returns the relative path to the file for the module. This corresponds to
406 the \f(CW%INC\fR entry.
407 .ie n .IP "$bool = $mock\->purge_on_destroy($bool)" 4
408 .el .IP "\f(CW$bool\fR = \f(CW$mock\fR\->purge_on_destroy($bool)" 4
409 .IX Item "$bool = $mock->purge_on_destroy($bool)"
410 When true, this will cause the package stash to be completely obliterated when
411 the mock object falls out of scope or is otherwise destroyed. You do not
412 normally want this.
413 .ie n .IP "$stash = $mock\->stash" 4
414 .el .IP "\f(CW$stash\fR = \f(CW$mock\fR\->stash" 4
415 .IX Item "$stash = $mock->stash"
416 This returns the stash for the class being mocked. This is the equivalent of:
417 .Sp
418 .Vb 1
419 \& my $stash = \e%{"${class}\e::"};
420 .Ve
421 .Sp
422 This saves you from needing to turn off strict.
423 .ie n .IP "$class = $mock\->class" 4
424 .el .IP "\f(CW$class\fR = \f(CW$mock\fR\->class" 4
425 .IX Item "$class = $mock->class"
426 The class being mocked by this instance.
427 .ie n .IP "$p = $mock\->parent" 4
428 .el .IP "\f(CW$p\fR = \f(CW$mock\fR\->parent" 4
429 .IX Item "$p = $mock->parent"
430 If you mock a class twice the first instance is the parent, the second is the
431 child. This prevents the parent from being destroyed before the child, which
432 would lead to a very unpleasant situation.
433 .ie n .IP "$c = $mock\->child" 4
434 .el .IP "\f(CW$c\fR = \f(CW$mock\fR\->child" 4
435 .IX Item "$c = $mock->child"
436 Returns the child mock, if any.
437 .SH SOURCE
438 .IX Header "SOURCE"
439 The source code repository for Test2\-Suite can be found at
440 <https://github.com/Test\-More/test\-more/>.
441 .SH MAINTAINERS
442 .IX Header "MAINTAINERS"
443 .IP "Chad Granum <[email protected]>" 4
444 .IX Item "Chad Granum <[email protected]>"
445 .SH AUTHORS
446 .IX Header "AUTHORS"
447 .IP "Chad Granum <[email protected]>" 4
448 .IX Item "Chad Granum <[email protected]>"
449 .SH COPYRIGHT
450 .IX Header "COPYRIGHT"
451 Copyright Chad Granum <[email protected]>.
452 .PP
453 This program is free software; you can redistribute it and/or
454 modify it under the same terms as Perl itself.
455 .PP
456 See <https://dev.perl.org/licenses/>