coolify/.claude/skills/laravel-actions/references/testing-fakes.md

Testing and Action Fakes

Scope

Use this reference when isolating action orchestration in tests.

Recap

• Summarizes all AsFake helpers (mock, partialMock, spy, shouldRun, shouldNotRun, allowToRun).
• Clarifies when to assert execution versus non-execution.
• Covers fake lifecycle checks/reset (isFake, clearFake).
• Provides branch-oriented test examples for orchestration confidence.

Core methods

• mock()
• partialMock()
• spy()
• shouldRun()
• shouldNotRun()
• allowToRun()
• isFake()
• clearFake()

Recommended pattern

• Test handle(...) directly for business rules.
• Test entrypoints for wiring/orchestration.
• Fake only at the boundary under test.

Methods provided (AsFake trait)

mock

Swaps the action with a full mock.

FetchContactsFromGoogle::mock()
    ->shouldReceive('handle')
    ->with(42)
    ->andReturn(['Loris', 'Will', 'Barney']);

partialMock

Swaps the action with a partial mock.

FetchContactsFromGoogle::partialMock()
    ->shouldReceive('fetch')
    ->with('some_google_identifier')
    ->andReturn(['Loris', 'Will', 'Barney']);

spy

Swaps the action with a spy.

$spy = FetchContactsFromGoogle::spy()
    ->allows('handle')
    ->andReturn(['Loris', 'Will', 'Barney']);

// ...

$spy->shouldHaveReceived('handle')->with(42);

shouldRun

Helper adding expectation on handle.

FetchContactsFromGoogle::shouldRun();

// Equivalent to:
FetchContactsFromGoogle::mock()->shouldReceive('handle');

shouldNotRun

Helper adding negative expectation on handle.

FetchContactsFromGoogle::shouldNotRun();

// Equivalent to:
FetchContactsFromGoogle::mock()->shouldNotReceive('handle');

allowToRun

Helper allowing handle on a spy.

$spy = FetchContactsFromGoogle::allowToRun()
    ->andReturn(['Loris', 'Will', 'Barney']);

// ...

$spy->shouldHaveReceived('handle')->with(42);

isFake

Returns whether the action has been swapped with a fake.

FetchContactsFromGoogle::isFake(); // false
FetchContactsFromGoogle::mock();
FetchContactsFromGoogle::isFake(); // true

clearFake

Clears the fake instance, if any.

FetchContactsFromGoogle::mock();
FetchContactsFromGoogle::isFake(); // true
FetchContactsFromGoogle::clearFake();
FetchContactsFromGoogle::isFake(); // false

Examples

Orchestration test

it('runs sync contacts for premium teams', function () {
    SyncGoogleContacts::shouldRun()->once()->with(42)->andReturnTrue();

    ImportTeamContacts::run(42, isPremium: true);
});

Guard-clause test

it('does not run sync when integration is disabled', function () {
    SyncGoogleContacts::shouldNotRun();

    ImportTeamContacts::run(42, integrationEnabled: false);
});

Checklist

• Assertions verify call intent and argument contracts.
• Fakes are cleared when leakage risk exists.
• Branch tests use shouldRun() / shouldNotRun() where clearer.

Common pitfalls

• Over-mocking and losing behavior confidence.
• Asserting only dispatch, not business correctness.

References

• https://www.laravelactions.com/2.x/as-fake.html