[Package] Laravel Testing Helper for Packages Development

License: MIT

Language: PHP

Keywords: laravel, php, testing

Laravel Testing Helper for Packages Development

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.

Build Status Latest Stable Version Total Downloads License

Version Compatibility

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

Getting Started

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, simply put the following in your composer.json file:

    "require-dev": {
        "orchestra/testbench": "^4.0"

And then run composer install from the terminal.

Quick Installation

Above installation can also be simplify by using the following command:

composer require --dev "orchestra/testbench=^4.0"


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.


class TestCase extends Orchestra\Testbench\TestCase

Custom Service Provider

To load your package service provider, override the getPackageProviders.

protected function getPackageProviders($app)
    return ['Acme\AcmeServiceProvider'];

Custom Aliases

To load your package alias, override the getPackageAliases.

protected function getPackageAliases($app)
    return [
        'Acme' => 'Acme\Facade'

Overriding setUp() method

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():

 * Setup the test environment.
protected function setUp()

    // Your code here

If you need to add something early in the application bootstrapping process, 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'   => '',

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:


    // ...

        <env name="DB_CONNECTION" value="testing"/>


Overriding Console Kernel

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');

Overriding HTTP 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');

Overriding Application Timezone

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';

Using Migrations

Package developer should be using ServiceProvider::loadMigrationsFrom() feature to automatically handle migrations for packages.

$this->artisan('migrate', ['--database' => 'testbench'])->run();

Using Laravel Migrations

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:


You can also set specific database connection to be used by adding --database options:

$this->loadLaravelMigrations(['--database' => 'testbench']);

Running Testing Migrations

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()

    $this->loadMigrationsFrom(__DIR__ . '/database/migrations');
    // and other test setup steps you need to perform
Notes and Considerations
  • 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 to CreateUsersTestTable or otherwise you may encounter composer class loader collision.

Using Model Factories

Testbench include withFactories() method to allow you to register custom model factory path for your test suite.



To see a working example of testbench including how to set your configuration, check the file:

Alternative Testing

There also 3rd party packages that extends Testbench:


No supported encrypter found. The cipher and / or key length are invalid.

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.


    // ...

        <env name="APP_KEY" value="AckfSECXIvnK5r28GVIWUAxmbBSjTsmF"/>


Why Testbench doesn't include any of the App classes.

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 rename App\User to Acme\User.

Missing Browser Kit support after testing on Laravel 5.4

Replace orchestra/testbench with orchestra/testbench-browser-kit and follow the installation guide.

Project Statistics

Sourcerank 20
Repository Size 689 KB
Stars 1,177
Forks 76
Watchers 23
Open issues 0
Dependencies 5
Contributors 38
Tags 91
Last updated
Last pushed

Top Contributors See all

Mior Muhammad Zaki Graham Campbell Manuel Pedrera JeroenG Dimitris Savvopoulos Ryan Durham Anton Komarev Taylor Otwell The Gitter Badger Cretu Eusebiu Bill Condo Loren Balázs Dura-Kovács Alin Eugen Deac Tuomas Koponen Lance Pioch Frankie Wittevrongel Luqman Rom Ian Olson anakadote

Packages Referencing this Repo

Laravel Testing Helper for Packages Development
Latest release v4.0.0 - Updated - 1.18K stars

Recent Tags See all

v3.8.5 September 11, 2019
v4.0.0 September 03, 2019
v3.9.0 September 03, 2019
v3.8.4 August 04, 2019
v3.8.3 May 29, 2019
v3.8.2 April 20, 2019
v3.7.7 March 16, 2019
v3.8.1 February 28, 2019
v3.8.0 February 25, 2019
v3.7.6 December 04, 2018
v3.7.5 November 15, 2018
v3.6.6 November 14, 2018
v3.7.4 October 07, 2018
v3.7.3 October 07, 2018
v3.7.2 September 13, 2018

Something wrong with this page? Make a suggestion

Last synced: 2019-09-11 07:58:10 UTC

Login to resync this repository