Mongomock Laravel Package

Technical Evaluation

Architecture Fit

• Mocking Strategy: The package provides a highly targeted solution for unit testing MongoDB interactions in PHP applications, particularly those using the official mongodb/mongodb driver. It replaces real MongoDB collections with in-memory mocks, enabling isolated, deterministic testing without external dependencies.
• API Compatibility: While not fully API-complete, it covers core CRUD operations (insertOne, updateOne, deleteOne, find, findOneAndUpdate, etc.) and query operators ($set, $inc, $push, $all, $exists, regex, etc.). This aligns well with 80% of use cases for Laravel applications interacting with MongoDB via repositories or services.
• Extensibility: The package allows custom filter logic (callbacks, PHPUnit constraints), which is valuable for testing complex queries. However, unsupported MongoDB features (e.g., aggregations, transactions) would require workarounds or custom extensions.
• Laravel Integration: Laravel’s database abstraction (e.g., MongoDB facade, Illuminate\Database\Eloquent\Model for MongoDB) could be partially mocked by replacing MongoDB\Collection instances. However, full ORM integration (e.g., MongoDB\Eloquent) would need additional effort.

Integration Feasibility

• Dependency Injection: The package is lightweight (no framework dependencies) and can be injected into Laravel services via constructor or method injection. Example:

  public function __construct(private MockCollection $mockCollection) {}
  

• Testing Framework: Works seamlessly with PHPUnit (v6–9) and Laravel’s phpunit.xml configuration. No conflicts with Laravel’s testing utilities (e.g., RefreshDatabase traits).
• BSON Support: Leverages the official mongodb/mongodb driver’s BSON types, ensuring type safety in tests. However, custom BSON extensions (e.g., MongoDB\BSON\UTCDateTime) may not be fully supported.
• Database Layer: Can mock both MongoDB\Database and MongoDB\Collection, but higher-level abstractions (e.g., Laravel’s MongoDB facade) would need manual overrides in tests.

Technical Risk

• Incomplete API: Missing features (e.g., aggregations, change streams) could break tests if the application relies on them. Mitigation: Feature flags or custom mock extensions.
• Performance Overhead: In-memory storage is fast for unit tests but could slow down large test suites if misused (e.g., mocking entire databases). Mitigation: Reset mocks between tests or use small, focused datasets.
• Behavioral Differences: Some MongoDB behaviors (e.g., auto-incrementing _id, default indexing) may not match production. Mitigation: Explicitly configure mocks to replicate production logic.
• PHPUnit Version Lock: Requires PHPUnit 6–9 (Laravel 8+ uses PHPUnit 9 by default). No risk if using Laravel’s default setup.
• Thread Safety: Not a concern for unit tests, but parallel test execution (e.g., Pest) could lead to shared state issues. Mitigation: Isolate tests or use beforeEach/afterEach hooks.

Key Questions

1. Scope of MongoDB Usage:
   • Does the application use only CRUD operations, or also aggregations, transactions, or change streams? If the latter, additional mocking logic may be needed.
2. ORM vs. Raw Queries:
   • Is MongoDB accessed via Laravel’s MongoDB Eloquent or raw mongodb/mongodb queries? Eloquent may require custom test doubles for relationships.
3. Test Isolation:
   • Are tests independent, or do they rely on shared mock state? If the latter, reset strategies must be defined.
4. CI/CD Impact:
   • Will this reduce flakiness in CI (e.g., by removing MongoDB dependency) or introduce new test maintenance overhead?
5. Long-Term Maintenance:
   • Is the package actively maintained? The last release was in 2022, but it has community contributions. Monitor for abandonware risks.

Integration Approach

Stack Fit

• Laravel Compatibility:
  • Works with Laravel 8+ (PHP 8.0+) and PHPUnit 9.
  • No conflicts with Laravel’s testing stack (e.g., Tests\TestCase, DatabaseMigrations).
  • Recommended for: Services, repositories, or controllers that directly use MongoDB\Collection.
• Alternative Abstractions:
  • For Laravel MongoDB Eloquent, consider mocking the Model layer instead (e.g., using Laravel’s createMock).
  • For complex queries, a hybrid approach (mock core operations, stub aggregations) may be needed.
• Tooling Synergy:
  • Integrates with Laravel’s phpunit.xml and Pest PHP (if using PHPUnit).
  • Can be combined with Laravel’s RefreshDatabase for hybrid tests (real DB for some tests, mocks for others).

Migration Path

1. Phase 1: Pilot in Unit Tests
   • Replace critical MongoDB-dependent unit tests with MockCollection.
   • Example:

     // Before: Real DB
     public function testUserCreation() {
         $user = User::create([...]);
         $this->assertDatabaseHas('users', [...]);
     }
     // After: Mocked
     public function testUserCreation() {
         $mockCollection = new MockCollection();
         $mockCollection->insertOne([...]);
         $this->assertEquals([...], $mockCollection->findOne([...]));
     }
     

2. Phase 2: Service Layer Mocking
   • Mock MongoDB\Collection in service classes (e.g., UserService).
   • Use dependency injection to swap real collections with mocks:

     $service = new UserService(new MockCollection());
     

3. Phase 3: Controller/HTTP Tests
   • Mock services or collections in HTTP tests to avoid DB calls:

     $this->app->instance(MockCollection::class, new MockCollection());
     

4. Phase 4: Hybrid Testing
   • Use real DB for integration tests, mocks for units.
   • Example phpunit.xml configuration:

     <env name="MOCK_MONGODB" value="true" />
     

Compatibility

• Laravel Services:
  • High compatibility if services directly use MongoDB\Collection.
  • Low compatibility if services use Laravel’s MongoDB facade (requires overriding the facade in tests).
• Query Builders:
  • Supports most query operators, but complex aggregations may fail. Workaround: Stub or extend the mock.
• BSON Types:
  • Supports core BSON types (ObjectId, Date, Binary). Custom types may need manual handling.
• PHPUnit Extensions:
  • Works with PHPUnit assertions (e.g., assertContains, assertInstanceOf) via the package’s extended filter support.

Sequencing

1. Identify Testable Components:
   • Audit codebase for MongoDB dependencies (services, repositories, controllers).
2. Prioritize High-Impact Tests:
   • Start with CRUD-heavy tests (insert/update/delete/find).
3. Extend Mocks for Gaps:
   • If missing features (e.g., $lookup), fork the package or create a wrapper.
4. Gradual Replacement:
   • Replace real DB calls in unit tests first, then HTTP tests.
5. Document Mock Behavior:
   • Add comments to tests explaining mock-specific logic (e.g., "This test uses a mock that doesn’t support $group").

Operational Impact

Maintenance

• Pros:
  • Reduces CI flakiness by eliminating MongoDB dependency.
  • Faster test execution (no DB setup/teardown).
  • Easier debugging (tests are deterministic).
• Cons:
  • Mock-specific logic may drift from production behavior over time.
  • Test maintenance if MongoDB schema or queries change (mock may need updates).
• Mitigation:
  • Regularly sync mock behavior with production changes.
  • Use feature flags to toggle between mock/real DB in tests.

Support

• Debugging:
  • Easier to debug unit tests (no network/DB latency).
  • Harder to debug if mock behavior doesn’t match production (e.g., missing $match operator).
• Onboarding:
  • Developers new to MongoDB can write tests without DB access.