Weave Code
Testbench Core Laravel Package
orchestra/testbench-core
Testbench Core is a testing framework for Laravel package development. It boots a Laravel application inside your package repository, letting tests run Artisan commands, migrations, factories, and routes, with releases matching Laravel 6 through 13.
Testing Helper for Laravel Development
Frequently asked questions about Testbench Core
- What is orchestra/testbench-core used for?
- Testbench Core is the engine underneath Orchestra Testbench: it boots a full Laravel application inside your package repository so your test suite can exercise service providers, routes, migrations, factories, Artisan commands, config merges and Blade views without a host application. Testbench, Testbench BrowserKit, Testbench Dusk and Workbench all layer on top of it. It is intended for developers publishing distributable Laravel packages, not for testing a standalone application.
- How do I install orchestra/testbench-core in a Laravel package?
- Install it as a dev dependency with composer require --dev orchestra/testbench-core, though for normal package testing you should install orchestra/testbench instead since it pulls the matching testbench-core version automatically. Then create a tests/TestCase.php that extends Orchestra\Testbench\TestCase and implement getPackageProviders() and getPackageAliases() to register your package. Add a testbench.yaml if you need Workbench or custom bootstrap configuration, and run vendor/bin/phpunit or vendor/bin/pest.
- Which Testbench Core version supports my Laravel version?
- Version compatibility is lockstep with Laravel: Testbench Core 4.x targets Laravel 6, 5.x targets 7, 6.x targets 8, 7.x targets 9, 8.x targets 10, 9.x targets 11, 10.x targets 12, and 11.x targets 13. Because it constrains illuminate/* in require-dev, a monorepo holding packages pinned to different Laravel majors can hit Composer resolution conflicts, so plan a multi-branch CI matrix if you support several majors in parallel.
- Do I need testbench-core directly, or should I require orchestra/testbench?
- In almost all cases require orchestra/testbench and let it pull the correct testbench-core version as a transitive dev dependency. You only need to require orchestra/testbench-core directly if you are building your own Testbench extension or tooling on top of the framework. Going through Testbench also gives you the version-matched ergonomics and documentation most package authors expect.
- Can I use Testbench Core with Pest instead of PHPUnit?
- Yes. Testbench Core supports PHPUnit 9 through 13, and Pest runs on top of PHPUnit, so the same Orchestral\Testbench\TestCase base class works with Pest test files. You can write the base TestCase in PHP and use Pest's expect() syntax in the individual tests without any extra glue. Pick Pest or PHPUnit as your primary runner and keep it consistent across your package matrix.
- Does testbench-core add any dependencies to production?
- No. It is a require-dev dependency with zero production footprint and no runtime coupling for consumers of your package. Nothing from Testbench Core ends up in your published artifact, which makes adoption fully reversible and caps the blast radius of any upgrade. Your package's own require section remains untouched.
- How do I test my package's service provider, migrations and routes with Testbench?
- Extend Orchestra\Testbench\TestCase and list your providers in getPackageProviders(), with optional aliases in getPackageAliases(). Migrations, routes, config and Blade views registered by those providers are then loaded when the in-repo Laravel app boots, so you can hit routes with $this->get() and run Artisan commands or factories directly in your tests. Use defineEnvironment() to tweak configuration and defineDatabaseMigrations() to control migration behaviour per test.
- Do the @define-env and @environment-setup annotations still work in Testbench Core 11?
- No. Version 11.0.0 removed the docblock annotation system, including @define-env, @define-db, @define-route and @environment-setup, along with the Foundation\Env class, HandleTerminatingConsole, Action::pathLocation() and laravel_migration_path(). Any existing suite relying on those annotations needs a migration pass to the supported methods or attributes before upgrading. Budget for that refactor when jumping to 11.x.
- Should I use Testbench Core for testing a Laravel application instead of Laravel's built-in testing?
- No. In an application repository, Illuminate\Foundation\Testing against the app kernel already covers the same ground, and adding Testbench introduces a second bootstrapping path with its own conventions. Testbench Core is aimed at distributable packages, service providers, SDKs and Nova tools where no host application exists. If you are building an app, treat Testbench as redundant.
- Is Testbench Core actively maintained, and what are the alternatives?
- It is maintained by the Orchestral team (crynobone) with a high release cadence, typically shipping within weeks of each new Laravel or PHPUnit patch. The maintainer team is small, so continuity risk exists but is manageable at current scale, and version bumps are a recurring upgrade chore you should assign an owner. The practical alternative is a hand-rolled throwaway Laravel app for testing, which is what Testbench replaced and which costs far more to keep in sync.
Weaver
How can I help you explore Laravel packages today?