blib/lib/Test/MockModule.pm

filter: Statementstmt 98.6% 297 / 301 Branchbran 92.9% 158 / 170 Conditioncond 84.6% 55 / 65 MC/DCmcdc 73.6% 28 / 38 Subroutinesub 97.6% 41 / 42 Podpod 100% 15 / 15 totaltotal 94.1% 594 / 631 CC 117 SCAR 22.2
CC
117
Cov
95%
_mock
24.0
unmock
13.1
new
13.0
CRAP 9.2
↑ Summary
1 package Test::MockModule;
2 28 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 28 ▶use strict qw/subs vars/;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 28 ▶use vars qw/$VERSION/;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 28 ▶use Scalar::Util qw/reftype refaddr weaken/;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 28 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 28 ▶use SUPER;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 # This is now auto-updated at release time by the github action
9 28 $VERSION = '0.185.3';
10  
11 28 our $GLOBAL_STRICT_MODE;
12  
13 37 ▶sub import {
Subroutine import: called CC=6 SCAR=17.9
14 37 my ( $class, @args ) = @_;
15  
16 # default if no args
17 37 $^H{'Test::MockModule/STRICT_MODE'} = 0;
18  
19 37 foreach my $arg (@args) {
20 13 ▶ if($arg eq 'global-strict' ) {
Branch: 3 branches
BranchTrueFalseTotal
if ($arg eq 'global-strict') { } 1 12 13
elsif ($arg eq 'strict') { } 4 8 12
elsif ($arg eq 'nostrict') { } 4 4 8
21 1 $GLOBAL_STRICT_MODE=1;
22 1 $^H{'Test::MockModule/STRICT_MODE'} = 1;
23 }
24 elsif ( $arg eq 'strict' ) {
25 4 $^H{'Test::MockModule/STRICT_MODE'} = 1;
26 } elsif ( $arg eq 'nostrict' ) {
27 4 ▶ $GLOBAL_STRICT_MODE && die "use Test::MockModule qw(nostrict) is illegal when GLOBAL_STRICT_MODE is being enforced";
Branch: 1 branch
BranchTrueFalseTotal
$Test::MockModule::GLOBAL_STRICT_MODE and die "use Test::MockModule qw(nostrict) is illegal when GLOBAL_STRICT_MODE is being enforced" 1 3 4
28 3 $^H{'Test::MockModule/STRICT_MODE'} = 0;
29 } else {
30 4 carp "Test::MockModule unknown import option '$arg'";
31 }
32 }
33 36 return;
34 }
35  
36 135 ▶sub _strict_mode {
Subroutine _strict_mode: called CC=6 SCAR=18.0
37 135 my $depth = 0;
38 135 ▶ while(my @fields = caller($depth++)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my(@fields) = caller $depth++) 269 19 288
39 269 my $hints = $fields[10];
40 269 ▶ if($hints && exists $hints->{'Test::MockModule/STRICT_MODE'}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($hints and exists $hints->{"Test::MockModule/STRICT_MODE"}) 116 153 269
Condition66%2/3
$hints and exists $hints->{"Test::MockModule/STRICT_MODE"}
!ll&&!rl&&r
1530116
MC/DC50%1/2
$hints and exists $hints->{"Test::MockModule/STRICT_MODE"}
$hints exists $hints->{"Test::MockModule/STRICT_MODE"}
Truth table66%2/3
A and B
A= $hintsB= exists $hints->{"Test::MockModule/STRICT_MODE"}
ABresult
0X0
100
111
41 116 ▶ $GLOBAL_STRICT_MODE && !$hints->{'Test::MockModule/STRICT_MODE'} && die "use Test::MockModule qw(nostrict) is illegal when GLOBAL_STRICT_MODE is being enforced";
Branch: 1 branch
BranchTrueFalseTotal
$Test::MockModule::GLOBAL_STRICT_MODE and not $hints->{"Test::MockModule/STRICT_MODE"} and die "use Test::MockModule qw(nostrict) is illegal when GLOBAL_STRICT_MODE is being enforced" 1 115 116
Condition66%2/3
$Test::MockModule::GLOBAL_STRICT_MODE and not $hints->{"Test::MockModule/STRICT_MODE"}
!ll&&!rl&&r
11501
MC/DC50%1/2
$Test::MockModule::GLOBAL_STRICT_MODE and not $hints->{"Test::MockModule/STRICT_MODE"}
$Test::MockModule::GLOBAL_STRICT_MODE not $hints->{"Test::MockModule/STRICT_MODE"}
Truth table66%2/3
A and not(B)
A= $Test::MockModule::GLOBAL_STRICT_MODEB= not $hints->{"Test::MockModule/STRICT_MODE"}
ABresult
0X0
100
111
42  
43 115 return $hints->{'Test::MockModule/STRICT_MODE'};
44 }
45 }
46 19 return 0;
47 }
48  
49 # Per-sub stack of live mock layers. Each entry:
50 # { id, orig, installed, is_meta, meta_orig }
51 #
52 # id = refaddr of the mock object owning the layer.
53 # orig = coderef at *Pkg::sub immediately before this layer was pushed
54 # (or undef if no sub existed). On mid-stack unmock, the popped
55 # entry's orig cascades down to the next layer so the eventual
56 # stack-empty restore sees the right "pre-mock" state.
57 # installed = coderef this layer most recently installed. Updated on
58 # re-mock by the same object so that an above-layer unmock,
59 # or a mid-stack splice, can re-install the latest coderef.
60 # is_meta = true if this layer was pushed while the package's metaclass
61 # was mutable (Moose Class::MOP::Class or Mouse::Meta::Class).
62 # Drives whether unmock restores via meta->add_method or via
63 # the symbol table.
64 # meta_orig = Method object (or undef) returned by $meta->get_method($name)
65 # immediately before this layer was pushed; only meaningful
66 # when is_meta is true. Cascaded on mid-stack unmock the same
67 # way as orig, so the bottom-of-stack restore can use the
68 # correct pre-any-mock meta state.
69 28 my %mock_subs;
70  
71 # Per-package weak registry: keeps the singleton-per-package behavior
72 # that was the default prior to v0.181 (and the documented contract for
73 # the `$mock->original` from-inside-closure pattern). new() returns
74 # the existing object for a package if one is alive; weak ref so a
75 # cleanly-destroyed mock releases the slot naturally. Pass
76 # `distinct => 1` to opt out and get a fresh object per call (the
77 # v0.181+ GH #48 behavior).
78 my %singleton;
79  
80 145 ▶sub new {
Subroutine new: called CC=13 SCAR=25.7
Pod documented
81 145 my ($class, $package, %args) = @_;
82  
83 145 ▶ croak "Cannot mock $package" if $package && $class && $package eq $class;
Branch: 1 branch
BranchTrueFalseTotal
if $package and $class and $package eq $class 1 144 145
Condition83%5/6
$package and $class and $package eq $class
!ll&&!rl&&r
11431
$package and $class
!ll&&!rl&&r
10144
MC/DC66%2/3
$package and $class and $package eq $class
$package $class $package eq $class
Truth table75%3/4
A and B and C
A= $packageB= $classC= $package eq $class
ABCresult
0XX0
10X0
1100
1111
84 144 ▶ unless (_valid_package($package)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (_valid_package($package)) 2 142 144
85 2 ▶ $package = 'undef' unless defined $package;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $package 1 1 2
86 2 croak "Invalid package name $package";
87 }
88  
89 # Auto-load the package BEFORE consulting the singleton cache.
90 # Otherwise a singleton seeded by an earlier `no_auto => 1` caller
91 # would silently deny later default-mode callers the module load
92 # they expect from `new()` (Koan-Bot review on PR #85).
93 142 ▶ unless ($package eq "CORE::GLOBAL" || $package eq 'main' || $args{no_auto} || ${"$package\::VERSION"}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($package eq "CORE::GLOBAL" or $package eq "main" or $args{"no_auto"} or ${"${package}::VERSION";}) 51 91 142
Condition100%9/9
$package eq "CORE::GLOBAL" or $package eq "main" or $args{"no_auto"} or ${"${package}::VERSION";}
l!l&&r!l&&!r
345751
$package eq "CORE::GLOBAL" or $package eq "main" or $args{"no_auto"}
l!l&&r!l&&!r
232108
$package eq "CORE::GLOBAL" or $package eq "main"
l!l&&r!l&&!r
11140
MC/DC100%4/4
$package eq "CORE::GLOBAL" or $package eq "main" or $args{"no_auto"} or ${"${package}::VERSION";}
$package eq "CORE::GLOBAL" $package eq "main" $args{"no_auto"} ${"${package}::VERSION";}
Truth table100%5/5
A or B or C or D
A= $package eq "CORE::GLOBAL"B= $package eq "main"C= $args{"no_auto"}D= ${"${package}::VERSION";}
ABCDresult
1XXX1
01XX1
001X1
00011
00000
94 51 (my $load_package = "$package.pm") =~ s{::}{/}g;
95 51 TRACE("$package is empty, loading $load_package");
96 51 require $load_package;
97 }
98  
99 141 ▶ if (!$args{distinct} && $singleton{$package}) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $args{"distinct"} and $singleton{$package}) 11 130 141
Condition100%3/3
not $args{"distinct"} and $singleton{$package}
!ll&&!rl&&r
696111
MC/DC100%2/2
not $args{"distinct"} and $singleton{$package}
not $args{"distinct"} $singleton{$package}
Truth table100%3/3
not(A) and B
A= not $args{"distinct"}B= $singleton{$package}
ABresult
0X0
100
111
100 11 TRACE("Reusing singleton MockModule object for $package");
101 11 return $singleton{$package};
102 }
103  
104 130 TRACE("Creating MockModule object for $package");
105 130 my $self = bless {
106 _package => $package,
107 _mocked => {},
108 }, $class;
109  
110 130 ▶ if (!$args{distinct}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($args{"distinct"}) 61 69 130
111 61 $singleton{$package} = $self;
112 61 weaken($singleton{$package});
113 }
114  
115 130 return $self;
116 }
117  
118 130 ▶sub DESTROY {
Subroutine DESTROY: called CC=1 SCAR=0.0
119 130 my $self = shift;
120 130 $self->unmock_all;
121 }
122  
123 3 ▶sub get_package {
Subroutine get_package: called CC=1 SCAR=0.0
Pod documented
124 3 my $self = shift;
125 3 return $self->{_package};
126 }
127  
128 19 ▶sub redefine {
Subroutine redefine: called CC=6 SCAR=18.0
Pod documented
129 19 my ($self, @mocks) = (@_);
130  
131 19 my @mocks_copy = @mocks;
132 19 ▶ while ( my ($name, $value) = splice @mocks_copy, 0, 2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@mocks_copy, 0, 2)) 19 15 34
133 19 my $sub_name = $self->_full_name($name);
134 19 my $coderef = *{$sub_name}{'CODE'};
135 19 ▶ next if 'CODE' eq ref $coderef;
Branch: 1 branch
BranchTrueFalseTotal
if "CODE" eq ref $coderef 13 6 19
136  
137 6 ▶ if ( $sub_name =~ qr{^(.+)::([^:]+)$} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sub_name =~ qr/^(.+)::([^:]+)$/) 6 0 6
138 6 my ( $pkg, $sub ) = ( $1, $2 );
139 6 ▶ next if $pkg->can( $sub );
Branch: 1 branch
BranchTrueFalseTotal
if $pkg->can($sub) 2 4 6
140 }
141  
142 4 ▶ if ('CODE' ne ref $coderef) {
Branch: 1 branch
BranchTrueFalseTotal
if ("CODE" ne ref $coderef) 4 0 4
143 4 croak "$sub_name does not exist!";
144 }
145 }
146  
147 15 return $self->_mock(@mocks);
148 }
149  
150 9 ▶sub define {
Subroutine define: called CC=4 SCAR=13.9
Pod documented
151 9 my ($self, @mocks) = @_;
152  
153 9 my @mocks_copy = @mocks;
154 9 ▶ while ( my ($name, $value) = splice @mocks_copy, 0, 2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@mocks_copy, 0, 2)) 9 7 16
155 9 my $sub_name = $self->_full_name($name);
156 9 my $coderef = *{$sub_name}{'CODE'};
157  
158 9 ▶ if ('CODE' eq ref $coderef) {
Branch: 1 branch
BranchTrueFalseTotal
if ("CODE" eq ref $coderef) 2 7 9
159 2 croak "$sub_name exists!";
160 }
161 }
162  
163 7 my $ret = $self->_mock(@mocks);
164  
165 # Mark defined subs so _mock() can update _orig on redefine (GH #64)
166 7 ▶ while ( my ($name, $value) = splice @mocks, 0, 2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@mocks, 0, 2)) 7 7 14
167 7 $self->{_defined}{$name} = 1;
168 }
169  
170 7 return $ret;
171 }
172  
173 119 ▶sub mock {
Subroutine mock: called CC=2 SCAR=6.9
Pod documented
174 119 my ($self, @mocks) = @_;
175  
176 119 ▶ croak "mock is not allowed in strict mode. Please use define or redefine" if $self->_strict_mode();
Branch: 1 branch
BranchTrueFalseTotal
if $self->_strict_mode 3 115 118
177  
178 115 return $self->_mock(@mocks);
179 }
180  
181 150 ▶sub _mock {
Subroutine _mock: called CC=24 SCAR=31.8
182 150 my $self = shift;
183  
184 # Lazily load Class::MOP::Method once if the target is a Moose class.
185 # Class::MOP is already loaded transitively whenever the target uses Moose,
186 # so this require is essentially a hash-lookup; we still hoist it out of
187 # the per-name install loop for clarity.
188 {
189 150 my $meta = _meta_for($self->{_package});
190 150 ▶ require Class::MOP::Method if $meta && $meta->isa('Class::MOP::Class');
Branch: 1 branch
BranchTrueFalseTotal
if $meta and $meta->isa("Class::MOP::Class") 25 125 150
Condition100%3/3
$meta and $meta->isa("Class::MOP::Class")
!ll&&!rl&&r
1081725
MC/DC100%2/2
$meta and $meta->isa("Class::MOP::Class")
$meta $meta->isa("Class::MOP::Class")
Truth table100%3/3
A and B
A= $metaB= $meta->isa("Class::MOP::Class")
ABresult
0X0
100
111
191 }
192  
193 150 ▶ while (my ($name, $value) = splice @_, 0, 2) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = splice(@_, 0, 2)) 177 149 326
194 177 ▶ my $code = sub { };
Subroutine __ANON__: called CC=1 SCAR=0.0
195 177 ▶ if (ref $value && reftype $value eq 'CODE') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $value and builtin::reftype($value) eq 'CODE') { } 156 21 177
elsif (defined $value) { } 19 2 21
Condition100%3/3
ref $value and builtin::reftype($value) eq "CODE"
!ll&&!rl&&r
201156
MC/DC100%2/2
ref $value and builtin::reftype($value) eq "CODE"
ref $value builtin::reftype($value) eq "CODE"
Truth table100%3/3
A and B
A= ref $valueB= builtin::reftype($value) eq "CODE"
ABresult
0X0
100
111
196 156 $code = $value;
197 } elsif (defined $value) {
198 19 ▶ $code = sub {$value};
Subroutine __ANON__: called CC=1 SCAR=0.0
199 }
200  
201 177 TRACE("$name: $code");
202 177 ▶ croak "Invalid subroutine name: $name" unless _valid_subname($name);
Branch: 1 branch
BranchTrueFalseTotal
unless _valid_subname($name) 1 176 177
203 176 my $sub_name = _full_name($self, $name);
204 176 my $meta = _meta_for($self->{_package});
205 176 ▶ my $can_meta = $meta && !$meta->is_immutable;
Condition100%3/3
$meta && !$meta->is_immutable
!ll&&!rl&&r
134339
MC/DC100%2/2
$meta && !$meta->is_immutable
$meta !$meta->is_immutable
Truth table100%3/3
A && not(B)
A= $metaB= !$meta->is_immutable
ABresult
0X0
100
111
206  
207 176 ▶ if (!$self->{_mocked}{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $self->{'_mocked'}{$name}) { } 153 23 176
208 153 TRACE("Storing existing $sub_name");
209 153 $self->{_mocked}{$name} = 1;
210 153 ▶ my $orig = defined &{$sub_name} ? \&$sub_name : undef;
Branch: 1 branch
BranchTrueFalseTotal
defined &{$sub_name;} ? : 133 20 153
211 153 $self->{_orig}{$name} = $orig;
212 # get_method() can return an empty list (rather than undef) for
213 # methods that aren't locally defined; force scalar context so
214 # the anonymous hash gets exactly one value here.
215 153 ▶ my $meta_orig = $can_meta ? scalar $meta->get_method($name) : undef;
Branch: 1 branch
BranchTrueFalseTotal
$can_meta ? : 36 117 153
216 153 ▶ $mock_subs{$sub_name} ||= [];
Condition100%2/2
$mock_subs{$sub_name} ||= []
l!l
26127
MC/DC100%1/1
$mock_subs{$sub_name} ||= []
$mock_subs{$sub_name}
Truth table100%2/2
A
A= $mock_subs{$sub_name}
Aresult
11
00
217 153 ▶ push @{$mock_subs{$sub_name}}, {
Branch: 1 branch
BranchTrueFalseTotal
$can_meta ? : 36 117 153
218 id => refaddr($self),
219 orig => $orig,
220 installed => $code,
221 is_meta => $can_meta ? 1 : 0,
222 meta_orig => $meta_orig,
223 };
224 } else {
225 23 my $is_redefine_after_define = $self->{_defined}{$name};
226 23 ▶ delete $self->{_defined}{$name} if $is_redefine_after_define;
Branch: 1 branch
BranchTrueFalseTotal
if $is_redefine_after_define 3 20 23
227  
228 # Re-mock by same object: update our stack entry's installed
229 # coderef so an above-layer unmock cascades to the correct
230 # (current) coderef. GH #64: when this is a redefine of a sub
231 # created via define(), also update _orig and the entry's orig
232 # so unmock() restores the originally-defined sub. Use this
233 # layer's PRIOR installed coderef rather than \&{$sub_name} --
234 # with stacking, the symbol may currently hold another mock
235 # object's installed coderef rather than ours.
236 23 ▶ if (my $stack = $mock_subs{$sub_name}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $stack = $mock_subs{$sub_name}) 23 0 23
237 23 my $my_id = refaddr($self);
238 23 for my $entry (@$stack) {
239 25 ▶ if ($entry->{id} == $my_id) {
Branch: 1 branch
BranchTrueFalseTotal
if ($entry->{"id"} == $my_id) 23 2 25
240 23 ▶ if ($is_redefine_after_define) {
Branch: 1 branch
BranchTrueFalseTotal
if ($is_redefine_after_define) 3 20 23
241 3 my $prior = $entry->{installed};
242 3 $self->{_orig}{$name} = $prior;
243 3 $entry->{orig} = $prior;
244 }
245 23 $entry->{installed} = $code;
246 23 last;
247 }
248 }
249 }
250 }
251  
252 176 ▶ if ($can_meta) {
Branch: 1 branch
BranchTrueFalseTotal
if ($can_meta) { } 39 137 176
253 39 TRACE("Installing mocked $sub_name via meta->add_method");
254 39 ▶ if ($meta->isa('Class::MOP::Class')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($meta->isa('Class::MOP::Class')) { } 23 16 39
255 $meta->add_method(
256 $name,
257 Class::MOP::Method->wrap(
258 $code,
259 name => $name,
260 package_name => $self->{_package},
261 23 ),
262 );
263 } else {
264 # Mouse: add_method accepts a plain coderef and wraps internally
265 16 $meta->add_method($name, $code);
266 }
267 } else {
268 137 ▶ if ($meta && $meta->is_immutable && !$self->{_warned_immutable}{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($meta and $meta->is_immutable and not $self->{"_warned_immutable"}{$name}) 3 134 137
Condition66%4/6
$meta and $meta->is_immutable and not $self->{"_warned_immutable"}{$name}
!ll&&!rl&&r
13403
$meta and $meta->is_immutable
!ll&&!rl&&r
13403
MC/DC33%1/3
$meta and $meta->is_immutable and not $self->{"_warned_immutable"}{$name}
$meta $meta->is_immutable not $self->{"_warned_immutable"}{$name}
Truth table50%2/4
A and B and not(C)
A= $metaB= $meta->is_immutableC= not $self->{"_warned_immutable"}{$name}
ABCresult
0XX0
10X0
1100
1111
269 3 $self->{_warned_immutable}{$name} = 1;
270 carp sprintf(
271 "Test::MockModule: package %s is immutable; mocking %s via symbol table only. "
272 . "Moose role/modifier resolution will not see the mock. "
273 . "Call %s->meta->make_mutable before mocking if MOP-aware behavior is needed.",
274 $self->{_package}, $name, $self->{_package},
275 3 );
276 }
277 137 TRACE("Installing mocked $sub_name");
278 137 _replace_sub($sub_name, $code);
279 }
280 }
281  
282 149 return $self;
283 }
284  
285 # Install $entry->{installed} at *Pkg::$name, using the meta path when the
286 # entry was originally pushed via meta and the metaclass is currently mutable;
287 # otherwise fall back to the symbol table.
288 26 ▶sub _install_layer {
Subroutine _install_layer: called CC=5 SCAR=16.2
289 26 my ($self, $sub_name, $name, $entry) = @_;
290 26 my $meta = _meta_for($self->{_package});
291 26 ▶ if ($entry->{is_meta} && $meta && !$meta->is_immutable) {
Branch: 1 branch
BranchTrueFalseTotal
if ($entry->{'is_meta'} and $meta and not $meta->is_immutable) { } 12 14 26
Condition66%4/6
$entry->{"is_meta"} and $meta and not $meta->is_immutable
!ll&&!rl&&r
14012
$entry->{"is_meta"} and $meta
!ll&&!rl&&r
14012
MC/DC33%1/3
$entry->{"is_meta"} and $meta and not $meta->is_immutable
$entry->{"is_meta"} $meta not $meta->is_immutable
Truth table50%2/4
A and B and not(C)
A= $entry->{"is_meta"}B= $metaC= not $meta->is_immutable
ABCresult
0XX0
10X0
1100
1111
292 12 ▶ if ($meta->isa('Class::MOP::Class')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($meta->isa('Class::MOP::Class')) { } 6 6 12
293 $meta->add_method(
294 $name,
295 Class::MOP::Method->wrap(
296 $entry->{installed},
297 name => $name,
298 package_name => $self->{_package},
299 6 ),
300 );
301 } else {
302 6 $meta->add_method($name, $entry->{installed});
303 }
304 } else {
305 14 _replace_sub($sub_name, $entry->{installed});
306 }
307 }
308  
309 # Restore the pre-any-mock state for the bottom-most (and now only) layer
310 # being popped. Uses the entry's meta_orig when the layer was pushed via
311 # meta, otherwise its symbol-table orig coderef.
312 127 ▶sub _restore_pre_mock {
Subroutine _restore_pre_mock: called CC=8 SCAR=20.8
313 127 my ($self, $sub_name, $name, $entry) = @_;
314 127 my $meta = _meta_for($self->{_package});
315 127 ▶ my $can_meta = $meta && !$meta->is_immutable;
Condition100%3/3
$meta && !$meta->is_immutable
!ll&&!rl&&r
100126
MC/DC100%2/2
$meta && !$meta->is_immutable
$meta !$meta->is_immutable
Truth table100%3/3
A && not(B)
A= $metaB= !$meta->is_immutable
ABresult
0X0
100
111
316  
317 127 ▶ if ($entry->{is_meta} && $can_meta) {
Branch: 1 branch
BranchTrueFalseTotal
if ($entry->{'is_meta'} and $can_meta) { } 26 101 127
Condition66%2/3
$entry->{"is_meta"} and $can_meta
!ll&&!rl&&r
101026
MC/DC50%1/2
$entry->{"is_meta"} and $can_meta
$entry->{"is_meta"} $can_meta
Truth table66%2/3
A and B
A= $entry->{"is_meta"}B= $can_meta
ABresult
0X0
100
111
318 26 my $orig_method = $entry->{meta_orig};
319 26 ▶ if (defined $orig_method) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $orig_method) { } 18 8 26
320 18 TRACE("Restoring original $sub_name via meta->add_method");
321 # Older Mouse versions require a coderef and reject a
322 # Mouse::Meta::Method object; extract the body for Mouse.
323 # Moose accepts either a coderef or a Class::MOP::Method.
324 18 ▶ my $arg = $meta->isa('Mouse::Meta::Class')
Branch: 2 branches
BranchTrueFalseTotal
$meta->isa('Mouse::Meta::Class') ? : 7 11 18
ref $orig_method eq 'CODE' ? : 0 7 7
325 ? (ref($orig_method) eq 'CODE' ? $orig_method : $orig_method->body)
326 : $orig_method;
327 18 $meta->add_method($name, $arg);
328 } else {
329 8 TRACE("Removing mocked $sub_name from meta (was inherited or absent)");
330 8 ▶ if ($meta->can('remove_method')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($meta->can('remove_method')) { } 5 3 8
331 5 $meta->remove_method($name);
332 } else {
333 # Mouse::Meta::Class has no remove_method; purge the
334 # internal methods cache entry directly so that
335 # get_method() no longer finds the mocked entry.
336 3 delete $meta->{methods}{$name};
337 }
338 # remove_method does not always clear the symbol table.
339 # When the layer captured a symbol-table orig (e.g. an earlier
340 # layer pushed via the symbol table while meta was immutable,
341 # then make_mutable purged the cached meta entry), restore that
342 # coderef so the method continues to resolve. When orig is
343 # undef the slot is cleared, so direct calls fall through to
344 # AUTOLOAD/parent.
345 8 _replace_sub($sub_name, $entry->{orig});
346 }
347 } else {
348 # Either the layer was a symbol-table push, or meta became immutable
349 # between mock and unmock. Fall back to the captured orig coderef.
350 101 _replace_sub($sub_name, $entry->{orig});
351 }
352 }
353  
354 3 ▶sub noop {
Subroutine noop: called CC=3 SCAR=11.0
Pod documented
355 3 my $self = shift;
356  
357 3 ▶ croak "noop is not allowed in strict mode. Please use define or redefine" if $self->_strict_mode();
Branch: 1 branch
BranchTrueFalseTotal
if $self->_strict_mode 1 2 3
358  
359 2 $self->_mock($_,1) for @_;
360  
361 2 return;
362 }
363  
364 11 ▶sub mock_all {
Subroutine mock_all: called CC=9 SCAR=22.0
Pod documented
365 11 my ($self, %opts) = @_;
366  
367 11 ▶ croak "mock_all is not allowed in strict mode. Please use redefine" if $self->_strict_mode();
Branch: 1 branch
BranchTrueFalseTotal
if $self->_strict_mode 1 10 11
368  
369 10 my $package = $self->{_package};
370  
371 10 my @subs;
372 {
373 28 ▶ no strict 'refs'; ## no critic (TestingAndDebugging::ProhibitNoStrict)
Subroutine BEGIN: called CC=1 SCAR=0.0
374 @subs = sort grep {
375 86 defined &{"${package}::$_"}
376 10 } keys %{"${package}::"};
377 }
378  
379 my $make_handler = exists $opts{handler}
380 4 ▶ ? sub { $opts{handler} }
Subroutine __ANON__: called CC=1 SCAR=0.0
381 : $opts{noop}
382 10 ▶ ? sub { sub { 1 } }
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
383 10 ▶ : sub { my $n = shift; sub { croak "$n was not mocked" } };
Subroutine __ANON__: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=1 SCAR=0.0
Branch: 2 branches
BranchTrueFalseTotal
exists $opts{'handler'} ? : 1 9 10
$opts{'noop'} ? : 3 6 9
384  
385 # Skip special Perl subs that should never be blindly mocked:
386 # - Phase blocks (BEGIN, END, INIT, CHECK, UNITCHECK) run at compile/exit time
387 # - DESTROY is called during object cleanup
388 # - AUTOLOAD handles missing method dispatch
389 # - import handles use/import semantics
390 # - Overload subs start with '(' (e.g. '(""', '(+', '(==')
391 10 my %_skip = map { $_ => 1 } qw(
392 import DESTROY BEGIN END INIT CHECK UNITCHECK AUTOLOAD
393 );
394  
395 10 my @to_mock;
396 10 for my $name (@subs) {
397 56 ▶ next if $_skip{$name};
Branch: 1 branch
BranchTrueFalseTotal
if $_skip{$name} 14 42 56
398 42 ▶ next if $name =~ /^\(/; # overload subs
Branch: 1 branch
BranchTrueFalseTotal
if $name =~ /^\(/ 6 36 42
399 36 ▶ next if $self->{_mocked}{$name};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"_mocked"}{$name} 1 35 36
400 35 push @to_mock, $name, $make_handler->("${package}::${name}");
401 }
402  
403 10 ▶ return $self->_mock(@to_mock) if @to_mock;
Branch: 1 branch
BranchTrueFalseTotal
if @to_mock 10 0 10
404 0 return $self;
405 }
406  
407 22 ▶sub original {
Subroutine original: called CC=5 SCAR=16.1
Pod documented
408 22 my ($self, $name) = @_;
409  
410 22 ▶ carp 'Please provide a valid function name' unless _valid_subname($name);
Branch: 1 branch
BranchTrueFalseTotal
unless _valid_subname($name) 1 21 22
411  
412 22 ▶ unless ($self->{_mocked}{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"_mocked"}{$name}) 6 16 22
413 # GH #42: when not mocked, return the actual sub instead of warning
414 6 my $sub_name = _full_name($self, $name);
415 6 ▶ return \&$sub_name if defined &{$sub_name};
Branch: 1 branch
BranchTrueFalseTotal
if defined &{$sub_name;} 4 2 6
416 2 return $self->{_package}->super($name);
417 }
418 16 ▶ return defined $self->{_orig}{$name} ? $self->{_orig}{$name} : $self->{_package}->super($name);
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{'_orig'}{$name} ? : 13 3 16
419 }
420  
421 # Class-method counterpart to $mock->original(). Takes strings, returns
422 # the truly-original coderef from the per-package registry (or the live
423 # sub if not mocked). Lets user closures reach the original sub without
424 # capturing $mock -- the closure-capture pattern that drives the GH #83
425 # DESTROY-leak under `distinct => 1` mode.
426 10 ▶sub original_for {
Subroutine original_for: called CC=7 SCAR=19.5
Pod documented
427 10 my ($class, $package, $name) = @_;
428 10 ▶ croak "Invalid package name " . (defined $package ? $package : 'undef')
Branch: 2 branches
BranchTrueFalseTotal
unless _valid_package($package) 1 9 10
defined $package ? : 1 0 1
429 unless _valid_package($package);
430 9 ▶ croak 'Please provide a valid function name'
Branch: 1 branch
BranchTrueFalseTotal
unless _valid_subname($name) 1 8 9
431 unless _valid_subname($name);
432  
433 8 my $sub_name = "${package}::${name}";
434 8 my $stack = $mock_subs{$sub_name};
435 8 ▶ if ($stack && @$stack) {
Branch: 1 branch
BranchTrueFalseTotal
if ($stack and @$stack) 6 2 8
Condition66%2/3
$stack and @$stack
!ll&&!rl&&r
206
MC/DC50%1/2
$stack and @$stack
$stack @$stack
Truth table66%2/3
A and B
A= $stackB= @$stack
ABresult
0X0
100
111
436 # Bottom-of-stack orig is the truly-original. May be undef when
437 # the sub was created via define() -- that is expected. Falling
438 # through to \&$sub_name would hand back the active mock (an
439 # infinite-recursion footgun for closures wrapping their orig).
440 6 return $stack->[0]{orig};
441 }
442 28 ▶ no strict 'refs'; ## no critic (TestingAndDebugging::ProhibitNoStrict)
Subroutine BEGIN: called CC=1 SCAR=0.0
443 2 ▶ return \&$sub_name if defined &{$sub_name};
Branch: 1 branch
BranchTrueFalseTotal
if defined &{$sub_name;} 1 1 2
444 1 return;
445 }
446  
447 157 ▶sub unmock {
Subroutine unmock: called CC=13 SCAR=25.7
Pod documented
448 157 my ( $self, @names ) = @_;
449  
450 157 ▶ carp 'Nothing to unmock' unless @names;
Branch: 1 branch
BranchTrueFalseTotal
unless @names 1 156 157
451 157 for my $name (@names) {
452 156 ▶ croak "Invalid subroutine name: $name" unless _valid_subname($name);
Branch: 1 branch
BranchTrueFalseTotal
unless _valid_subname($name) 1 155 156
453  
454 155 my $sub_name = _full_name($self, $name);
455 155 ▶ unless ($self->{_mocked}{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"_mocked"}{$name}) 2 153 155
456 2 carp $sub_name . " was not mocked";
457 2 next;
458 }
459  
460 153 TRACE("Restoring original $sub_name");
461 153 my $stack = $mock_subs{$sub_name};
462 153 ▶ if ($stack) {
Branch: 1 branch
BranchTrueFalseTotal
if ($stack) { } 153 0 153
463 153 my $my_id = refaddr($self);
464 153 my $idx;
465 153 for my $i (0 .. $#$stack) {
466 166 ▶ if ($stack->[$i]{id} == $my_id) {
Branch: 1 branch
BranchTrueFalseTotal
if ($stack->[$i]{"id"} == $my_id) 153 13 166
467 153 $idx = $i;
468 153 last;
469 }
470 }
471 153 ▶ if (defined $idx) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $idx) { } 153 0 153
472 153 ▶ if ($idx == $#$stack) {
Branch: 1 branch
BranchTrueFalseTotal
if ($idx == $stack->$#*) { } 138 15 153
473 # Top of stack: restore the prior layer's installed
474 # coderef (via meta or symbol as the layer dictates),
475 # or fully restore the pre-mock state if no prior
476 # layer remains.
477 138 my $popped = pop @$stack;
478 138 ▶ if (@$stack) {
Branch: 1 branch
BranchTrueFalseTotal
if (@$stack) { } 11 127 138
479 11 $self->_install_layer($sub_name, $name, $stack->[-1]);
480 } else {
481 127 $self->_restore_pre_mock($sub_name, $name, $popped);
482 }
483 } else {
484 # Mid-stack: cascade our orig (and meta_orig, when the
485 # layer above also used the meta path) down to the next
486 # entry so a later stack-empty restore sees the correct
487 # pre-any-mock state. Then remove ourselves and re-install
488 # the new top's installed coderef -- the symbol/meta may
489 # currently hold OUR installed coderef if we re-mocked
490 # after a higher layer was pushed, so we must explicitly
491 # restore the layer that should now be active.
492 15 $stack->[$idx + 1]{orig} = $stack->[$idx]{orig};
493 $stack->[$idx + 1]{meta_orig} = $stack->[$idx]{meta_orig}
494 15 ▶ if $stack->[$idx + 1]{is_meta};
Branch: 1 branch
BranchTrueFalseTotal
if $$stack[$idx + 1]{"is_meta"} 10 5 15
495 15 splice @$stack, $idx, 1;
496 15 $self->_install_layer($sub_name, $name, $stack->[-1]);
497 }
498 } else {
499 # Defensive: not found in stack (shouldn't happen).
500 0 _replace_sub($sub_name, $self->{_orig}{$name});
501 }
502 153 ▶ delete $mock_subs{$sub_name} unless @$stack;
Branch: 1 branch
BranchTrueFalseTotal
unless @$stack 127 26 153
503 } else {
504 0 _replace_sub($sub_name, $self->{_orig}{$name});
505 }
506  
507 153 delete $self->{_mocked}{$name};
508 153 delete $self->{_orig}{$name};
509 153 delete $self->{_defined}{$name};
510 153 delete $self->{_warned_immutable}{$name};
511 }
512 156 return $self;
513 }
514  
515 140 ▶sub unmock_all {
Subroutine unmock_all: called CC=2 SCAR=6.9
Pod documented
516 140 my $self = shift;
517 140 foreach my $name (keys %{$self->{_mocked}}) {
518 94 $self->unmock($name);
519 }
520  
521 140 return;
522 }
523  
524 17 ▶sub is_mocked {
Subroutine is_mocked: called CC=2 SCAR=6.9
Pod documented
525 17 my ($self, $name) = @_;
526  
527 17 ▶ return unless _valid_subname($name);
Branch: 1 branch
BranchTrueFalseTotal
unless _valid_subname($name) 3 14 17
528  
529 14 return $self->{_mocked}{$name};
530 }
531  
532 7 ▶sub mocked_subs {
Subroutine mocked_subs: called CC=1 SCAR=0.0
Pod documented
533 7 my $self = shift;
534 7 my @subs = sort keys %{$self->{_mocked}};
535 7 return @subs;
536 }
537  
538 365 ▶sub _full_name {
Subroutine _full_name: called CC=1 SCAR=0.0
539 365 my ($self, $sub_name) = @_;
540 365 return sprintf( "%s::%s", $self->{_package}, $sub_name );
541 }
542  
543 154 ▶sub _valid_package {
Subroutine _valid_package: called CC=3 SCAR=11.0
544 154 my $name = shift;
545 154 ▶ return unless defined $name && length $name;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $name and length $name 2 152 154
Condition100%3/3
defined $name and length $name
!ll&&!rl&&r
11152
MC/DC100%2/2
defined $name and length $name
defined $name length $name
Truth table100%3/3
A and B
A= defined $nameB= length $name
ABresult
0X0
100
111
546 152 return $name =~ /^[a-z_]\w*(?:::\w+)*$/i;
547 }
548  
549 381 ▶sub _valid_subname {
Subroutine _valid_subname: called CC=3 SCAR=11.0
550 381 my $name = shift;
551 381 ▶ return unless defined $name && length $name;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $name and length $name 1 380 381
Condition66%2/3
defined $name and length $name
!ll&&!rl&&r
01380
MC/DC50%1/2
defined $name and length $name
defined $name length $name
Truth table66%2/3
A and B
A= defined $nameB= length $name
ABresult
0X0
100
111
552 380 return $name =~ /^[a-z_]\w*$/i;
553 }
554  
555 492 ▶sub _meta_for {
Subroutine _meta_for: called CC=8 SCAR=20.9
556 492 my $package = shift;
557 492 ▶ return unless defined $package && length $package;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $package and length $package 4 488 492
Condition100%3/3
defined $package and length $package
!ll&&!rl&&r
22488
MC/DC100%2/2
defined $package and length $package
defined $package length $package
Truth table100%3/3
A and B
A= defined $packageB= length $package
ABresult
0X0
100
111
558 488 ▶ return unless $package->can('meta');
Branch: 1 branch
BranchTrueFalseTotal
unless $package->can("meta") 351 137 488
559 137 my $meta = eval { $package->meta };
560 137 ▶ return unless ref $meta;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $meta 0 137 137
561 # Moo's ->meta returns a Moo::HandleMoose::FakeMetaClass whose ->isa lazily
562 # inflates a real Moose metaclass -- which throws when Moose isn't installed.
563 # Match it by exact ref (not ->isa) BEFORE the isa checks so inflation never
564 # fires; Moo classes fall back to plain symbol-table mocking. (GH #93)
565 137 ▶ return if ref($meta) eq 'Moo::HandleMoose::FakeMetaClass';
Branch: 1 branch
BranchTrueFalseTotal
if ref $meta eq "Moo::HandleMoose::FakeMetaClass" 10 127 137
566 127 ▶ return $meta if $meta->isa('Class::MOP::Class'); # Moose
Branch: 1 branch
BranchTrueFalseTotal
if $meta->isa("Class::MOP::Class") 75 52 127
567 52 ▶ return $meta if $meta->isa('Mouse::Meta::Class'); # Mouse
Branch: 1 branch
BranchTrueFalseTotal
if $meta->isa("Mouse::Meta::Class") 52 0 52
568 0 return;
569 }
570  
571 260 ▶sub _replace_sub {
Subroutine _replace_sub: called CC=7 SCAR=19.5
572 260 my ($sub_name, $coderef) = @_;
573  
574 28 ▶ no warnings qw< redefine prototype >;
Subroutine BEGIN: called CC=1 SCAR=0.0
575  
576 260 ▶ if (defined $coderef) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $coderef) { } 243 17 260
577 243 *{$sub_name} = $coderef;
578 } else {
579 17 TRACE("removing subroutine: $sub_name");
580 17 my ($package, $sub) = $sub_name =~ /(.*::)(.*)/;
581 17 my %symbols = %{$package};
582  
583 # save a copy of all non-code slots
584 17 my %slot;
585 17 foreach my $slot_name (qw(ARRAY FORMAT HASH IO SCALAR)) {
586 85 ▶ next unless defined $symbols{$sub};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $symbols{$sub} 0 85 85
587 85 ▶ next unless defined(my $elem = *{$symbols{$sub}}{$slot_name});
Branch: 1 branch
BranchTrueFalseTotal
unless defined(my $elem = *{$symbols{$sub};}{$slot_name}) 67 18 85
588 18 $slot{$slot_name} = $elem;
589 }
590  
591 # clear the symbol table entry for the subroutine
592 17 undef *$sub_name;
593  
594 # restore everything except the code slot
595 17 ▶ return unless scalar keys %slot;
Branch: 1 branch
BranchTrueFalseTotal
unless scalar keys %slot 0 17 17
596 17 foreach (keys %slot) {
597 18 *$sub_name = $slot{$_};
598 }
599 }
600 }
601  
602 # Log::Trace stubs
603 894 ▶sub TRACE {}
Subroutine TRACE: called CC=1 SCAR=0.0
Pod documented
604 0 ▶sub DUMP {}
Subroutine DUMP: not called CC=1 SCAR=0.0
Pod documented
605  
606 28 1;
607  
608 =pod
609  
610 =head1 NAME
611  
612 Test::MockModule - Override subroutines in a module for unit testing
613  
614 =head1 SYNOPSIS
615  
616 use Module::Name;
617 use Test::MockModule;
618  
619 {
620 my $module = Test::MockModule->new('Module::Name');
621 $module->mock('subroutine', sub { ... });
622 Module::Name::subroutine(@args); # mocked
623  
624 # Same effect, but this will die() if other_subroutine()
625 # doesn't already exist, which is often desirable.
626 $module->redefine('other_subroutine', sub { ... });
627  
628 # This will die() if another_subroutine() is defined.
629 $module->define('another_subroutine', sub { ... });
630 }
631  
632 {
633 # you can also chain new/mock/redefine/define
634  
635 Test::MockModule->new('Module::Name')
636 ->mock( one_subroutine => sub { ... })
637 ->redefine( other_subroutine => sub { ... } )
638 ->define( a_new_sub => 1234 );
639 }
640  
641 Module::Name::subroutine(@args); # original subroutine
642  
643 # Working with objects
644 use Foo;
645 use Test::MockModule;
646 {
647 my $mock = Test::MockModule->new('Foo');
648 $mock->mock(foo => sub { print "Foo!\n"; });
649  
650 my $foo = Foo->new();
651 $foo->foo(); # prints "Foo!\n"
652 }
653  
654 # If you want to prevent noop and mock from working, you can
655 # load Test::MockModule in strict mode.
656  
657 use Test::MockModule qw/strict/;
658 my $module = Test::MockModule->new('Module::Name');
659  
660 # Redefined the other_subroutine or dies if it's not there.
661 $module->redefine('other_subroutine', sub { ... });
662  
663 # Dies since you specified you wanted strict mode.
664 $module->mock('subroutine', sub { ... });
665  
666 # Turn strictness off in this lexical scope
667 {
668 use Test::MockModule 'nostrict';
669 # ->mock() works now
670 $module->mock('subroutine', sub { ... });
671 }
672  
673 # Assure strict is ALWAYS used.
674 use Test::MockModule 'global-strict';
675  
676 # Back in the strict scope, so mock() dies here
677 $module->mock('subroutine', sub { ... });
678  
679 =head1 DESCRIPTION
680  
681 C<Test::MockModule> lets you temporarily redefine subroutines in other packages
682 for the purposes of unit testing.
683  
684 A C<Test::MockModule> object is set up to mock subroutines for a given
685 module. The object remembers the original subroutine so it can be easily
686 restored. This happens automatically when all MockModule objects for the given
687 module go out of scope, or when you C<unmock()> the subroutine.
688  
689 =head1 STRICT MODE
690  
691 One of the weaknesses of testing using mocks is that the implementation of the
692 interface that you are mocking might change, while your mocks get left alone.
693 You are not now mocking what you thought you were, and your mocks might now be
694 hiding bugs that will only be spotted in production. To help prevent this you
695 can load Test::MockModule in 'strict' mode:
696  
697 use Test::MockModule qw(strict);
698  
699 This will disable use of the C<mock()> method, making it a fatal runtime error.
700 You should instead define mocks using C<redefine()>, which will only mock
701 things that already exist and die if you try to redefine something that doesn't
702 exist.
703  
704 Strictness is lexically scoped, so you can do this in one file:
705  
706 use Test::MockModule qw(strict);
707
708 ...->redefine(...);
709  
710 and this in another:
711  
712 use Test::MockModule; # the default is nostrict
713  
714 ...->mock(...);
715  
716 You can even mix n match at different places in a single file thus:
717  
718 use Test::MockModule qw(strict);
719 # here mock() dies
720  
721 {
722 use Test::MockModule qw(nostrict);
723 # here mock() works
724 }
725  
726 # here mock() goes back to dieing
727  
728 use Test::MockModule qw(nostrict);
729 # and from here on mock() works again
730  
731 NB that strictness must be defined at compile-time, and set using C<use>. If
732 you think you're going to try and be clever by calling Test::MockModule's
733 C<import()> method at runtime then what happens in undefined, with results
734 differing from one version of perl to another. What larks!
735  
736 =head1 GLOBAL STRICT MODE
737  
738 If your particular test suite needs to assure that no developer ever accidentally
739 turns off strict, this is the mode for you
740  
741 use Test::MockModule 'global-strict';
742  
743 Setting this mode will cause any later invocation of nostrict to fail on compile.
744 Further, any use of mock at runtime will die if the 'nostrict' mode was invoked
745 prior to global-strict being initially set. While this seems like it might be
746 overkill, this can be important as the number of simultaneous developers
747 increases over time.
748  
749 =head1 METHODS
750  
751 =over 4
752  
753 =item new($package[, %options])
754  
755 Returns a singleton-per-package mock object. Two calls to
756 C<< Test::MockModule->new('Foo') >> return the same object as long as the
757 first one is still alive; this preserves the long-standing pre-v0.181
758 contract that the documented C<< $mock->original >> from-inside-closure
759 pattern depends on (see GH #83).
760  
761 Pass C<< distinct => 1 >> to opt into the v0.181 GH #48 semantics --
762 each call returns a fresh object, multiple mock objects coexist on the
763 same package, and the per-sub stack handles multi-mock layering:
764  
765 my $m1 = Test::MockModule->new('Module::Name', distinct => 1);
766 my $m2 = Test::MockModule->new('Module::Name', distinct => 1);
767 # $m1 and $m2 are independent. Tests that need this layering must
768 # opt in explicitly.
769  
770 Under C<distinct> mode the most recent C<mock>/C<redefine> call wins
771 regardless of stack position; when a mock object is destroyed, the
772 layer below it on the stack is reactivated; when all mock objects for
773 a subroutine are destroyed, the original subroutine is restored.
774  
775 If there is no C<$VERSION> defined in C<$package>, the module will be
776 automatically loaded. You can override this behaviour by setting the
777 C<no_auto> option:
778  
779 my $mock = Test::MockModule->new('Module::Name', no_auto => 1);
780  
781 B<GH #83 caveat for distinct mode>: a closure that captures C<$mock>
782 (typically by calling C<< $mock->original(...) >> inside the mock body)
783 prevents C<DESTROY> from firing when C<$mock> goes out of scope, so
784 the mock leaks past its lexical scope. The default (singleton) mode
785 makes this leak harmless by re-using the same object on subsequent
786 C<new()> calls. Under C<< distinct => 1 >>, prefer the class-method
787 form C<< Test::MockModule->original_for($pkg, $sub) >> from inside
788 closures so they capture only strings, or capture
789 C<< $mock->original(...) >> in a lexical B<before> calling C<mock()>.
790  
791 =item get_package()
792  
793 Returns the target package name for the mocked subroutines
794  
795 =item is_mocked($subroutine)
796  
797 Returns a boolean value indicating whether or not the subroutine is currently
798 mocked
799  
800 =item mocked_subs()
801  
802 Returns a sorted list of the subroutine names that are currently mocked for
803 this module. Useful for debugging complex test setups.
804  
805 my $mock = Test::MockModule->new('Module::Name');
806 $mock->mock('foo', sub { 1 });
807 $mock->mock('bar', sub { 2 });
808 my @mocked = $mock->mocked_subs; # ('bar', 'foo')
809  
810 =item mock($subroutine =E<gt> \E<amp>coderef)
811  
812 Temporarily replaces one or more subroutines in the mocked module. A subroutine
813 can be mocked with a code reference or a scalar. A scalar will be recast as a
814 subroutine that returns the scalar.
815  
816 Returns the current C<Test::MockModule> object, so you can chain L<new> with L<mock>.
817  
818 my $mock = Test::MockModule->new(...)->mock(...);
819  
820 The following statements are equivalent:
821  
822 $module->mock(purge => 'purged');
823 $module->mock(purge => sub { return 'purged'});
824  
825 When dealing with references, things behave slightly differently. The following
826 statements are B<NOT> equivalent:
827  
828 # Returns the same arrayref each time, with the localtime() at time of mocking
829 $module->mock(updated => [localtime()]);
830 # Returns a new arrayref each time, with up-to-date localtime() value
831 $module->mock(updated => sub { return [localtime()]});
832  
833 The following statements are in fact equivalent:
834  
835 my $array_ref = [localtime()]
836 $module->mock(updated => $array_ref)
837 $module->mock(updated => sub { return $array_ref });
838  
839  
840 However, C<undef> is a special case. If you mock a subroutine with C<undef> it
841 will install an empty subroutine
842  
843 $module->mock(purge => undef);
844 $module->mock(purge => sub { });
845  
846 rather than a subroutine that returns C<undef>:
847  
848 $module->mock(purge => sub { undef });
849  
850 You can call C<mock()> for the same subroutine many times, but when you call
851 C<unmock()>, the original subroutine is restored (not the last mocked
852 instance).
853  
854 B<MOCKING + EXPORT>
855  
856 If you are trying to mock a subroutine exported from another module, this may
857 not behave as you initially would expect, since Test::MockModule is only mocking
858 at the target module, not anything importing that module. If you mock the local
859 package, or use a fully qualified function name, you will get the behavior you
860 desire:
861  
862 use Test::MockModule;
863 use Test::More;
864 use POSIX qw/strftime/;
865  
866 my $posix = Test::MockModule->new("POSIX");
867  
868 $posix->mock("strftime", "Yesterday");
869 is strftime("%D", localtime(time)), "Yesterday", "`strftime` was mocked successfully"; # Fails
870 is POSIX::strftime("%D", localtime(time)), "Yesterday", "`strftime` was mocked successfully"; # Succeeds
871  
872 my $main = Test::MockModule->new("main", no_auto => 1);
873 $main->mock("strftime", "today");
874 is strftime("%D", localtime(time)), "today", "`strftime` was mocked successfully"; # Succeeds
875  
876 If you are trying to mock a subroutine that was exported into a module that you're
877 trying to test, rather than mocking the subroutine in its originating module,
878 you can instead mock it in the module you are testing:
879  
880 package MyModule;
881 use POSIX qw/strftime/;
882  
883 sub minus_twentyfour
884 {
885 return strftime("%a, %b %d, %Y", localtime(time - 86400));
886 }
887  
888 package main;
889 use Test::More;
890 use Test::MockModule;
891  
892 my $posix = Test::MockModule->new("POSIX");
893 $posix->mock("strftime", "Yesterday");
894  
895 is MyModule::minus_twentyfour(), "Yesterday", "`minus-twentyfour` got mocked"; # fails
896  
897 my $mymodule = Test::MockModule->new("MyModule", no_auto => 1);
898 $mymodule->mock("strftime", "Yesterday");
899 is MyModule::minus_twentyfour(), "Yesterday", "`minus-twentyfour` got mocked"; # succeeds
900  
901 =item redefine($subroutine)
902  
903 The same behavior as C<mock()>, but this will preemptively check to be
904 sure that all passed subroutines actually exist. This is useful to ensure that
905 if a mocked module's interface changes the test doesn't just keep on testing a
906 code path that no longer behaves consistently with the mocked behavior.
907  
908 Note that redefine is also now checking if one of the parent provides the sub
909 and will not die if it's available in the chain.
910  
911 Returns the current C<Test::MockModule> object, so you can chain L<new> with L<redefine>.
912  
913 my $mock = Test::MockModule->new(...)->redefine(...);
914  
915 =item define($subroutine)
916  
917 The reverse of redefine, this will fail if the passed subroutine exists.
918 While this use case is rare, there are times where the perl code you are
919 testing is inspecting a package and adding a missing subroutine is actually
920 what you want to do.
921  
922 By using define, you're asserting that the subroutine you want to be mocked
923 should not exist in advance.
924  
925 Note: define does not check for inheritance like redefine.
926  
927 Returns the current C<Test::MockModule> object, so you can chain L<new> with L<define>.
928  
929 my $mock = Test::MockModule->new(...)->define(...);
930  
931 =item original($subroutine)
932  
933 Returns the original (unmocked) subroutine. If the subroutine is not currently
934 mocked, returns the existing subroutine directly instead of warning. This makes
935 it safe to call C<original()> before or after mocking.
936  
937 Here is a sample how to wrap a function with custom arguments using the original subroutine.
938 This is useful when you cannot (do not) want to alter the original code to abstract
939 one hardcoded argument pass to a function.
940  
941 package MyModule;
942  
943 sub sample {
944 return get_path_for("/a/b/c/d");
945 }
946  
947 sub get_path_for {
948 ... # anything goes there...
949 }
950  
951 package main;
952 use Test::MockModule;
953  
954 my $mock = Test::MockModule->new("MyModule");
955 # capture the original before mocking to avoid closing over $mock
956 my $orig_get_path = $mock->original("get_path_for");
957 # replace all calls to get_path_for using a different argument
958 $mock->redefine("get_path_for", sub {
959 return $orig_get_path->("/my/custom/path");
960 });
961  
962 # or
963  
964 my $orig_get_path = $mock->original("get_path_for");
965 $mock->redefine("get_path_for", sub {
966 my $path = shift;
967 if ( $path && $path eq "/a/b/c/d" ) {
968 # only alter calls with path set to "/a/b/c/d"
969 return $orig_get_path->("/my/custom/path");
970 } else { # preserve the original arguments
971 return $orig_get_path->($path, @_);
972 }
973 });
974  
975  
976 =item original_for($package, $subroutine)
977  
978 Class-method counterpart to C<original()>. Returns the truly-original
979 coderef for C<$package::$subroutine> from the per-package registry,
980 or the live sub via the symbol table if not currently mocked. Returns
981 C<undef> if no sub by that name exists. Croaks on invalid package or
982 sub names.
983  
984 The motivating use case is letting closures reach the original sub
985 without capturing C<$mock> -- the closure-capture pattern that drives
986 the GH #83 leak under C<< distinct => 1 >> mode:
987  
988 my $mock = Test::MockModule->new('MyModule', distinct => 1);
989 $mock->mock('greet', sub {
990 # Closure captures only strings -- $mock can be GC'd at scope end
991 return Test::MockModule
992 ->original_for('MyModule', 'greet')->(@_) . '_suffix';
993 });
994  
995 For stacked mocks, returns the truly-original (pre-any-mock) coderef,
996 not the layer below.
997  
998  
999 =item unmock($subroutine [, ...])
1000  
1001 Restores the original C<$subroutine>. You can specify a list of subroutines to
1002 C<unmock()> in one go.
1003  
1004 =item unmock_all()
1005  
1006 Restores all the subroutines in the package that were mocked. This is
1007 automatically called when all C<Test::MockModule> objects for the given package
1008 go out of scope.
1009  
1010 =item noop($subroutine [, ...])
1011  
1012 Given a list of subroutine names, mocks each of them with a no-op subroutine that
1013 returns C<1>. Handy for mocking methods you want to ignore!
1014  
1015 The C<1> return value is part of the public contract of this method (see GH #81)
1016 -- callers in the wild rely on it being truthy.
1017  
1018 # Neuter a list of methods in one go
1019 $module->noop('purge', 'updated');
1020  
1021 =item mock_all(%options)
1022  
1023 Mocks all subroutines in the target package that are not already mocked.
1024 By default, each mocked subroutine will die when called, making it easy
1025 to catch unexpected calls during testing.
1026  
1027 my $module = Test::MockModule->new('Foo');
1028 $module->mock_all();
1029 Foo->bar(); # dies: "Foo::bar was not mocked"
1030  
1031 The C<import> subroutine is always skipped.
1032  
1033 Options:
1034  
1035 =over 4
1036  
1037 =item noop =E<gt> 1
1038  
1039 Mock all subroutines with a no-op sub that returns C<1> instead of dying.
1040 This is consistent with C<noop()>.
1041  
1042 $module->mock_all(noop => 1);
1043 Foo->bar(); # returns 1
1044  
1045 =item handler =E<gt> \&coderef
1046  
1047 Provide a custom handler for all mocked subroutines.
1048  
1049 $module->mock_all(handler => sub { warn "unexpected call" });
1050  
1051 =back
1052  
1053 Returns the current C<Test::MockModule> object for chaining.
1054  
1055 =back
1056  
1057 =over 4
1058  
1059 =item TRACE
1060  
1061 A stub for Log::Trace
1062  
1063 =item DUMP
1064  
1065 A stub for Log::Trace
1066  
1067 =back
1068  
1069 =head1 MOOSE AND MOUSE SUPPORT
1070  
1071 When the target package's metaclass is a C<Class::MOP::Class> (Moose) or
1072 C<Mouse::Meta::Class> (Mouse), C<Test::MockModule> registers mocks with
1073 the meta-object via C<add_method> in addition to installing them in the
1074 symbol table. This makes mocked methods visible to:
1075  
1076 =over 4
1077  
1078 =item * Moose role C<requires> checks (including dynamic role application
1079 via L<Moose::Util/apply_all_roles>).
1080  
1081 =item * Method modifier resolution (C<around>, C<before>, C<after>) on
1082 subclasses loaded after the mock is installed.
1083  
1084 =item * Other MOP-driven introspection that walks C<get_method> /
1085 C<get_method_list>.
1086  
1087 =back
1088  
1089 C<unmock> reverses the registration: if the original method existed on
1090 the class itself, it is restored via C<add_method>; if the method was
1091 inherited (or absent) before mocking, it is removed via
1092 C<remove_method> so inheritance lookup falls back to the parent.
1093 For Mouse classes (which lack a public C<remove_method> on
1094 C<Mouse::Meta::Class>), the mock entry is purged from the meta-class's
1095 internal method cache directly to achieve the same effect.
1096  
1097 If the target class is immutable (C<< $meta->is_immutable >> is true),
1098 C<Test::MockModule> falls back to symbol-table-only behavior and emits a
1099 warning. Call C<< Pkg->meta->make_mutable >> before mocking if you need
1100 MOP-aware behavior on an immutable class.
1101  
1102 =head2 Moo and other MOP-less object systems
1103  
1104 L<Moo>, L<Role::Tiny>, and L<Object::Pad> are not detected and not
1105 specially handled. Mocks on Moo classes still work for direct calls but
1106 will not be seen by role-application or method-modifier resolution for
1107 classes that consume Moo roles. As a workaround, mock the underlying
1108 package directly with C<no_auto =E<gt> 1> and explicit load ordering, or
1109 convert the affected class to Moose.
1110  
1111 =head1 SEE ALSO
1112  
1113 L<Test::MockObject::Extends>
1114  
1115 L<Sub::Override>
1116  
1117 =head1 AUTHORS
1118  
1119 Current Maintainer: Geoff Franks <gfranks@cpan.org>
1120  
1121 Original Author: Simon Flack E<lt>simonflk _AT_ cpan.orgE<gt>
1122  
1123 Lexical scoping of strictness: David Cantrell E<lt>david@cantrell.org.ukE<gt>
1124  
1125 =head1 COPYRIGHT
1126  
1127 Copyright 2004 Simon Flack E<lt>simonflk _AT_ cpan.orgE<gt>.
1128 All rights reserved
1129  
1130 You may distribute under the terms of either the GNU General Public License or
1131 the Artistic License, as specified in the Perl README file.
1132  
1133 =cut
↑ Summary