Debian Codegraph @

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