Weave Code
Testbench Laravel Package
orchestra/testbench
Orchestra Testbench is the de facto helper for testing Laravel packages. It boots a lightweight Laravel app for PHPUnit/Pest, so you can run integration and feature tests against your package with minimal setup and fast feedback.
Laravel Testing Helper for Packages Development
Frequently asked questions about Testbench
- How do I install Orchestra Testbench for Laravel package testing?
- Run `composer require --dev orchestra/testbench` in your package directory. Testbench integrates seamlessly with PHPUnit or PestPHP, requiring no additional Laravel installation. Follow the [official setup guide](https://packages.tools/testbench) for configuration steps like defining a test skeleton.
- Can Testbench test Laravel packages across multiple Laravel versions (e.g., 11, 12, 13)?
- Yes, Testbench supports Laravel 11–13. Use `package_version_compare()` to conditionally run tests for specific versions. For example, gate feature tests with `if (package_version_compare('12.0.0', '<='))`. Ensure your package’s `composer.json` declares supported Laravel versions.
- What’s the difference between Testbench’s default skeleton and a custom skeleton?
- The default skeleton provides a minimal Laravel environment for basic testing. Custom skeletons (e.g., `workbench/bootstrap/providers.php`) let you inject package-specific providers, middleware, or database configurations. Use custom skeletons only if the default doesn’t meet your package’s needs, like testing spatie/laravel-permission.
- How does Testbench handle database testing for packages?
- Use the `WithFixtures` trait to load database fixtures before tests. Configure fixtures in `testbench.yaml` under `fixtures_path`. Testbench automatically rolls back transactions between tests, preventing state pollution. For complex setups, extend the `createApplication()` method to customize database connections.
- Is Testbench compatible with PestPHP, and how does it compare to PHPUnit?
- Testbench supports both PHPUnit and PestPHP. Pest users must use attributes like `#[UsesVendor]` for package-specific setup. PHPUnit remains the default, but Testbench’s core functionality (e.g., `createApplication()`) works identically. Choose one framework per project to avoid duplication.
- How do I mock external dependencies (e.g., APIs, queues) in Testbench?
- Use the `InteractsWithMockery` trait to mock dependencies. For example, mock a queue connection with `$this->mock(Queue::class)`. Testbench integrates with Mockery natively, simplifying interactions with Laravel’s service container. Avoid global mocks; scope them to specific test methods.
- Will Testbench work in CI/CD pipelines with parallel testing?
- Yes, Testbench supports parallel testing (e.g., `--parallel` in PHPUnit). Configure your CI (GitHub Actions/GitLab CI) to use `phpunit --parallel`. Monitor for database connection leaks in parallel runs; use `WithFixtures` to isolate test states. Testbench’s parallel compatibility was fixed in v10.11.0.
- What if my package uses Laravel features not supported in older versions (e.g., v11)?
- Testbench supports Laravel 11–13, but some features (e.g., `laravel_migration_path()` deprecation in v11) may require manual adjustments. Check the [compatibility matrix](https://packages.tools/testbench) and use version-specific logic like `package_version_compare()` to handle differences gracefully.
- How do I test package interactions with Laravel’s core (e.g., route binding, events)?
- Testbench boots a full Laravel environment, so you can test routes with `$this->get('/endpoint')` or events with `Event::assertDispatched()`. For service providers, use `app()->make()` to resolve bindings. Example: `$this->app->make('YourPackageService')` to test provider registrations.
- Are there alternatives to Testbench for Laravel package testing?
- Alternatives include Laravel’s built-in testing tools (limited for packages) or custom solutions like `laravel-shift/testing`. However, Testbench is the most mature, widely adopted tool for package testing, with active maintenance and Laravel version support. It reduces boilerplate and integrates with core Laravel testing patterns.
Weaver
How can I help you explore Laravel packages today?