Mongomock Laravel Package

Product Decisions This Supports

• Accelerate Test-Driven Development (TDD) for MongoDB-based Features: Enable rapid iteration on backend services relying on MongoDB by eliminating flaky or slow integration tests. Critical for teams adopting TDD or shifting left on testing.

• Reduce CI/CD Costs: Replace MongoDB-dependent unit tests with in-memory mocks, cutting test execution time by ~80% (no DB spin-up, network latency, or resource contention). Justifies investment for high-test-volume pipelines.

• Build vs. Buy Decision: Buy for teams already using MongoDB in PHP. Avoid reinventing wheel for mocking logic. Build only if needing 100% API parity (this package is intentionally subsetted).

• Use Cases:

  • Microservices: Isolate MongoDB-dependent logic (e.g., CRUD, aggregations) for unit testing.
  • Legacy Refactoring: Safely modify MongoDB-heavy codebases without breaking prod.
  • Edge Cases: Test complex queries (e.g., $lookup, $facet) without real data.
  • Security: Validate input sanitization (e.g., injection tests) without exposing real data.

• Roadmap Enabler:

  • Feature Flags: Test MongoDB-dependent features behind flags before full rollout.
  • Multi-DB Support: Validate logic for MongoDB and other databases (e.g., PostgreSQL) in parallel.

When to Consider This Package

• Adopt If:

  • Your PHP backend heavily uses MongoDB (e.g., >30% of logic touches collections).
  • Unit tests are blocked by MongoDB dependencies (slow, flaky, or resource-intensive).
  • Your team prioritizes fast feedback loops (e.g., TDD, CI parallelization).
  • You need basic-to-intermediate MongoDB operations mocked (e.g., find(), updateOne(), aggregations).
  • Your stack includes PHPUnit 6–9 and PHP 7.1+.

• Look Elsewhere If:

  • You require full MongoDB API compatibility (e.g., rare operators like $graphLookup).
  • Your tests need real BSON validation (this mock uses PHP arrays).
  • You’re using MongoDB Atlas triggers or change streams (unsupported).
  • Your team lacks PHPUnit familiarity (package assumes constraint-based testing).
  • You need performance benchmarking (mocks won’t replicate real DB behavior).

• Alternatives to Evaluate:

  • Mockery: For fine-grained mocking of individual methods (but requires manual setup).
  • MongoDB’s Native Testing Tools: If using MongoDB PHP Test Library (official but less flexible).
  • In-Memory Databases: For integration tests (e.g., MongoDB Local Instance or TestContainers).

How to Pitch It (Stakeholders)

For Executives:

"This package lets our engineering team test MongoDB-dependent code 10x faster by replacing slow, flaky database tests with in-memory mocks. For example, a suite that took 2 minutes in CI now runs in 12 seconds—freeing up ~90% of test time for other critical work. It’s a low-risk, high-reward investment to accelerate feature delivery and reduce bugs in production. The MIT license means no vendor lock-in, and it’s already battle-tested in real projects."

ROI:

• Dev Velocity: Faster iterations for MongoDB-heavy features.
• Cost Savings: Reduced CI costs (e.g., AWS/GCP DB instances).
• Reliability: Catch edge cases early (e.g., malformed queries) without prod impact.

For Engineering Leaders:

*"Problem: MongoDB tests are slow, flaky, and block parallelization in CI. Solution: mongomock gives us deterministic, fast unit tests for MongoDB logic by simulating collections in memory.

Why This Over Mockery?

• Batteries-included: Handles MongoDB’s quirks (e.g., BSON, operators like $exists).
• PHPUnit-native: Works seamlessly with existing assertions (e.g., assertContains).
• Minimal Setup: Drop-in replacement for MongoDB\Collection—no refactoring needed.

Trade-offs:

• Not 100% API-complete (but covers 80% of common use cases).
• Requires PHPUnit (but most teams already use it).

Ask: Let’s pilot this on Module X (highest MongoDB dependency) and measure CI time savings. If it reduces test time by >50%, we’ll roll it out to all MongoDB-heavy services."*

For Developers:

*"Need to test MongoDB queries without spinning up a real DB? mongomock is your cheat code.

How It Works:

// Real code:
$collection->find(['age' => ['$gt' => 25]]);

// Mocked test:
$mock = new \Helmich\MongoMock\MockCollection();
$mock->insertOne(['age' => 30, 'name' => 'Alice']);
$result = $mock->find(['age' => ['$gt' => 25]]); // Returns in-memory results!
assertCount(1, $result);

Superpowers: ✅ Callbacks in queries: Test dynamic filters (e.g., ['name' => fn($n) => str_starts_with($n, 'A')]). ✅ PHPUnit constraints: Validate BSON types (e.g., assertInstanceOf(\MongoDB\BSON\Binary::class)). ✅ No DB needed: Works offline or in CI.

Gotchas:

• No real BSON validation (e.g., _id won’t auto-generate ObjectIds).
• Limited to v1 MongoDB PHP driver (but covers most CRUD/aggregation needs).

Try It: Add to composer.json under require-dev, then swap MongoDB\Collection with Helmich\MongoMock\MockCollection in tests. First PR accepted!"*