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