Prophecy Phpunit Laravel Package

Getting Started

1. Install with composer require --dev phpspec/prophecy-phpunit.
2. Extend PHPUnit\Framework\TestCase and use Prophecy\PhpUnit\ProphecyTrait;.
3. Call $this->prophesize(ServiceInterface::class) to generate test doubles.
4. Define expectations before calling ->reveal() — e.g., $mock->process()->willReturn('ok').
5. Inject the revealed object into your SUT: new ServiceConsumer($mock->reveal()).

Implementation Patterns

• Interface-Driven Prophesizing: Prefer prophesizing interfaces (prophesize(LoggerInterface::class)) for looser coupling and clearer intent.
• Argument Constraints for Robustness: Use Argument::type(), Argument::exact(), or custom predicates via Argument::that() to avoid brittle string/identity matches.
• Early Expectation Setup: Define all expectations immediately after prophesizing and before reveal() to prevent "unexpected call" exceptions from missed setup.
• Hybrid Mocking: Mix Prophecy doubles for external dependencies (e.g., APIs, queues) with native PHPUnit mocks for simple value objects — but isolate tests by avoiding both in the same assertion flow.
• PHPStan/PSALM Safety: Leverage strict return types from prophesize() (v2.3+) for IDE autocomplete and static analysis — no more @var annotations for doubles.

Gotchas and Tips

• reveal() Must Follow Expectations: Calling reveal() prematurely (e.g., in constructor args before setting willReturn()) silently breaks prophecy tracking — build expectations first.
• Assertion Counter Sync: Prophecy calls auto-increment PHPUnit’s assertion counter (since v1.1), but only when expectations use shouldBeCalled()/shouldNotBeenCalled() or shouldHaveBeenCalled() after execution — for willReturn()-only cases, verify with --testdox or manual assertion counts.
• Trait Name Collisions: Since it’s a trait, avoid naming conflicts — if your test class defines prophesize(), it will override the trait method (silent failure risk).
• Version Locking: For legacy projects on PHP 8.1, pin phpspec/prophecy-phpunit: ^2.0; newer versions (v2.2+) require PHP ≥8.2 and Prophecy ≥1.18.
• PHPUnit Compatibility Matrix: Verify version alignment:
  • PHPUnit 13 → ^2.5
  • PHPUnit 12 → ^2.4
  • PHPUnit 11 → ^2.2
  • PHPUnit 10.1+ → ^2.1
• Debugging Tips: Run with -vvv and capture prophecy-specific output; failures show which argument constraints failed, often clearer than PHPUnit’s native mocks.