Testbench Laravel Package

Technical Evaluation

Architecture Fit

• Leverages Laravel’s ecosystem: Built atop Orchestral Testbench and Laravel Testbench Core, ensuring alignment with Laravel’s testing patterns (e.g., service providers, mocking, fixtures).
• Modular design: Abstract base classes (AbstractAppTestCase, AbstractPackageTestCase) allow customization without reinventing boilerplate.
• Dependency isolation: No invasive service providers—tests run in a clean environment, reducing side effects.
• CI/CD friendly: Pre-configured for PHPUnit, Mockery, and Laravel’s testing utilities, fitting seamlessly into existing CI pipelines.

Integration Feasibility

• Zero-configuration: No Laravel service provider registration required; tests inherit Laravel’s core testing infrastructure.
• Version compatibility: Supports Laravel 8–13, PHP 7.4–8.5, and PHPUnit 9–11, covering modern stacks. Key caveat: PHPUnit 12 is not officially supported due to volatility (workaround: pin to PHPUnit 11 or 9/10).
• Package testing focus: Optimized for Laravel package development (e.g., testing service providers, commands, jobs). Less ideal for monolithic app testing unless extended.
• Mockery integration: Provides utilities for mocking Laravel components (e.g., Mockery::mock()), reducing flakiness in isolated tests.

Technical Risk

• Breaking changes in v6.0+: Static methods in getBasePath() and getRequiredServiceProviders() may require updates to existing test suites.
• PHPUnit 12 exclusion: Risk of instability if adopting PHPUnit 12 (mitigate by sticking to PHPUnit 11 or 9/10).
• Orchestral Testbench dependency: Underlying reliance on orchestral/testbench (v3.6+) may introduce indirect risks if that package evolves.
• Limited monolithic app support: Not a drop-in replacement for Laravel’s built-in testing tools (e.g., createApplication()). Best for package-level or modular testing.

Key Questions

1. Scope of adoption:
   • Is this for package development (recommended) or app-level testing (may need extensions)?
2. PHPUnit version:
   • Will PHPUnit 12 be used? If yes, assess risk of forking or patching TestBench.
3. Legacy support:
   • Does the team need Laravel <8 or PHP <7.4? If so, downgrade to v5.7 (last version with broader support).
4. Mockery vs. PHPUnit mocks:
   • Does the team prefer Mockery’s syntax or PHPUnit’s native mocks? TestBench defaults to Mockery.
5. Custom test utilities:
   • Are additional helpers (e.g., assertInJson) needed beyond what Orchestral Testbench provides?

Integration Approach

Stack Fit

• Ideal for:
  • Laravel package development (e.g., testing service providers, commands, events).
  • Modular app testing where components are isolated (e.g., microservices, plugins).
  • Teams already using Orchestral Testbench or Laravel Testbench Core.
• Less ideal for:
  • End-to-end app testing (use Laravel’s built-in createApplication() instead).
  • Projects requiring PHPUnit 12 (risk of instability; consider alternatives like spatie/laravel-test-factories).

Migration Path

1. Assess current testing stack:
   • Audit existing test classes for compatibility with TestBench’s abstract base classes.
   • Example migration:

     // Before (Laravel native)
     class MyTest extends \Tests\TestCase {}
     
     // After (TestBench)
     class MyTest extends \GrahamCampbell\TestBench\AbstractAppTestCase {}
     

2. Update dependencies:
   • Add to composer.json:

     "require-dev": {
       "graham-campbell/testbench": "^6.3",
       "orchestral/testbench": "^3.6",
       "mockery/mockery": "^1.6"
     }
     

   • Pin PHPUnit to 9–11 (avoid 12).
3. Leverage abstract classes:
   • Extend AbstractAppTestCase for app-level tests.
   • Extend AbstractPackageTestCase for package-specific tests (e.g., service providers).
4. Replace Laravel’s createApplication():
   • Use TestBench’s getApplication() or getPackageProviders() methods.
5. Update mocking:
   • Replace partialMock() with Mockery’s mock() where applicable.

Compatibility

• Laravel 8–13: Full support (v6.3+).
• PHP 7.4–8.5: Supported (v6.3+).
• PHPUnit 9–11: Officially supported (v6.3+).
• Mockery: Required (v1.6+).
• Orchestral Testbench: Indirect dependency (v3.6+).

Sequencing

1. Phase 1: Package Testing
   • Migrate package-specific tests first (lowest risk).
   • Example: Test a service provider’s register() method.
2. Phase 2: Modular App Testing
   • Refactor tests for reusable components (e.g., commands, jobs).
3. Phase 3: CI/CD Integration
   • Update test suites in CI pipelines (ensure PHPUnit/Mockery versions match).
4. Phase 4: Custom Extensions
   • Add custom test traits or helpers if needed (e.g., database assertions).

Operational Impact

Maintenance

• Low overhead: No configuration or service providers to maintain.
• Dependency updates:
  • Monitor Orchestral Testbench and Laravel Testbench Core for breaking changes.
  • TestBench’s MIT license allows forks if needed.
• Mockery vs. PHPUnit:
  • Mockery’s syntax may require team training if unfamiliar.

Support

• Community: Active maintainer (Graham Campbell) with responsive issue tracking.
• Documentation: Lightweight but sufficient for basic usage. Examples in Graham Campbell’s other packages.
• Enterprise support: Available via Tidelift (paid).

Scaling

• Performance: Minimal runtime overhead (tests run in isolated environments).
• Parallel testing: Compatible with PHPUnit’s parallelization (no conflicts).
• Large test suites: May benefit from custom test suites or categorization (e.g., @package vs. @app tags).

Failure Modes

Ramp-Up

• Team training:
  • 1–2 hours to understand abstract base classes and Mockery.
  • Focus on AbstractPackageTestCase for package devs and AbstractAppTestCase for modular testing.
• Onboarding resources:
  • Study Graham Campbell’s other packages for usage examples.
  • Review Orchestral Testbench’s docs for advanced features.
• Migration checklist:
  1. Update composer.json.
  2. Extend abstract test classes.
  3. Replace createApplication() calls.
  4. Update mocking syntax (if using Mockery).
  5. Run tests in CI with pinned versions.