Eloquent Mockery Laravel Package

Product Decisions This Supports

• Accelerate test-driven development (TDD) for Laravel applications by reducing coupling between Eloquent models and database dependencies, enabling faster iteration and refactoring.
• Shift-left testing strategy by allowing developers to mock Eloquent queries without requiring a repository pattern, lowering the barrier to writing unit tests for database interactions.
• Improve CI/CD pipeline efficiency by reducing flaky tests tied to database state, enabling parallel test execution and faster feedback loops.
• Support legacy code modernization by isolating database-dependent logic in tests, making it easier to incrementally adopt new architectures (e.g., CQRS, event sourcing).
• Build vs. Buy Decision: Justify buying this lightweight package over building custom mocking utilities, especially for teams already using Laravel/Eloquent, by leveraging its MIT license and active maintenance (last release: 2024-06-21).
• Roadmap Enabler: Prioritize features like real-time data sync or complex query validation by first ensuring robust test coverage via mocking, reducing regression risks.

When to Consider This Package

• Adopt when:

  • Your Laravel app relies heavily on Eloquent for core logic, and unit tests are blocked by database dependencies.
  • Your team lacks a repository pattern or wants to avoid adding abstraction layers for testing purposes.
  • You’re migrating legacy code to a testable architecture and need a low-friction way to mock queries.
  • CI/CD bottlenecks are caused by slow or flaky database-dependent tests.
  • You’re building APIs or microservices where Eloquent interactions need to be tested independently of the database.

• Look elsewhere if:

  • Your team already uses a repository pattern (this package is designed as an alternative to it).
  • You need advanced mocking (e.g., for relationships, events, or observers), which may require custom extensions.
  • Your project uses non-Eloquent ORMs (e.g., Doctrine, Query Builder).
  • You’re in a high-security environment where MIT-licensed packages require additional vetting (though this is minimal risk).
  • You prefer behavior-driven testing (BDD) frameworks like Laravel’s createMock() or PHPUnit’s built-in mocking, which may suffice for simpler cases.

How to Pitch It (Stakeholders)

For Executives/Product Leaders:

*"This package lets our Laravel backend team write faster, more reliable tests by mocking database queries directly in Eloquent—without adding complexity. It’s like giving developers a ‘pause button’ for the database during testing, which:

• Reduces CI/CD wait times by 30–50% (no more flaky tests tied to DB state).
• Lowers technical debt by making refactoring safer (e.g., schema changes, API updates).
• Saves costs by avoiding custom mocking solutions (MIT-licensed, actively maintained). For a one-time integration effort, it’s a high-ROI tool to future-proof our backend development."*

For Engineering Teams:

*"Eloquent Mockery lets you test Eloquent models in isolation without:

• Writing a repository layer (avoids over-engineering).
• Dealing with database setup/teardown in unit tests.
• Relying on createMock() or manual mocking for queries.

Key benefits: ✅ Write tests 2–3x faster for query-heavy logic (e.g., where, join, with). ✅ No database required for unit tests—run tests in parallel or on CI instantly. ✅ Seamless integration with Laravel’s testing helpers (e.g., assertDatabaseHas can still be used alongside). ✅ Future-proof: Works with Laravel 9+ and PHP 8.1+.

Example use case:

// Before: Flaky test tied to DB
public function test_user_has_posts() {
    $user = User::factory()->create();
    $posts = Post::where('user_id', $user->id)->get();
    // ...
}

// After: Isolated, fast test
public function test_user_has_posts() {
    $mockQuery = Mockery::mock('overload:App\Models\Post');
    $mockQuery->shouldReceive('where')->with('user_id', 1)->andReturnSelf();
    $mockQuery->shouldReceive('get')->andReturn([new Post()]);
    // Test logic...
}

Ask: Where are our slowest/flakiest tests? This could cut those down to seconds."*