Debian Codegraph @

upstream/debian-unstable/man3/Test2::Tools::Mock.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (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 .\"
57 .IX Title "Test2::Tools::Mock 3perl"
58 .TH Test2::Tools::Mock 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Test2::Tools::Mock \- Class/Instance mocking for Test2.
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 Mocking is often an essential part of testing. This library covers some of the
68 most common mocking needs. This plugin is heavily influenced by Mock::Quick,
69 but with an improved API. This plugin is also intended to play well with other
70 plugins in ways Mock::Quick would be unable to.
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 2
74 \& my $mock = mock \*(AqSome::Class\*(Aq => (
75 \& track => $BOOL, # Enable/Disable tracking on subs defined below
76 \&
77 \& add => [
78 \& new_method => sub { ... },
79 \& ],
80 \& override => [
81 \& replace_method => sub { ... },
82 \& ],
83 \& set => [
84 \& replace_or_inject => sub { ... },
85 \& ],
86 \&
87 \& track => $bool, # enable/disable tracking again to affect mocks made after this point
88 \& ..., # Argument keys may be repeated
89 \& );
90 \&
91 \& Some::Class\->new_method(); # Calls the newly injected method
92 \& Some::Class\->replace_method(); # Calls our replacement method.
93 \&
94 \& $mock\->override(...) # Override some more
95 \&
96 \& $mock = undef; # Undoes all the mocking, restoring all original methods.
97 \&
98 \& my $simple_mock = mock {} => (
99 \& add => [
100 \& is_active => sub { ... }
101 \& ]
102 \& );
103 \&
104 \& $simple_mock\->is_active(); # Calls our newly mocked method.
105 .Ve
106 .SH EXPORTS
107 .IX Header "EXPORTS"
108 .SS DEFAULT
109 .IX Subsection "DEFAULT"
110 .IP mock 4
111 .IX Item "mock"
112 This is a one-stop shop function that delegates to one of the other methods
113 depending on how it is used. If you are not comfortable with a function that
114 has a lot of potential behaviors, you can use one of the other functions
115 directly.
116 .ie n .IP "@mocks = mocked($object)" 4
117 .el .IP "\f(CW@mocks\fR = mocked($object)" 4
118 .IX Item "@mocks = mocked($object)"
119 .PD 0
120 .ie n .IP "@mocks = mocked($class)" 4
121 .el .IP "\f(CW@mocks\fR = mocked($class)" 4
122 .IX Item "@mocks = mocked($class)"
123 .PD
124 Check if an object or class is mocked. If it is mocked the \f(CW$mock\fR object(s)
125 (Test2::Mock) will be returned.
126 .ie n .IP "$mock = mock $class => ( ... );" 4
127 .el .IP "\f(CW$mock\fR = mock \f(CW$class\fR => ( ... );" 4
128 .IX Item "$mock = mock $class => ( ... );"
129 .PD 0
130 .ie n .IP "$mock = mock $instance => ( ... )" 4
131 .el .IP "\f(CW$mock\fR = mock \f(CW$instance\fR => ( ... )" 4
132 .IX Item "$mock = mock $instance => ( ... )"
133 .ie n .IP "$mock = mock 'class', $class => ( ... )" 4
134 .el .IP "\f(CW$mock\fR = mock 'class', \f(CW$class\fR => ( ... )" 4
135 .IX Item "$mock = mock 'class', $class => ( ... )"
136 .PD
137 These forms delegate to \f(CWmock_class()\fR to mock a package. The third form is to
138 be explicit about what type of mocking you want.
139 .ie n .IP "$obj = \fBmock()\fR" 4
140 .el .IP "\f(CW$obj\fR = \fBmock()\fR" 4
141 .IX Item "$obj = mock()"
142 .PD 0
143 .ie n .IP "$obj = mock { ... }" 4
144 .el .IP "\f(CW$obj\fR = mock { ... }" 4
145 .IX Item "$obj = mock { ... }"
146 .ie n .IP "$obj = mock 'obj', ...;" 4
147 .el .IP "\f(CW$obj\fR = mock 'obj', ...;" 4
148 .IX Item "$obj = mock 'obj', ...;"
149 .PD
150 These forms delegate to \f(CWmock_obj()\fR to create instances of anonymous packages
151 where methods are vivified into existence as needed.
152 .ie n .IP "mock $mock => sub { ... }" 4
153 .el .IP "mock \f(CW$mock\fR => sub { ... }" 4
154 .IX Item "mock $mock => sub { ... }"
155 .PD 0
156 .ie n .IP "mock $method => ( ... )" 4
157 .el .IP "mock \f(CW$method\fR => ( ... )" 4
158 .IX Item "mock $method => ( ... )"
159 .PD
160 These forms go together, the first form will set \f(CW$mock\fR as the current mock
161 build, then run the sub. Within the sub you can declare mock specifications
162 using the second form. The first form delegates to \f(CWmock_build()\fR.
163 .Sp
164 The second form calls the specified method on the current build. This second
165 form delegates to \f(CWmock_do()\fR.
166 .SS "BY REQUEST"
167 .IX Subsection "BY REQUEST"
168 \fIDEFINING MOCKS\fR
169 .IX Subsection "DEFINING MOCKS"
170 .ie n .IP "$obj = mock_obj( ... )" 4
171 .el .IP "\f(CW$obj\fR = mock_obj( ... )" 4
172 .IX Item "$obj = mock_obj( ... )"
173 .PD 0
174 .ie n .IP "$obj = mock_obj { ... } => ( ... )" 4
175 .el .IP "\f(CW$obj\fR = mock_obj { ... } => ( ... )" 4
176 .IX Item "$obj = mock_obj { ... } => ( ... )"
177 .ie n .IP "$obj = mock_obj sub { ... }" 4
178 .el .IP "\f(CW$obj\fR = mock_obj sub { ... }" 4
179 .IX Item "$obj = mock_obj sub { ... }"
180 .ie n .IP "$obj = mock_obj { ... } => sub { ... }" 4
181 .el .IP "\f(CW$obj\fR = mock_obj { ... } => sub { ... }" 4
182 .IX Item "$obj = mock_obj { ... } => sub { ... }"
183 .PD
184 This method lets you quickly generate a blessed object. The object will be an
185 instance of a randomly generated package name. Methods will vivify as
186 read/write accessors as needed.
187 .Sp
188 Arguments can be any method available to Test2::Mock followed by an
189 argument. If the very first argument is a hashref then it will be blessed as
190 your new object.
191 .Sp
192 If you provide a coderef instead of key/value pairs, the coderef will be run to
193 build the mock. (See the "BUILDING MOCKS" section).
194 .ie n .IP "$mock = mock_class $class => ( ... )" 4
195 .el .IP "\f(CW$mock\fR = mock_class \f(CW$class\fR => ( ... )" 4
196 .IX Item "$mock = mock_class $class => ( ... )"
197 .PD 0
198 .ie n .IP "$mock = mock_class $instance => ( ... )" 4
199 .el .IP "\f(CW$mock\fR = mock_class \f(CW$instance\fR => ( ... )" 4
200 .IX Item "$mock = mock_class $instance => ( ... )"
201 .ie n .IP "$mock = mock_class ... => sub { ... }" 4
202 .el .IP "\f(CW$mock\fR = mock_class ... => sub { ... }" 4
203 .IX Item "$mock = mock_class ... => sub { ... }"
204 .PD
205 This will create a new instance of Test2::Mock to control the package
206 specified. If you give it a blessed reference it will use the class of the
207 instance.
208 .Sp
209 Arguments can be any method available to Test2::Mock followed by an
210 argument. If the very first argument is a hashref then it will be blessed as
211 your new object.
212 .Sp
213 If you provide a coderef instead of key/value pairs, the coderef will be run to
214 build the mock. (See the "BUILDING MOCKS" section).
215 .PP
216 \fIBUILDING MOCKS\fR
217 .IX Subsection "BUILDING MOCKS"
218 .ie n .IP "mock_build $mock => sub { ... }" 4
219 .el .IP "mock_build \f(CW$mock\fR => sub { ... }" 4
220 .IX Item "mock_build $mock => sub { ... }"
221 Set \f(CW$mock\fR as the current build, then run the specified code. \f(CW$mock\fR will
222 no longer be the current build when the sub is complete.
223 .ie n .IP "$mock = \fBmock_building()\fR" 4
224 .el .IP "\f(CW$mock\fR = \fBmock_building()\fR" 4
225 .IX Item "$mock = mock_building()"
226 Get the current building \f(CW$mock\fR object.
227 .ie n .IP "mock_do $method => $args" 4
228 .el .IP "mock_do \f(CW$method\fR => \f(CW$args\fR" 4
229 .IX Item "mock_do $method => $args"
230 Run the specified method on the currently building object.
231 .PP
232 \fIMETHOD GENERATORS\fR
233 .IX Subsection "METHOD GENERATORS"
234 .ie n .IP "$sub = mock_accessor $field" 4
235 .el .IP "\f(CW$sub\fR = mock_accessor \f(CW$field\fR" 4
236 .IX Item "$sub = mock_accessor $field"
237 Generate a read/write accessor for the specified field. This will generate a sub like the following:
238 .Sp
239 .Vb 5
240 \& $sub = sub {
241 \& my $self = shift;
242 \& ($self\->{$field}) = @_ if @_;
243 \& return $self\->{$field};
244 \& };
245 .Ve
246 .ie n .IP "$sub = mock_getter $field" 4
247 .el .IP "\f(CW$sub\fR = mock_getter \f(CW$field\fR" 4
248 .IX Item "$sub = mock_getter $field"
249 Generate a read only accessor for the specified field. This will generate a sub like the following:
250 .Sp
251 .Vb 4
252 \& $sub = sub {
253 \& my $self = shift;
254 \& return $self\->{$field};
255 \& };
256 .Ve
257 .ie n .IP "$sub = mock_setter $field" 4
258 .el .IP "\f(CW$sub\fR = mock_setter \f(CW$field\fR" 4
259 .IX Item "$sub = mock_setter $field"
260 Generate a write accessor for the specified field. This will generate a sub like the following:
261 .Sp
262 .Vb 4
263 \& $sub = sub {
264 \& my $self = shift;
265 \& ($self\->{$field}) = @_;
266 \& };
267 .Ve
268 .ie n .IP "%pairs = mock_accessors(qw/name1 name2 name3/)" 4
269 .el .IP "\f(CW%pairs\fR = mock_accessors(qw/name1 name2 name3/)" 4
270 .IX Item "%pairs = mock_accessors(qw/name1 name2 name3/)"
271 Generates several read/write accessors at once, returns key/value pairs where
272 the key is the field name, and the value is the coderef.
273 .ie n .IP "%pairs = mock_getters(qw/name1 name2 name3/)" 4
274 .el .IP "\f(CW%pairs\fR = mock_getters(qw/name1 name2 name3/)" 4
275 .IX Item "%pairs = mock_getters(qw/name1 name2 name3/)"
276 Generates several read only accessors at once, returns key/value pairs where
277 the key is the field name, and the value is the coderef.
278 .ie n .IP "%pairs = mock_setters(qw/name1 name2 name3/)" 4
279 .el .IP "\f(CW%pairs\fR = mock_setters(qw/name1 name2 name3/)" 4
280 .IX Item "%pairs = mock_setters(qw/name1 name2 name3/)"
281 Generates several write accessors at once, returns key/value pairs where the
282 key is the field name, and the value is the coderef.
283 .SH "MOCK CONTROL OBJECTS"
284 .IX Header "MOCK CONTROL OBJECTS"
285 .Vb 1
286 \& my $mock = mock(...);
287 .Ve
288 .PP
289 Mock objects are instances of Test2::Mock. See it for their methods.
290 .SH SOURCE
291 .IX Header "SOURCE"
292 The source code repository for Test2\-Suite can be found at
293 <https://github.com/Test\-More/Test2\-Suite/>.
294 .SH MAINTAINERS
295 .IX Header "MAINTAINERS"
296 .IP "Chad Granum <[email protected]>" 4
297 .IX Item "Chad Granum <[email protected]>"
298 .SH AUTHORS
299 .IX Header "AUTHORS"
300 .PD 0
301 .IP "Chad Granum <[email protected]>" 4
302 .IX Item "Chad Granum <[email protected]>"
303 .PD
304 .SH COPYRIGHT
305 .IX Header "COPYRIGHT"
306 Copyright 2018 Chad Granum <[email protected]>.
307 .PP
308 This program is free software; you can redistribute it and/or
309 modify it under the same terms as Perl itself.
310 .PP
311 See <https://dev.perl.org/licenses/>