Weave Code
Testbench Laravel Package
orchestra/testbench
Orchestra Testbench is the de-facto Laravel testing helper for package development. It boots a lightweight Laravel app for your package’s tests, making it easy to run PHPUnit/Pest suites with proper service providers, config, and environment setup.
Laravel Testing Helper for Packages Development
Frequently asked questions about Testbench
- How does Orchestra Testbench simplify testing Laravel packages compared to manual setup?
- Testbench automates Laravel’s bootstrapping—like service providers, config files, and environment variables—so you don’t need to manually create a full Laravel app for testing. It handles database migrations, Eloquent models, and even Str/Validator helpers, reducing setup time by 80% while ensuring tests run in a clean, isolated Laravel context.
- Which Laravel versions does Testbench support, and how do I check compatibility?
- Testbench v11.x supports Laravel 11–13, with backward compatibility for v10.x (Laravel 12). Check the [official docs](https://packages.tools/testbench) for version-specific guides. Always align Testbench’s version with your Laravel app’s version to avoid integration issues, especially with breaking changes like removed annotations in Laravel 11.
- Can I use Testbench with PestPHP instead of PHPUnit?
- Yes, Testbench supports both PHPUnit and PestPHP. For Pest, use `$__filename` for file resolution and leverage traits like `WithFixtures`. However, Pest support is newer, so validate edge cases (e.g., parallel tests) in your CI pipeline. The [Pest integration guide](https://packages.tools/testbench) covers setup details.
- How do I mock external dependencies (e.g., APIs, queues) in Testbench?
- Use the `InteractsWithMockery` trait for dependency mocking. For external processes like queues or CLI commands, Testbench’s `remote()` function lets you test interactions without spinning up full services. Example: `Testbench::remote('php artisan queue:work')` to simulate queue jobs in tests.
- What’s the best way to handle database fixtures in Testbench?
- Use the `WithFixtures` trait to load fixtures before tests. Testbench supports JSON/YAML fixture files and auto-rolls back transactions after each test. For complex setups, extend the trait or use `Testbench::fake()` to mock database interactions entirely. Fixtures are especially useful for testing Eloquent models or migrations.
- Will Testbench work with parallel test execution (PHPUnit --parallel)?
- Testbench supports parallel tests, but some edge cases (e.g., `WithFixtures` trait conflicts) may require manual fixes. Testbench’s isolation features reduce flakiness, but benchmark your suite in CI first. If issues arise, disable parallel mode or extend the `Testbench::afterEach()` hook to reset shared state.
- How do I test a package that uses custom service providers or middleware?
- Register providers via `Testbench::provide()` or override the `Testbench::boot()` method. For middleware, use `Testbench::actingAs()` or mock the pipeline with `Mockery`. Testbench’s `TestCase` base class ensures providers are loaded in the correct order, mimicking Laravel’s container behavior.
- Are there alternatives to Testbench for Laravel package testing?
- For lightweight needs, Laravel’s built-in `createApplication()` method suffices, but lacks Testbench’s fixtures, mocking, and isolation. Other options include `laravel-shift/blueprint` (for testing apps) or `spatie/laravel-test-factories` (for fixtures), but neither offers Testbench’s package-specific optimizations like remote testing or Str/Validator helpers.
- How do I handle cached configurations or singleton services that aren’t flushed between tests?
- Testbench flushes most Laravel components (e.g., Eloquent, Str), but cached configs or singletons require manual cleanup. Extend the `Testbench::afterEach()` hook or use `Testbench::fake()` to reset state. For example: `Cache::shouldReceive('flush')->once()` in your test setup.
- What’s the maintenance effort like for keeping Testbench updated with Laravel’s changes?
- Testbench releases align with Laravel’s major versions (e.g., v11.x for Laravel 13). Orchestral’s team actively maintains it, but breaking changes (like annotation removal in Laravel 11) may require test suite updates. Monitor the [GitHub issues](https://github.com/orchestral/testbench/issues) and Laravel’s deprecations list to plan migrations proactively.
Weaver
How can I help you explore Laravel packages today?