Testbench Component is a simple package that is supposed to help you write tests for your Laravel package, especially when there is routing involved.

• Version Compatibility
• Installation
• Usage
• Example
• Alternative Testing
• Troubleshoot

To install through composer, simply put the following in your composer.json file:

{
    "require-dev": {
        "orchestra/testbench": "~3.0"
    }
}

And then run composer install from the terminal.

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

composer require --dev "orchestra/testbench=~3.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 5.

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

/**
 * Setup the test environment.
 */
public function setUp()
{
    parent::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'   => '',
    ]);
}

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

Testbench include a custom migrations command that support realpath option instead of the basic relative path option, this would make it easier for you to run database migrations during testing by just including the full realpath to your package database/migration folder.

$this->artisan('migrate', [
    '--database' => 'testbench',
    '--realpath' => realpath(__DIR__.'/../migrations'),
]);

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

$this->withFactories(__DIR__.'/factories');

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

• Testing with Database.

There also 3rd party packages that extends Testbench Component on CodeCeption and PHPSpec:

• Testbench with CodeCeption
• Testbench with PHPSpec

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

This error would only occur if your test suite require actual usage 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 error might pop-up when testing routes with Request::old() or old() helper inside the requested view. This is due to Testbench not loading the default global middleware made available with Laravel.

To avoid breaking Backward Compatibility (BC) under 3.1 please add the following code under your setUp or getEnvironmentSetUp method.

$app->make('Illuminate\Contracts\Http\Kernel')->pushMiddleware('Illuminate\Session\Middleware\StartSession');