Weave Code
Testbench Core Laravel Package
orchestra/testbench-core
Orchestra Testbench Core is the foundation for testing Laravel packages. It boots a lightweight Laravel app inside your package so you can run artisan commands, migrations, routing, and more, with compatibility across Laravel 6–12.
Testing Helper for Laravel Development
Frequently asked questions about Testbench Core
- How do I use Testbench Core to test a Laravel package without installing a full Laravel app?
- Testbench Core lets you boot a minimal Laravel environment directly in your package tests. Add it via Composer (`orchestra/testbench-core`), then use `createApplication()` in your test classes to spin up a lightweight Laravel instance. This avoids requiring a separate Laravel install while still testing providers, migrations, and configurations.
- What Laravel versions does Testbench Core support, and how do I pick the right version?
- Testbench Core follows a strict version-to-Laravel mapping: Laravel 6.x uses v4.x, 7.x uses v5.x, up to Laravel 13.x with v11.x. Check the [compatibility table](https://github.com/orchestral/testbench-core#version-compatibility) and align your package’s `orchestra/testbench-core` version with your target Laravel version. For example, Laravel 12.x requires v10.x.
- Can I test Artisan commands with Testbench Core, and how?
- Yes, Testbench Core integrates with Laravel’s Artisan system. Use `$this->artisan('command:name', ['--option' => 'value'])` in your tests to execute commands. For example, to test a custom `migrate:fresh` command, call `$this->artisan('migrate:fresh')` after booting the application with `createApplication()`. This works seamlessly with Laravel’s command bus.
- What’s the difference between Testbench Core and the higher-level Testbench package?
- Testbench Core is the foundational library that boots Laravel apps in tests and handles core utilities like configuration, providers, and basic HTTP testing. The higher-level `orchestra/testbench` package builds on this core, adding convenience methods, factories, and migrations support. Use Core if you need lightweight testing; use Testbench for full-featured package testing.
- How do I mock configurations in Testbench Core for testing?
- Use the `WithConfig` attribute to mock configurations before booting the app. For example, `@WithConfig(['app.debug' => false])` sets `app.debug` to false. In v11.3.1+, this defaults to pre-boot behavior, meaning configs are loaded before the `ServiceProvider::boot()` method runs. If you need post-boot config loading, explicitly set `defer: true` in the attribute.
- Does Testbench Core support parallel testing with PHPUnit, and what are the requirements?
- Yes, Testbench Core supports parallel testing via PHPUnit’s parallel extensions. Ensure you’re using PHPUnit 12.x or later and have the `phpunit/parallel-tests` package installed. The core library includes fixes for parallel testing isolation (e.g., `flushState()` clears singletons like `Str` or `Validator`). Testbench Core v11.0.1+ explicitly addresses parallel testing compatibility.
- I’m getting errors with `nunomaduro/collision` v8.9.4+. How does Testbench Core handle this?
- Testbench Core v11.3.0+ includes a fix for `nunomaduro/collision` v8.9.4+ compatibility issues. If you’re using an older version of Collision (e.g., ^8.9.3), the fix is irrelevant. To avoid conflicts, pin `nunomaduro/collision` to `^8.9.3` in your `composer.json` if you’re not ready to upgrade. The core library itself remains unaffected by this dependency collision.
- Can I test HTTP routes and basic API responses with Testbench Core?
- Testbench Core provides basic HTTP testing capabilities, including route assertions and simple API response validation. Use `$this->get('/route')` or `$this->post('/route', ['data' => 'value'])` to send requests and assert responses. For advanced browser interactions (e.g., JavaScript, CSS selectors), consider `orchestra/testbench-browser-kit` or `orchestra/testbench-dusk`, which extend Core’s functionality.
- How do I handle database migrations and seeders in Testbench Core tests?
- Testbench Core integrates with Laravel’s migration system. Use `$this->artisan('migrate')` to run migrations before tests or `$this->artisan('migrate:fresh')` to reset the database. For seeders, call `$this->artisan('db:seed')` or target specific seeders with `--class`. The core library ensures migrations run in an isolated environment, so your tests won’t interfere with your local Laravel app.
- What are the alternatives to Testbench Core for Laravel package testing, and when should I use them?
- Alternatives include PestPHP (for simpler syntax) or custom Laravel installations (for full-featured testing). Use PestPHP if you prefer a more expressive, PHPUnit-like syntax without the overhead of Testbench. Use a full Laravel install if you need complex testing environments or third-party packages that aren’t compatible with Testbench Core. Testbench Core is ideal for lightweight, isolated package testing with minimal setup.
Weaver
How can I help you explore Laravel packages today?