Phpunit Extensions Laravel Package

Technical Evaluation

Architecture Fit

• Mocking Paradigm Alignment: The package enforces explicit mocking, which aligns with modern testing best practices (e.g., avoiding implicit assumptions in mocks). This is particularly valuable for Laravel applications where loose mocking can lead to flaky integration tests (e.g., API tests with unstubbed service container methods).
• Laravel Compatibility: While Laravel’s TestCase is not extended directly, the trait-based approach (StrictMocking) allows seamless integration without modifying Laravel’s core test classes. This avoids vendor lock-in risks.
• Static Analysis Synergy: The PHPStan integration enforces strict mocking at development time, reducing runtime surprises. This complements Laravel’s existing tooling (e.g., Pest, Laravel Pint) and aligns with shift-left testing principles.

Integration Feasibility

• Low Friction for New Projects: Ideal for greenfield Laravel projects or test suites where strict mocking is a priority. The TestCase extension provides a zero-configuration opt-in.
• Backward Compatibility Challenges: Existing test suites relying on unstubbed mock defaults (e.g., createMock() returning null for unstubbed methods) will require refactoring. The pardoned config mitigates this but adds maintenance overhead.
• Dependency Isolation: The package is dev-only and MIT-licensed, posing no runtime conflicts with Laravel’s production dependencies. However, PHPUnit 12/13 and PHP 8.3/8.4 requirements may necessitate infrastructure upgrades.

Technical Risk

• Test Suite Disruption: Enforcing strict mocking may break existing tests if they depend on unstubbed method defaults. Mitigation strategies:
  • Gradual Adoption: Start with new test files or low-risk modules.
  • CI Gating: Fail builds only on new violations (via PHPStan) to avoid mass refactoring.
• False Positives: PHPStan rules might flag dynamic method calls (e.g., method_exists() checks) as violations. The pardoned config helps, but teams must curate exceptions carefully.
• Early Development: The package’s 2026 release date suggests active maintenance, but the "early development" warning implies potential API changes. Monitor the repo for breaking updates post-adoption.
• Laravel-Specific Risks:
  • Service Container Mocks: Laravel’s MockApplicationServices or MockFacade may need updates if they rely on unstubbed defaults.
  • Test Helpers: Custom helpers (e.g., partialMock()) might conflict with strict mocking rules.

Key Questions

1. Test Suite Health: What percentage of tests rely on unstubbed mock defaults? Is the effort to refactor justified by the expected reliability gains?
2. CI/CD Maturity: Can PHPStan rules be integrated into the pipeline without slowing down feedback loops (e.g., GitHub Actions cache, parallelization)?
3. Team Alignment: Is the team committed to strict mocking as a long-term practice, or is this a temporary enforcement to catch issues?
4. Laravel Ecosystem: Does the team use custom test helpers (e.g., createMockWithPartial()) or third-party packages that might conflict with strict mocking?
5. Infrastructure Readiness: Is the team using PHP 8.3+ and PHPUnit 12+? If not, what’s the upgrade path?
6. Performance Impact: Will strict mocking introduce noticeable overhead in test execution (e.g., stricter type checks during mock creation)?

Integration Approach

Stack Fit

• PHPUnit Version: The package targets PHPUnit 12/13 (and PHP 8.3/8.4). Laravel’s default PHPUnit version (typically 9.x) may require an upgrade. Verify compatibility with:
  • Laravel’s phpunit.xml configuration.
  • Third-party packages that pin PHPUnit versions (e.g., laravel/pint).
• Laravel Synergy:
  • Works alongside Laravel’s testing tools (e.g., HttpTests, DatabaseMigrations) but requires explicit opt-in per test class.
  • No conflicts with Laravel’s service container or Facade mocking, provided tests are updated to use createStrictMock().
• Toolchain Compatibility:
  • PHPStan: Must be configured in phpstan.neon (no Laravel-specific conflicts). Ensure the rules.neon file is included in the project’s static analysis pipeline.
  • IDE Support: Configure PHPStorm/VSCode to recognize the PHPStan rules for inline feedback. Example:

    // .phpstorm.meta.php
    {
      "rules": {
        "vendors/lendable/phpunit-extensions/phpstan/rules.neon": {
          "level": "warning"
        }
      }
    }
    

  • Pest Integration: If using Pest, the trait can be added to TestCase or individual test files, but Pest’s Mock facade may need updates to support createStrictMock().

Migration Path

1. Preparation Phase:
   • Audit: Run PHPStan with the package’s rules to identify violations:

     composer require --dev phpstan/phpstan lendable/phpunit-extensions
     vendor/bin/phpstan analyse --level=max --memory-limit=1G
     

   • Upgrade: Update phpunit.php and composer.json to meet PHPUnit/PHP version requirements:

     "require-dev": {
       "phpunit/phpunit": "^12.0",
       "php": "^8.3"
     }
     

2. Pilot Phase:
   • New Tests: Create a new test file extending Lendable\PHPUnitExtensions\TestCase or using the StrictMocking trait.
   • Existing Tests: For critical modules, use the trait in new test classes and gradually migrate.
3. Refactoring Phase:
   • Replace Mocks: Update createMock() calls to createStrictMock() in existing tests.
   • Stub Explicitly: Add stubs for all methods called on mocks, even if defaults were previously acceptable.
   • Handle Exceptions: Use the pardoned config for tests that cannot be immediately fixed:

     lendable_phpunit:
       enforceStrictMocking:
         pardoned:
           - App\Tests\Feature\LegacyTest
     

4. Enforcement Phase:
   • CI Gating: Fail builds on new violations (remove pardoned exclusions incrementally).
   • Documentation: Update team docs to reflect the new mocking standards.

Compatibility

• Laravel-Specific:
  • Service Container: If tests mock container bindings (e.g., MockApplicationServices), ensure all resolved methods are stubbed explicitly.
  • Facades: Update MockFacade usage to align with strict mocking (e.g., stub shouldReceive() calls).
  • Test Helpers: Review custom helpers (e.g., partialMock()) for conflicts. Example fix:

    // Before (loose)
    $mock = $this->partialMock(MyService::class, ['method1']);
    
    // After (strict)
    $mock = $this->createStrictMock(MyService::class);
    $mock->method('method1')->willReturn(...);
    

• Third-Party Packages: Test packages that use mocks (e.g., Mockery, Brain\Monkey) for compatibility. If they rely on unstubbed defaults, consider wrapping their mocks with createStrictMock().

Sequencing

Operational Impact

Maintenance

• Pros:
  • **Reduced Flak