Testbench Component is a simple package that has been designed to help you write tests for your Laravel package, especially when there is routing involved.
- Version Compatibility
- Getting Started
- Installation
- Usage
- Example
- Alternative Testing
- Troubleshoot
- Changelog
Laravel | Testbench |
---|---|
5.0.x | 3.0.x |
5.1.x | 3.1.x |
5.2.x | 3.2.x |
5.3.x | 3.3.x |
5.4.x | 3.4.x |
5.5.x | 3.5.x |
5.6.x | 3.6.x |
5.7.x | 3.7.x |
5.8.x | 3.8.x |
6.x | 4.x |
7.x | 5.x |
8.x | 6.x |
Before going through the rest of this documentation, please take some time to read the Package Development section of Laravel's own documentation, if you haven't done so yet.
To install through composer, run the following command from terminal:
composer require --dev "orchestra/testbench"
To use Testbench Component, all you need to do is extend Orchestra\Testbench\TestCase
instead of PHPUnit\Framework\TestCase
. The fixture app
booted by Orchestra\Testbench\TestCase
is predefined to follow the base application skeleton of Laravel 6.
<?php
class TestCase extends Orchestra\Testbench\TestCase
{
//
}
To load your package service provider, override the getPackageProviders
.
protected function getPackageProviders($app)
{
return ['Acme\AcmeServiceProvider'];
}
To load your package alias, override the getPackageAliases
.
protected function getPackageAliases($app)
{
return [
'Acme' => 'Acme\Facade'
];
}
Since Orchestra\Testbench\TestCase
replace Laravel's Illuminate\Foundation\Testing\TestCase
, if you need your own setUp()
implementation, do not forget to call parent::setUp()
and make sure proper declaration compatibility:
/**
* Setup the test environment.
*/
protected function setUp(): void
{
parent::setUp();
// Your code here
}
If you need to add something early in the application bootstrapping process (which executed between registering service providers and booting service providers) you could use the getEnvironmentSetUp()
method:
/**
* Define environment setup.
*
* @param \Illuminate\Foundation\Application $app
* @return void
*/
protected function getEnvironmentSetUp($app)
{
// Setup default database to use sqlite :memory:
$app['config']->set('database.default', 'testbench');
$app['config']->set('database.connections.testbench', [
'driver' => 'sqlite',
'database' => ':memory:',
'prefix' => '',
]);
}
New in Testbench Core 4.4 is the ability to use @environment-setup
annotation to customise use of getEnvironmentSetUp
specific for each test.
protected function useMySqlConnection($app)
{
$app->config->set('database.default', 'mysql');
}
protected function useSqliteConnection($app)
{
$app->config->set('database.default', 'sqlite');
}
/**
* @environment-setup useMySqlConnection
*/
public function testItCanBeConnectedWithMySql()
{
// write your tests
}
/**
* @environment-setup useSqliteConnection
*/
public function testItCanBeConnectedWithSqlite()
{
// write your tests
}
To reduce setup configuration, you could use testing
database connection (:memory:
with sqlite
driver) via setting it up under getEnvironmentSetUp()
or by defining it under PHPUnit Configuration File:
<phpunit>
// ...
<php>
<env name="DB_CONNECTION" value="testing"/>
</php>
</phpunit>
You can easily swap Console Kernel for application bootstrap by overriding resolveApplicationConsoleKernel()
method:
/**
* Resolve application Console Kernel implementation.
*
* @param \Illuminate\Foundation\Application $app
* @return void
*/
protected function resolveApplicationConsoleKernel($app)
{
$app->singleton('Illuminate\Contracts\Console\Kernel', 'Acme\Testbench\Console\Kernel');
}
You can easily swap HTTP Kernel for application bootstrap by overriding resolveApplicationHttpKernel()
method:
/**
* Resolve application HTTP Kernel implementation.
*
* @param \Illuminate\Foundation\Application $app
* @return void
*/
protected function resolveApplicationHttpKernel($app)
{
$app->singleton('Illuminate\Contracts\Http\Kernel', 'Acme\Testbench\Http\Kernel');
}
You can also easily override application default timezone, instead of the default "UTC"
:
/**
* Get application timezone.
*
* @param \Illuminate\Foundation\Application $app
* @return string|null
*/
protected function getApplicationTimezone($app)
{
return 'Asia/Kuala_Lumpur';
}
Package developer should be using ServiceProvider::loadMigrationsFrom()
feature to automatically handle migrations for packages.
$this->artisan('migrate', ['--database' => 'testbench'])->run();
By default Testbench doesn't execute the default Laravel migrations which include users
and password_resets
table. In order to run the migration just add the following command:
$this->loadLaravelMigrations();
You can also set specific database connection to be used by adding --database
options:
$this->loadLaravelMigrations(['--database' => 'testbench']);
To run migrations that are only used for testing purposes and not part of your package, add the following to your base test class:
/**
* Setup the test environment.
*/
protected function setUp(): void
{
parent::setUp();
$this->loadMigrationsFrom(__DIR__ . '/database/migrations');
// and other test setup steps you need to perform
}
- Your migration files has to suite Laravel's convention, e.g.
0000_00_00_000000_create_package_test_tables.php
. - You may choose to put your migrations folder in
tests/database/
. - You may choose to change your test-migrations class name to be different from the published class names, e.g. from
CreateUsersTable
toCreateUsersTestTable
or otherwise you may encounter composer class loader collision.
Laravel 8 shipped with class based Factories which you can autoload using Composer. This is only needed when you want to retain the legacy model factories.
Testbench include withFactories()
method to allow you to register custom model factory path for your test suite.
$this->withFactories(__DIR__.'/factories');
You also need to require the following:
composer require --dev "laravel/legacy-factories:^1.0.4"
To see a working example of testbench including how to set your configuration, check the file:
Introduced in Testbench
5.6
and6.1
as experimental feature
testbench
console command allows you to run artisan commands outside of Laravel. e.g:
./vendor/bin/testbench migrate
or
./vendor/bin/testbench passport:install
This would allows you to setup the testing environment before running phpunit
instead of executing everything from within TestCase::setUp()
. Behind the scene the command will boot a basic skeleton Laravel application similar to Testbench boot Laravel for testing.
In order for the testbench
command to understand any required service providers or environment variables to be used when executing the "artisan" command you need to add the following testbench.yaml
file on the project root directory.
env:
- DB_CONNECTION="mysql"
- DB_USERNAME="homestead"
- DB_PASSWORD="secret"
providers:
- Laravel\Passport\PassportServiceProvider
- The command is currently designed to help testing, however you might be able to run other feature to help package development such as running
ide-helper:models
etc. - The command wouldn't work for file stubbing as the generated file will be based on the booted Laravel application and not your package directories.
- The command is an experimental feature and will only be likely to be marked as stable in Testbench 7. Please try it out and report back any issues.
There also 3rd party packages that extends Testbench:
RuntimeException: No supported encrypter found. The cipher and / or key length are invalid.
This error would only occur if your test suite require usages of the encrypter. To solve this you can add a dummy APP_KEY
or use a specific key to your application/package phpunit.xml
.
<phpunit>
// ...
<php>
<env name="APP_KEY" value="AckfSECXIvnK5r28GVIWUAxmbBSjTsmF"/>
</php>
</phpunit>
The reason Testbench remove all the classes is to make sure that you would never depends on it when developing Laravel Packages. Classes such as App\Http\Controllers\Controller
and App\User
are simple to be added but the problems with these classes is that it can be either:
- Removed, moved to other location such as
App\Models\User
, or - Renamed using
php artisan app:name Acme
which would renameApp\User
toAcme\User
.
If you plan to use the new HTTP Client in Laravel 7, you need to include guzzlehttp/guzzle
to your package's composer.json
:
composer require "guzzlehttp/guzzle:^6.3.1"
We can't guarantee that any requirements in
laravel/laravel
will always be maintained as it is. Developer may remove any of the optional requirements such asguzzlehttp/guzzle
,fideloper/proxy
,fruitcake/laravel-cors
orlaravel/tinker
.
Starting from Laravel 8, Illuminate\Database\Eloquent\Factory
has been pushed to laravel/legacy-factories
package in favor of class based Factories.
As package developers, you have the options to either split the package version for Laravel 8 from previous Laravel version and use the new class based Factories or require laravel/legacy-factories
to make release while supporting lower versions as well. In both cases the packages will needs to require PHP 7.3 and above.
Note: The minimum PHP requirements is due to
laravel/legacy-factories
depending onilluminate/macroable
.
In order to use legacy factories on packages development supporting Laravel 8 and below without splitting the release you can opt to use the following:
composer require --dev "laravel/legacy-factories:^1.0.4"
Next you need to ensure orchestra/testbench
uses the minimum version supporting laravel/legacy-factories
to avoid issues on CI environment (if you're running tests on each version of Laravel or using --prefer-lowest
).
Laravel | Minimum Versions |
---|---|
5.5 | 3.5.6 |
5.6 | 3.6.7 |
5.7 | 3.7.8 |
5.8 | 3.8.6 |
6.x | 4.8.0 |
7.x | 5.2.0 |
E.g: If you need to support minimum Laravel 5.6 here how the requirement should look like in composer.json
:
{
"require-dev": {
"orchestra/testbench": "~3.6.7 || ~3.7.8 || ~3.8.6 || ^4.8 || ^5.2 || ^6.0"
}
}
You need to check all your TestCase and ensure that there is no call to $this->withFactories()
, autoloading class based factories is handled by Composer and withFactories()
is only needed for legacy based factories.
Replace orchestra/testbench
with orchestra/testbench-browser-kit
and follow the installation guide.