Weave Code
Testbench Core Laravel Package
orchestra/testbench-core
Testbench Core is the foundation for Orchestra Testbench, providing a lightweight Laravel application bootstrap for package testing. Run artisan commands, migrations, factories, and routes in your test suite with versioned Laravel compatibility.
Orchestra Testbench Core is the foundation for building and running tests for Laravel packages. It provides the underlying utilities used by the Testbench ecosystem to spin up a lightweight Laravel application context inside your package repo, so you can test features as if they were running in a real app.
Use it directly or via Testbench, Testbench BrowserKit, or Testbench Dusk to validate package behavior across supported Laravel versions.
- Bootstraps a Laravel app environment for package tests
- Run Artisan commands, migrations, factories, and routing in tests
- Designed for package development workflows and CI pipelines
- Supports a clear Laravel ↔ Testbench Core compatibility matrix
- Acts as the core layer powering BrowserKit and Dusk integrations
Frequently asked questions about Testbench Core
- How do I use Testbench Core to test a Laravel package without a full application?
- Testbench Core lets you bootstrap a minimal Laravel environment directly in your package tests. Use `createApplication()` in your test class to generate a lightweight Laravel instance, then run migrations, factories, or artisan commands as needed. This avoids requiring a full Laravel app while maintaining realistic testing conditions.
- What Laravel versions does Testbench Core support, and how do I ensure compatibility?
- Testbench Core follows a 1:1 version alignment with Laravel (e.g., Testbench Core 9.x for Laravel 11.x). Check the [version compatibility table](https://github.com/orchestral/testbench-core#version-compatibility) and pin your package’s dependency to match your Laravel target version in `composer.json`. For example, use `orchestra/testbench-core:^9.0` for Laravel 11.x.
- Can I use Testbench Core with PHPUnit 13.1, and what if I’m still on PHPUnit 12.x?
- Testbench Core now fully supports PHPUnit 13.1, enabling features like `expectExceptionCode()`. If you’re on PHPUnit 12.x, you’ll encounter deprecation warnings. Update to `^13.1` in `composer.json` to avoid failures, or use `^12.0` for legacy support (though future Testbench releases may drop this).
- How do I test artisan commands with Testbench Core?
- Use the `Artisan::call()` method to execute commands in your tests. For example, `Artisan::call('migrate')` runs migrations. Testbench Core provides a full Laravel kernel, so commands like `queue:work` or custom artisan commands will work as expected. Combine this with factories or mocks for comprehensive testing.
- Is Testbench Core suitable for CI/CD pipelines, and does it support parallel testing?
- Yes, Testbench Core is optimized for CI/CD. It supports PHPUnit’s `--parallel` flag out of the box, making it ideal for fast, repeatable test runs in pipelines. The lightweight Laravel environment ensures minimal setup time, and state-flushing utilities prevent test pollution between parallel executions.
- What’s the difference between Testbench Core and the full Testbench package?
- Testbench Core is the foundation—it provides the minimal Laravel environment and core utilities. The full [Testbench package](https://github.com/orchestral/testbench) builds on this with additional helpers for testing routes, middleware, and service providers. Use Core directly if you only need artisan commands or migrations, or add Testbench for broader Laravel package testing.
- How do I customize the Laravel environment in Testbench Core for my package?
- Use `testbench.yaml` to configure the Laravel environment, such as defining custom providers, aliases, or service bindings. For advanced setups, override the `createApplication()` method in your test class. Testbench Core’s `WithFixtures` trait simplifies loading migrations, factories, and seeders, while `InteractsWithMockery` enables mocking dependencies.
- Will Testbench Core work with PestPHP, or is it PHPUnit-only?
- Testbench Core is PHPUnit-first but remains compatible with PestPHP. PestPHP tests can leverage Testbench Core’s utilities by using PHPUnit’s underlying test runner. However, some Pest-specific configurations (like `testbench.yaml`) may require adjustments. Check the [PestPHP documentation](https://pestphp.com/) for integration tips.
- Are there performance benefits to using Testbench Core over a full Laravel app in tests?
- Yes, Testbench Core boots a minimal Laravel instance, reducing memory usage and startup time compared to a full app. This is especially useful in CI/CD, where faster test execution lowers costs. The trade-off is that some edge cases (like complex service container bindings) may require manual setup, but the core functionality remains lightweight.
- How do I handle database migrations and seeders in Testbench Core tests?
- Use the `WithMigrations` trait to load migrations before tests. For seeders, call `Artisan::call('db:seed')` or manually invoke the seeder class. Testbench Core flushes the database state between tests by default, ensuring isolation. If you need persistent data, disable flushing with `$this->withoutFreshDatabase()` in your test class.
Weaver
How can I help you explore Laravel packages today?