Testbench Core Laravel Package

Technical Evaluation

Architecture Fit

• Core Purpose Alignment: Testbench Core is a test isolation framework for Laravel packages, enabling TPMs to validate package functionality in an isolated Laravel environment. This aligns perfectly with the need for reliable, reproducible testing in Laravel-based products, especially for packages with complex dependencies (e.g., auth, APIs, migrations).
• Modular Design: The package is modular (core + extensions like BrowserKit/Dusk) and version-locked to Laravel, ensuring compatibility without forcing upgrades. This reduces technical debt for TPMs managing long-lived products.
• Isolation Mechanisms: Key features like TerminatingConsole, fixture loading, and state flushing (e.g., Str, Validator) address common Laravel testing pain points (e.g., shared state pollution, artisan command testing). This is critical for packages with global state dependencies (e.g., caching, queues).
• Package-Specific Testing: The testbench.yaml config and WithFixtures trait enable package-aware testing, which is essential for TPMs building composable Laravel packages (e.g., auth systems, payment gateways).

Integration Feasibility

• Low Friction for Laravel Ecosystem: Since Testbench Core is Laravel-native, integration requires minimal setup:
  • Add to composer.json (e.g., "orchestra/testbench-core": "^11.0").
  • Extend Orchestra\Testbench\PHPUnit\TestCase for base tests.
  • Configure testbench.php for package-specific needs (e.g., custom migrations, providers).
• PHPUnit/PestPHP Agnostic: Works with both PHPUnit and PestPHP, giving TPMs flexibility to adopt modern testing tools (e.g., Pest’s fluent syntax) without rewriting tests.
• Artisan/Command Testing: Built-in support for testing Artisan commands, migrations, and routes reduces boilerplate for TPMs shipping CLI tools (e.g., php artisan mypackage:generate).

Technical Risk

• Version Locking: TPMs must strictly align Testbench Core versions with Laravel versions (e.g., Laravel 12 → Testbench 10.x). Mismatches risk breaking tests. Mitigation: Use ^ in composer.json and pin to a specific minor version (e.g., 10.x-dev) for stability.
• Parallel Testing Quirks: The WithFixtures trait has known issues with --parallel in PHPUnit (fixed in v11.0.1+). TPMs using parallel test suites must:
  • Ensure Testbench Core ≥ v11.0.1.
  • Avoid shared fixtures in parallel runs or use refreshDatabase() per test.
• Deprecation Burden: Recent releases (v11.0.0+) removed deprecated annotations (@define-env, @define-db) and classes (Env, HandleTerminatingConsole). TPMs with legacy test suites may need refactoring.
  • Mitigation: Audit tests for deprecated annotations early; leverage testbench.yaml for modern config.
• Windows Symlink Issues: Fixed in v10.8.0, but TPMs using Windows CI (e.g., GitHub Actions) should test on Windows to avoid edge cases with asset symlinks.
• State Management: While Testbench flushes Str, Validator, and JsonResource states, custom package state (e.g., singleton services) may still leak. TPMs must:
  • Use refreshApplication() or refreshMigrations() sparingly.
  • Mock global services (e.g., App::singleton() bindings) explicitly.

Key Questions for TPMs

1. Laravel Version Strategy:
   • Is the product locked to a specific Laravel LTS version (e.g., 10.x)? If so, Testbench Core versioning is straightforward.
   • If using multiple Laravel versions (e.g., 11.x and 12.x), will Testbench Core’s version matrix create maintenance overhead?
2. Testing Scope:
   • Are tests package-focused (e.g., validating a payment gateway package) or application-focused (e.g., testing a full Laravel app)? Testbench Core excels at the former.
   • Do tests require JavaScript interaction? If yes, consider Testbench Dusk (but note ChromeDriver dependencies).
3. CI/CD Impact:
   • Will parallel test execution (--parallel) be used? If yes, confirm Testbench Core ≥ v11.0.1.
   • Are tests running on Windows CI? Validate symlink behavior post-v10.8.0.
4. Legacy Test Migration:
   • Do existing tests use deprecated annotations (@define-env)? Budget time for migration to testbench.yaml.
   • Are there custom test utilities (e.g., helper functions) that rely on deprecated Testbench internals?
5. Performance:
   • Will tests bootstrap a full Laravel app per test? For slow packages (e.g., heavy migrations), consider:
     • Caching the Laravel kernel ($app->setKernel()).
     • Using WithFixtures to avoid full app bootstrapping where possible.
6. Support for Custom Skeletons:
   • Does the product use a custom Laravel skeleton (e.g., for package development)? Testbench Core supports this via testbench.php config, but TPMs must validate:
     • Configuration merging works as expected.
     • Custom providers/services are loaded correctly.

Integration Approach

Stack Fit

• Primary Use Case: Laravel Package Development.
  • Ideal for TPMs building composable packages (e.g., auth, payments, APIs) that need isolated testing.
  • Less suited for full-stack Laravel apps (use Laravel’s built-in testing tools instead).
• Testing Tools Compatibility:

  Tool	Compatibility	Notes
  PHPUnit	✅ Full support (v12/13)	Use Orchestra\Testbench\PHPUnit\TestCase.
  PestPHP	✅ Partial (via testbench.yaml)	Requires config for Pest integration.
  Laravel Dusk	✅ (via Testbench Dusk)	Adds ChromeDriver dependency.
  BrowserKit	✅ (via Testbench BrowserKit)	No JS support.

• Dependency Conflicts:
  • Low risk for most packages. Testbench Core is self-contained and avoids conflicts with Laravel core.
  • Potential conflict: If the package or app uses custom PHPUnit extensions (e.g., custom assertions), Testbench’s PHPUnit integration may need adjustment.

Migration Path

1. Assessment Phase:
   • Audit existing tests for:
     • Deprecated annotations (@define-env, @define-db).
     • Custom test utilities tied to Laravel internals.
     • Parallel test assumptions.
   • Document Laravel version and Testbench Core version alignment.
2. Setup:
   • Install Testbench Core:

     composer require --dev orchestra/testbench-core ^11.0
     

   • Create testbench.php (if using custom config):

     <?php
     return [
         'migrations' => 'path/to/migrations',
         'providers' => [
             // Custom providers
         ],
         'seeders' => true, // Enable if using database seeding
     ];
     

   • Extend the base test case:

     use Orchestra\Testbench\PHPUnit\TestCase;
     
     class MyPackageTest extends TestCase { ... }
     

3. Incremental Migration:
   • Phase 1: Migrate unit tests (e.g., service classes, repositories) to Testbench.
   • Phase 2: Migrate integration tests (e.g., migrations, commands, routes).
   • Phase 3: Migrate legacy tests (e.g., replace @define-env with testbench.php config).
4. CI/CD Adjustments:
   • Update test commands:

     # GitHub Actions example
     - run: php artisan testbench
     

   • Add Testbench-specific environment variables (e.g., TESTBENCH_USER_MODEL).

Compatibility

• Laravel Core: Testbench Core is version-locked to Laravel (e.g., v11.x → Laravel 13.x). TPMs must ensure their product’s Laravel version matches the Testbench Core version.
• Database: Supports SQLite (default), MySQL, PostgreSQL, and SQLite in-memory databases. TPMs using custom database connections must configure testbench.php:

  'connections' => [
      'mysql' => [
          'driver' => 'mysql',
          'host' => env('DB_HOST', '127.0.0.1'),
      ],
  ],
  

• Service Providers: Testbench disables Laravel’s default providers by default (configurable via