Stub Laravel Package

Getting Started

Start by installing via Composer: composer require --dev codeception/stub. In your test class, use Codeception\Stub to quickly generate stubs. For example:

use Codeception\Stub;

// Create a stub of a service class
$userService = Stub::make(UserService::class, [
    'findUserById' => $mockUser,
    'isValid' => true
]);

The simplest first use case: stub a method on a real class to return a fixed value without invoking its actual logic—e.g., mocking database or API calls in a unit test.

Implementation Patterns

• Method overrides: Pass an associative array to Stub::make() to override specific methods. Use Stub::construct() for full constructor-based construction with stubbed methods.
• Dynamic return values: Supply closures instead of values for context-aware returns:

  Stub::make(Service::class, [
      'getCacheKey' => function($id) { return "cache:$id"; }
  ]);
  

• Partial mocking: Stub only selected methods while preserving the real implementation of others—ideal for testing internal logic with minimal indirection.
• Assertion on calls: Use Stub::invoke() to call a method directly and chain Stub::getInvokedMethods() or Stub::getArguments() to assert interaction history in your test.
• Integration with PHPUnit: Works seamlessly with assertNotNull($stub) or assertEquals()—no need for separate mock expectations syntax.

Gotchas and Tips

• No constructor invocation by default: Stub::make() skips constructor calls. Use Stub::construct() if dependencies need initialization.
• Argument type validation skipped: The stub doesn’t enforce method signatures or types. Ensure method names and parameter counts match your target class—typos won’t surface until runtime.
• Static methods & final classes unsupported: This package only works on instance methods of non-final classes/interfaces. Avoid stubbing for highly sealed designs.
• Debugging tip: Stub::getInvokedMethods() and Stub::getArguments($methodName) are invaluable for asserting how a stub was used—but remember to call them after the method under test.
• Extensibility: Extend Stub to create project-specific helpers (e.g., TestDouble::service()), promoting consistency across teams.
• Avoid overuse: For complex interaction assertions, revert to PHPUnit’s full mock builder—Stub shines for state-based testing, not behavior-based.