Technical Evaluation

Purpose Alignment: Orchestra/Testbench is explicitly designed for Laravel package development, addressing a critical gap in Laravel’s ecosystem. It provides a standardized way to test packages in isolation, mimicking Laravel’s environment without requiring a full application setup.
Core Features:
- Isolated Testing: Simulates Laravel’s service container, middleware, and dependencies without bootstrapping a full app.
- Fixtures & Mocking: Supports database fixtures (WithFixtures trait), mocking (via InteractsWithMockery), and state management (e.g., flushing Model, Validator, Str states).
- Configuration Overrides: Allows customizing Laravel’s config, providers, and environment files per test.
- Parallel Test Support: Compatible with PHPUnit’s --parallel flag (critical for CI/CD pipelines).
- Version Agnosticism: Supports Laravel 11–13+ and PHPUnit 12–13, with backward compatibility for older versions.
Non-Functional Fit:
- Performance: Lightweight compared to full Laravel app bootstrapping (tests run in ~10–30% of the time).
- Maintainability: Actively maintained (last release: 2026-04-09), with clear deprecation cycles (e.g., removed annotations in v11.0.0).
- Extensibility: Hooks for custom skeletons, seeders, and remote command execution.

Laravel Ecosystem Lock-In: High – Designed for Laravel packages only. Non-Laravel projects or frameworks will not benefit.
Dependency Graph:
- Core Dependencies:
  - orchestra/testbench-core (v11.2.0+ for v11.x).
  - PHPUnit 12–13 (or PestPHP via traits).
  - Laravel Framework (11.50.0+ for v9.x, 12.24.0+ for v10.x, 13.x for v11.x).
- Transitive Risks:
  - mockery/mockery (for mocking) – may require PHP 8.1+.
  - symfony/process (for remote() function) – stable but version-locked.
Conflict Potential:
- Low with Laravel: Testbench overrides Laravel’s bootstrapping logic but plays nicely with its internals.
- Medium with Custom Packages: If a package relies on Laravel’s global state (e.g., cached config), Testbench’s state-flushing may cause edge cases.
- High with Non-Laravel Tools: Tools like PestPHP or custom test runners may need adapters (e.g., WithFixtures trait).

Risk Area	Severity	Mitigation
Version Skew	High	Lock Testbench to a specific minor version (e.g., `^11.1`) to avoid breaking changes (e.g., Laravel 13+ support in v11.0.0).
State Management	Medium	Testbench flushes most states, but custom package globals (e.g., static caches) may leak. Use `flushState()` or `terminate()` explicitly.
Parallel Test Failures	Medium	`--parallel` works but may fail with `WithFixtures` (fixed in v10.11.0+). Test with `phpunit --parallel` early.
Deprecated APIs	Low	v11.0.0+ removed annotations (`@define-env`, etc.). Migrate to `testbench.yaml` or traits.
CI/CD Flakiness	Low	Use `Orchestra\Testbench\terminate()` in `setUp()` to ensure clean exits in CI.

Laravel Version Strategy:
- Is the package targeting Laravel 11/12/13? Testbench’s version must align (e.g., v10.x for LTS, v11.x for Laravel 13).
- Example: For Laravel 12, use orchestra/testbench:^10.11.
Testing Scope:
- Are tests unit-only, integration-heavy, or end-to-end? Testbench excels at integration but may need supplements (e.g., PestPHP) for unit tests.
Mocking Strategy:
- Will the package use Mockery (built-in) or PHPUnit’s native mocks? Testbench defaults to Mockery but supports both.
CI/CD Pipeline:
- Does the pipeline use parallel tests? Validate --parallel compatibility early.
- Are database fixtures needed? Testbench supports WithFixtures but may require custom setup for complex schemas.
Custom Skeleton:
- Does the package need a custom Laravel skeleton (e.g., for providers/config)? Testbench supports this via testbench.yaml.
State Isolation:
- Does the package rely on global state (e.g., cached config, static classes)? Testbench flushes most but may need manual cleanup.

Integration Approach

Primary Use Case: Laravel Package Development (core focus).
Compatible Stacks:
- Laravel 11–13 (with version-matched Testbench).
- PHPUnit 12–13 or PestPHP (via traits).
- Mockery (for mocking) or PHPUnit’s native mocks.
- Database: SQLite (default), MySQL/PostgreSQL (with config overrides).
Incompatible Stacks:
- Non-Laravel PHP frameworks (Symfony, Lumen, etc.).
- Custom test runners without PHPUnit/PestPHP support.
- PHP < 8.1 (due to Mockery and Laravel dependencies).

Current State	Migration Steps
No Testing	1. Add `orchestra/testbench` to `devDependencies`.2. Extend `Orchestra\Testbench\PHPUnit\TestCase`.3. Use `createApplication()` to bootstrap Laravel.4. Write tests with `WithFixtures`/`Mockery`.
Basic PHPUnit	1. Replace `PHPUnit\Framework\TestCase` with `Orchestra\Testbench\PHPUnit\TestCase`.2. Add `use Orchestra\Testbench\Concerns\WithFixtures`.3. Configure `testbench.yaml` for fixtures/providers.
Custom Laravel App Tests	1. Replace `artisan test` with Testbench’s `createApplication()`.2. Migrate fixtures to Testbench’s `WithFixtures`.3. Remove global app state dependencies (e.g., cached config).
PestPHP	1. Use `Orchestra\Testbench\Concerns\InteractsWithPest`.2. Extend `Orchestra\Testbench\Pest\TestCase`.3. Configure `testbench.yaml` for Pest-specific overrides.

Laravel Compatibility Matrix:

Testbench Version Laravel Support PHPUnit Support

v11.x 13.x 13.1+

v10.x 12.24.0–12.55.0 12.5–13.0

v9.x 11.44.7–11.50.0 12.2–12.5
Database Compatibility:
- SQLite (default), MySQL/PostgreSQL (via .env overrides).
- Note: Testbench does not manage migrations—use WithFixtures for test data.
Tooling Compatibility:
- Parallel Tests: Supported (but validate with WithFixtures).
- PestPHP: Partial (requires InteractsWithPest trait).
- Dusk/BrowserKit: Not supported (use Laravel’s native testing for browser tests).

Phase 1: Setup

Add Testbench to composer.json:

"devDependencies": {
  "orchestra/testbench": "^11.1",
  "phpunit/phpunit": "^13.1"
}

Configure testbench.yaml (optional but recommended):

fixtures: true
seeders: ["DatabaseSeeder"]
providers: ["YourPackageServiceProvider"]