Weave Code
Testbench Laravel Package
orchestra/testbench
Orchestra Testbench is the de-facto helper for writing tests for Laravel packages, providing a lightweight Laravel application skeleton so you can verify your package's service providers, routes, and config.
Laravel Testing Helper for Packages Development
Frequently asked questions about Testbench
- What is Orchestra Testbench used for in Laravel package development?
- Orchestra Testbench provides a lightweight, disposable Laravel application skeleton so you can boot and test a package's service providers, routes, commands, migrations, and configuration in isolation. It is intended for package development, not for testing a full Laravel application in place of the app's own test suite. Teams commonly use it for shared domain libraries, SDK or driver packages, and installable modules.
- How do I install Orchestra Testbench for a Laravel package?
- Install it as a development dependency with composer require --dev orchestra/testbench. Then extend Orchestra Testbench's TestCase in your package's base test case, or use the Pest equivalent, and declare providers, environment, migrations, and seeders in testbench.yaml. Because it is require-dev only, it does not enter your production artifact.
- Which Laravel versions does Orchestra Testbench support?
- Testbench majors track Laravel majors one-to-one: Testbench 9.x targets Laravel 11, 10.x targets Laravel 12, and 11.x targets Laravel 13. Recent releases also set minimum Laravel patch floors, for example v10.8.0 requires Laravel 12.40.0 and v11.3.0 requires Laravel 13.32.0, so check the release notes before upgrading. PHPUnit minor support has ranged from 12.1 through 13.3 across recent releases.
- Does Orchestra Testbench work with Pest as well as PHPUnit?
- Yes. Testbench supplies the application under test and works alongside your existing test runner, so you can extend the Testbench TestCase from PHPUnit or use the Pest equivalent. The choice of PHPUnit or Pest is a house-style and CI concern rather than a Testbench limitation. Check the supported PHPUnit minor versions for your chosen Testbench major.
- How do I configure providers, migrations, routes, and seeders with Orchestra Testbench?
- Declare the package's service providers, environment variables, migrations, seeders, and routes in testbench.yaml, and use the provided attributes and traits such as WithConfig, WithMigrations, WithFixtures, and UsesVendor where they fit. A thin base TestCase that registers your package provider keeps individual tests small. Workbench also provides commands such as package:test, package:purge-skeleton, and asset-symlink for package-shaped development.
- Why does composer update fail with Orchestra Testbench version conflicts?
- Testbench majors are locked to Laravel majors and minor releases often raise the minimum Laravel patch floor, so an unattended Laravel patch upgrade can break Composer resolution. A Testbench minor can therefore force a framework patch bump on your schedule. Pin compatible versions in require-dev and review Testbench release notes before running broad composer update.
- Is Orchestra Testbench a production dependency?
- No. Orchestra Testbench is a require-dev-only package that provides a test application kernel; it is not a runtime dependency and should not enter the production artifact. The architectural blast radius is close to zero when it is scoped per package. Keep it out of production installs by using --no-dev in deployment builds.
- What are alternatives to Orchestra Testbench for testing Laravel packages?
- Hand-rolling a Laravel container bootstrap per package is the main alternative, but bespoke test harnesses tend to accumulate and go unmaintained. Orchestra Testbench is the acknowledged de-facto standard in this niche, and Laravel's own package development documentation is the prerequisite reading. If you have no package-shaped code, Testbench's fit is weak and you may not need an alternative at all.
- Who maintains Orchestra Testbench and is single-maintainer risk a concern?
- Orchestra Testbench is open source under the MIT license and is widely used for Laravel package testing, but single-maintainer concentration is a real bus-factor concern to note at review. Plan ownership for Laravel-major upgrade tickets, especially when Laravel 13 to 14 lands. Track release notes and transitive dependencies such as testbench-core and Orchestra Sidekick.
- How do I upgrade from Orchestra Testbench 9.x to 10.x or 11.x?
- Upgrade sequentially through Testbench majors, for example 9.x to 10.x to 11.x, rather than skipping a major. Recent majors have removed deprecated helper functions and annotations such as @define-env, @environment-setup, @define-db, and @define-route, which can silently break older suites. Convert tests to the current base TestCase, attributes, and traits, and check the minimum Laravel patch floor for each target release.
Weaver
How can I help you explore Laravel packages today?