File Coverage

=head1 NAME

Test::Mockingbird::DeepMock - Declarative structured mocking and spying for Perl tests

=head1 VERSION

Version 0.14

=cut

=head1 SYNOPSIS

    use Test::Mockingbird::DeepMock qw(deep_mock);

    deep_mock(
        {
            mocks => [
                { target => 'MyApp::greet', type => 'mock', with => sub { 'hi' } },
                { target => 'MyApp::double', type => 'spy', tag => 'double_spy' },
            ],
            expectations => [
                { tag => 'double_spy', calls => 2 },
            ],
        },
        sub {
            is MyApp::greet(), 'hi', 'greet mocked';
            MyApp::double(2);
            MyApp::double(3);
        }
    );

=head1 DESCRIPTION

C<Test::Mockingbird::DeepMock> provides a declarative, data-driven way to
describe mocking, spying, injection, and expectations in Perl tests.

Instead of scattering C<mock>, C<spy>, and C<restore_all> calls throughout
your test code, DeepMock lets you define a complete mocking plan in a single
hashref, then executes your test code under that plan.

=head1 LIMITATIONS

=over 4

=item Nested deep_mock scopes are not supported

C<deep_mock> calls C<restore_all()> on exit, which removes every active mock.
A nested C<deep_mock> call will cause the inner exit to also tear down the
outer mocks.

=item inject type in mocks list

The C<inject> mock type delegates to C<Test::Mockingbird::inject()>. Because
C<inject()> builds a sub that returns the C<with> value verbatim, passing a
coderef via C<with> stores the coderef itself; it is not called on each
access. To inject a factory, wrap it explicitly.

=back

=head1 PLAN STRUCTURE

=head2 C<mocks>

ArrayRef of mock specs. Each entry:

    {
        target => 'Package::method',
        type   => 'mock' | 'spy' | 'inject',
        with   => sub { ... },
        tag    => 'identifier',
    }

=head2 C<expectations>

ArrayRef of expectation specs. Each entry:

    {
        tag        => 'spy_tag',
        calls      => $n,
        args_like  => [ [qr/pat1/, qr/pat2/], ... ],
        args_eq    => [ ['exact', 'args'],    ... ],
        args_deeply => [ [$struct],           ... ],
        never      => 1,
        order      => [ 'A::m1', 'B::m2' ],
    }

The C<order> key is processed after all per-spy expectations and does not
require a C<tag>.

=head2 C<globals>

Optional:

    globals => { restore_on_scope_exit => 1 }

=head2 C<time>

Optional time-travel plan applied before mocks are installed:

    time => {
        freeze  => '2025-01-01T00:00:00Z',
        travel  => '2025-01-03T00:00:00Z',
        advance => [ 2 => 'minutes' ],
        rewind  => [ 1 => 'hour'    ],
    }

=head1 TROUBLESHOOTING

=head2 "Not enough arguments for deep_mock"

DeepMock uses C<($$)> prototype. Use C<deep_mock( {...}, sub { ... } )>.

=head2 My mocks are not restored

Check C<globals => { restore_on_scope_exit => 0 }> has not been set.

=head1 METHODS

=head2 deep_mock

Run a code block with a set of mocks and expectations applied.

=head3 API SPECIFICATION

=head4 Input (Params::Validate::Strict schema)

    $plan -- HashRef with keys: mocks, expectations, globals, time
    $code -- CodeRef

=head4 Output (Returns::Set schema)

    returns: whatever $code returns (context-sensitive)

=head3 MESSAGES

  "deep_mock expects a HASHREF plan" -- first arg is not a hashref

=head3 FORMAL SPECIFICATION

    deep_mock ≙
      âˆ€ plan : HashRef; code : CodeRef •
        pre  ref(plan) = 'HASH'
        post apply_time(plan.time)
             âˆ§ install_mocks(plan.mocks)
             âˆ§ result = code()
             âˆ§ check_expectations(plan.expectations)
             âˆ§ restore_all()

=head3 PSEUDOCODE

    validate plan is HASH
    apply time plan if present
    install each mock/spy/inject from plan.mocks, building %handles
    capture wantarray context
    eval { run $code }
    run expectations against %handles
    restore all mocks (unless restore_on_scope_exit => 0)
    restore time state
    re-croak any exception from $code
    return $code's result in correct context

=cut

=head1 SUPPORT

Please report bugs at L<https://github.com/nigelhorne/Test-Mockingbird/issues>.

=head1 AUTHOR

Nigel Horne, C<< <njh at nigelhorne.com> >>

=head1 SEE ALSO

=over 4

=item * L<Test::Mockingbird>

=item * L<Test::Mockingbird::Async>

=item * L<Test::Mockingbird::TimeTravel>

=back

=head1 REPOSITORY

L<https://github.com/nigelhorne/Test-Mockingbird>

=head1 LICENCE AND COPYRIGHT

Copyright 2026 Nigel Horne.

Usage is subject to GPL2 licence terms.

=cut