File: lib/Test/Mockingbird/DeepMock.pm

lib/Test/Mockingbird/DeepMock.pm

Structural Coverage (Approximate)

TER1 (Statement): 100.00%
TER2 (Branch): 100.00%
TER3 (LCSAJ): 100.0% (5/5)
Approximate LCSAJ segments: 59

LCSAJ Legend

● Covered — this LCSAJ path was executed during testing.

● Not covered — this LCSAJ path was never executed. These are the paths to focus on.

Multiple dots on a line indicate that multiple control-flow paths begin at that line. Hovering over any dot shows:

        start → end → jump

start – first line of the linear sequence
end – last line before control flow changes
jump – line execution jumps to next

Uncovered paths show [NOT COVERED] in the tooltip.

Mutant Testing Legend

Survived (tests missed this) Killed (tests detected this) No mutation

1: package Test::Mockingbird::DeepMock; 2: 3: use strict; 4: use warnings; 5: 6: use Carp qw(croak); 7: use Exporter 'import'; 8: use Test::Mockingbird (); 9: use Test::Mockingbird::TimeTravel (); 10: use Test::More (); 11: 12: our @EXPORT_OK = qw(deep_mock); 13: 14: =encoding utf-8 15: 16: =head1 NAME 17: 18: Test::Mockingbird::DeepMock - Declarative structured mocking and spying for Perl tests 19: 20: =head1 VERSION 21: 22: Version 0.14 23: 24: =cut 25: 26: our $VERSION = '0.14'; 27: 28: =head1 SYNOPSIS 29: 30: use Test::Mockingbird::DeepMock qw(deep_mock); 31: 32: deep_mock( 33: { 34: mocks => [ 35: { target => 'MyApp::greet', type => 'mock', with => sub { 'hi' } }, 36: { target => 'MyApp::double', type => 'spy', tag => 'double_spy' }, 37: ], 38: expectations => [ 39: { tag => 'double_spy', calls => 2 }, 40: ], 41: }, 42: sub { 43: is MyApp::greet(), 'hi', 'greet mocked'; 44: MyApp::double(2); 45: MyApp::double(3); 46: } 47: ); 48: 49: =head1 DESCRIPTION 50: 51: C<Test::Mockingbird::DeepMock> provides a declarative, data-driven way to 52: describe mocking, spying, injection, and expectations in Perl tests. 53: 54: Instead of scattering C<mock>, C<spy>, and C<restore_all> calls throughout 55: your test code, DeepMock lets you define a complete mocking plan in a single 56: hashref, then executes your test code under that plan. 57: 58: =head1 LIMITATIONS 59: 60: =over 4 61: 62: =item Nested deep_mock scopes are not supported 63: 64: C<deep_mock> calls C<restore_all()> on exit, which removes every active mock. 65: A nested C<deep_mock> call will cause the inner exit to also tear down the 66: outer mocks. 67: 68: =item inject type in mocks list 69: 70: The C<inject> mock type delegates to C<Test::Mockingbird::inject()>. Because 71: C<inject()> builds a sub that returns the C<with> value verbatim, passing a 72: coderef via C<with> stores the coderef itself; it is not called on each 73: access. To inject a factory, wrap it explicitly. 74: 75: =back 76: 77: =head1 PLAN STRUCTURE 78: 79: =head2 C<mocks> 80: 81: ArrayRef of mock specs. Each entry: 82: 83: { 84: target => 'Package::method', 85: type => 'mock' | 'spy' | 'inject', 86: with => sub { ... }, 87: tag => 'identifier', 88: } 89: 90: =head2 C<expectations> 91: 92: ArrayRef of expectation specs. Each entry: 93: 94: { 95: tag => 'spy_tag', 96: calls => $n, 97: args_like => [ [qr/pat1/, qr/pat2/], ... ], 98: args_eq => [ ['exact', 'args'], ... ], 99: args_deeply => [ [$struct], ... ], 100: never => 1, 101: order => [ 'A::m1', 'B::m2' ], 102: } 103: 104: The C<order> key is processed after all per-spy expectations and does not 105: require a C<tag>. 106: 107: =head2 C<globals> 108: 109: Optional: 110: 111: globals => { restore_on_scope_exit => 1 } 112: 113: =head2 C<time> 114: 115: Optional time-travel plan applied before mocks are installed: 116: 117: time => { 118: freeze => '2025-01-01T00:00:00Z', 119: travel => '2025-01-03T00:00:00Z', 120: advance => [ 2 => 'minutes' ], 121: rewind => [ 1 => 'hour' ], 122: } 123: 124: =head1 TROUBLESHOOTING 125: 126: =head2 "Not enough arguments for deep_mock" 127: 128: DeepMock uses C<($$)> prototype. Use C<deep_mock( {...}, sub { ... } )>. 129: 130: =head2 My mocks are not restored 131: 132: Check C<globals => { restore_on_scope_exit => 0 }> has not been set. 133: 134: =head1 METHODS 135: 136: =head2 deep_mock 137: 138: Run a code block with a set of mocks and expectations applied. 139: 140: =head3 API SPECIFICATION 141: 142: =head4 Input (Params::Validate::Strict schema) 143: 144: $plan -- HashRef with keys: mocks, expectations, globals, time 145: $code -- CodeRef 146: 147: =head4 Output (Returns::Set schema) 148: 149: returns: whatever $code returns (context-sensitive) 150: 151: =head3 MESSAGES 152: 153: "deep_mock expects a HASHREF plan" -- first arg is not a hashref 154: 155: =head3 FORMAL SPECIFICATION 156: 157: deep_mock â‰™ 158: âˆ€ plan : HashRef; code : CodeRef â€¢ 159: pre ref(plan) = 'HASH' 160: post apply_time(plan.time) 161: âˆ§ install_mocks(plan.mocks) 162: âˆ§ result = code() 163: âˆ§ check_expectations(plan.expectations) 164: âˆ§ restore_all() 165: 166: =head3 PSEUDOCODE 167: 168: validate plan is HASH 169: apply time plan if present 170: install each mock/spy/inject from plan.mocks, building %handles 171: capture wantarray context 172: eval { run $code } 173: run expectations against %handles 174: restore all mocks (unless restore_on_scope_exit => 0) 175: restore time state 176: re-croak any exception from $code 177: return $code's result in correct context 178: 179: =cut 180: 181: sub deep_mock { 182: my ($plan, $code) = @_; 183: 184: croak 'deep_mock expects a HASHREF plan' unless ref $plan eq 'HASH'; 185: 186: my %handles; 187: 188: _apply_time_plan($plan->{time}); 189: 190: _install_mocks($plan->{mocks} // [], \%handles); 191: 192: # Preserve the caller's context through the eval block 193: my $ctx = wantarray; 194: my (@list_ret, $scalar_ret, $err); 195: 196: { 197: local $@;