1Test2::Tools::Mock(3) User Contributed Perl DocumentationTest2::Tools::Mock(3)
2
6 Test2::Tools::Mock - Class/Instance mocking for Test2.
7
9 Mocking is often an essential part of testing. This library covers some
10 of the most common mocking needs. This plugin is heavily influenced by
11 Mock::Quick, but with an improved API. This plugin is also intended to
12 play well with other plugins in ways Mock::Quick would be unable to.
13
15 my $mock = mock 'Some::Class' => (
16 track => $BOOL, # Enable/Disable tracking on subs defined below
17 add => [
19 new_method => sub { ... },
20 ],
21 override => [
22 replace_method => sub { ... },
23 ],
24 set => [
25 replace_or_inject => sub { ... },
26 ],
27 track => $bool, # enable/disable tracking again to affect mocks made after this point
29 ..., # Argument keys may be repeated
30 );
31 Some::Class->new_method(); # Calls the newly injected method
33 Some::Class->replace_method(); # Calls our replacement method.
34 $mock->override(...) # Override some more
36 $mock = undef; # Undoes all the mocking, restoring all original methods.
38 my $simple_mock = mock {} => (
40 add => [
41 is_active => sub { ... }
42 ]
43 );
44 $simple_mock->is_active(); # Calls our newly mocked method.
46
48 DEFAULT
49 mock
50 This is a one-stop shop function that delegates to one of the other
51 methods depending on how it is used. If you are not comfortable
52 with a function that has a lot of potential behaviors, you can use
53 one of the other functions directly.
54 @mocks = mocked($object)
56 @mocks = mocked($class)
57 Check if an object or class is mocked. If it is mocked the $mock
58 object(s) (Test2::Mock) will be returned.
59 $mock = mock $class => ( ... );
61 $mock = mock $instance => ( ... )
62 $mock = mock 'class', $class => ( ... )
63 These forms delegate to mock_class() to mock a package. The third
64 form is to be explicit about what type of mocking you want.
65 $obj = mock()
67 $obj = mock { ... }
68 $obj = mock 'obj', ...;
69 These forms delegate to mock_obj() to create instances of anonymous
70 packages where methods are vivified into existence as needed.
71 mock $mock => sub { ... }
73 mock $method => ( ... )
74 These forms go together, the first form will set $mock as the
75 current mock build, then run the sub. Within the sub you can
76 declare mock specifications using the second form. The first form
77 delegates to mock_build().
78 The second form calls the specified method on the current build.
80 This second form delegates to mock_do().
81 BY REQUEST
83 DEFINING MOCKS
84 $obj = mock_obj( ... )
86 $obj = mock_obj { ... } => ( ... )
87 $obj = mock_obj sub { ... }
88 $obj = mock_obj { ... } => sub { ... }
89 This method lets you quickly generate a blessed object. The object
90 will be an instance of a randomly generated package name. Methods
91 will vivify as read/write accessors as needed.
92 Arguments can be any method available to Test2::Mock followed by an
94 argument. If the very first argument is a hashref then it will be
95 blessed as your new object.
96 If you provide a coderef instead of key/value pairs, the coderef
98 will be run to build the mock. (See the "BUILDING MOCKS" section).
99 $mock = mock_class $class => ( ... )
101 $mock = mock_class $instance => ( ... )
102 $mock = mock_class ... => sub { ... }
103 This will create a new instance of Test2::Mock to control the
104 package specified. If you give it a blessed reference it will use
105 the class of the instance.
106 Arguments can be any method available to Test2::Mock followed by an
108 argument. If the very first argument is a hashref then it will be
109 blessed as your new object.
110 If you provide a coderef instead of key/value pairs, the coderef
112 will be run to build the mock. (See the "BUILDING MOCKS" section).
113 BUILDING MOCKS
115 mock_build $mock => sub { ... }
117 Set $mock as the current build, then run the specified code. $mock
118 will no longer be the current build when the sub is complete.
119 $mock = mock_building()
121 Get the current building $mock object.
122 mock_do $method => $args
124 Run the specified method on the currently building object.
125 METHOD GENERATORS
127 $sub = mock_accessor $field
129 Generate a read/write accessor for the specified field. This will
130 generate a sub like the following:
131 $sub = sub {
133 my $self = shift;
134 ($self->{$field}) = @_ if @_;
135 return $self->{$field};
136 };
137 $sub = mock_getter $field
139 Generate a read only accessor for the specified field. This will
140 generate a sub like the following:
141 $sub = sub {
143 my $self = shift;
144 return $self->{$field};
145 };
146 $sub = mock_setter $field
148 Generate a write accessor for the specified field. This will
149 generate a sub like the following:
150 $sub = sub {
152 my $self = shift;
153 ($self->{$field}) = @_;
154 };
155 %pairs = mock_accessors(qw/name1 name2 name3/)
157 Generates several read/write accessors at once, returns key/value
158 pairs where the key is the field name, and the value is the
159 coderef.
160 %pairs = mock_getters(qw/name1 name2 name3/)
162 Generates several read only accessors at once, returns key/value
163 pairs where the key is the field name, and the value is the
164 coderef.
165 %pairs = mock_setters(qw/name1 name2 name3/)
167 Generates several write accessors at once, returns key/value pairs
168 where the key is the field name, and the value is the coderef.
169
171 my $mock = mock(...);
172 Mock objects are instances of Test2::Mock. See it for their methods.
174
176 The source code repository for Test2-Suite can be found at
177 <https://github.com/Test-More/Test2-Suite/>.
178
180 Chad Granum <exodist@cpan.org>
181
183 Chad Granum <exodist@cpan.org>
184
186 Copyright 2018 Chad Granum <exodist@cpan.org>.
187 This program is free software; you can redistribute it and/or modify it
189 under the same terms as Perl itself.
190 See <https://dev.perl.org/licenses/>
192perl v5.36.0 2023-03-23 Test2::Tools::Mock(3)