Using Named Routes in a Lumen Test

When writing tests in Lumen, I recently discovered that the route() helper doesn’t work with tests out-of-the-box.

I prefer to define named routes and make requests against them in my tests. If you follow the Lumen documentation, the typical way that you make a request for a test looks like this:

$this->json('GET', '/posts/1')
    ->seeJson(['title' => 'Hello World']);

Using the route helper, your test might look like this:

public function testShowingAPost()
{
    $this->json('GET', route('posts.show', ['id' => 1]))
        ->seeJson(['title' => "Hello World"]);
}

If you run the above test, here’s what the URL would return:

phpunit
PHPUnit 6.4.4 by Sebastian Bergmann and contributors.
 
.F                                                                  2 / 2 (100%)
 
Time: 48 ms, Memory: 6.00MB
 
There was 1 failure:
 
1) ExampleTest::testShowingAPost
Invalid JSON was returned from the route. Perhaps an exception was thrown?

If you inspect things a little closer, you can see the issue:

public function testShowingAPost()
{
    $this->json('GET', route('posts.show', ['id' => 1]));
    dd(
        $this->response->getContent(),
        route('posts.show', ['id' => 1])
    );
 
    $this->seeJson(['title' => "Hello World"]);
}

Interestingly, the route doesn’t look quite right, and the router is returning the / route:

phpunit
PHPUnit 6.4.4 by Sebastian Bergmann and contributors.
 
string(40) "Lumen (5.5.2) (Laravel Components 5.5.*)"
string(16) "http://:/posts/1"

It looks like the localhost part of the request isn’t being set, and the route isn’t matching. We can fix that by bootstrapping the request as Laravel does.

Bootstrapping the Request

When you run tests in the Laravel framework, the project includes CreatesApplication trait that gets called during setup which in turn bootstraps classes for the application. One of those “bootstrappers” is the SetRequestForConsole which bootstraps the request for the console.

We can replicate this functionality so that tests in Lumen have a bootstrapped request on setup, but it requires a little work on our end.

The base TestCase class eventually calls refreshApplication() during setup which in turn calls createApplication() defined in the tests/TestCase.php file.

The createApplication() method returns the application, so we can bootstrap the request at this point before returning the application and assigning it to $this->app.

Here’s what the default base TestCase class looks like that ships with Lumen:

<?php
 
abstract class TestCase extends Laravel\Lumen\Testing\TestCase
{
    /**
     * Creates the application.
     *
     * @return \Laravel\Lumen\Application
     */
    public function createApplication()
    {
        return require __DIR__.'/../bootstrap/app.php';
    }
}

Open the tests/TestCase.php file and update it to the following in order to replicate Laravel’s SetRequestForConsole:

<?php
 
use Illuminate\Http\Request;
use Laravel\Lumen\Testing\TestCase as BaseTestCase;
 
abstract class TestCase extends BaseTestCase
{
    /**
     * Creates the application.
     *
     * @return \Laravel\Lumen\Application
     */
    public function createApplication()
    {
        $app = require __DIR__.'/../bootstrap/app.php';
 
        $uri = $app->make('config')->get('app.url', 'http://localhost');
 
        $components = parse_url($uri);
 
        $server = $_SERVER;
 
        if (isset($components['path'])) {
            $server = array_merge($server, [
                'SCRIPT_FILENAME' => $components['path'],
                'SCRIPT_NAME' => $components['path'],
            ]);
        }
 
        $app->instance('request', Request::create(
            $uri, 'GET', [], [], [], $server
        ));
 
        return $app;
    }
}

First, we require the application instance by assigning require to the $app variable. Instead of returning it, we create a request instance with a default URL of http://localhost.

When we re-run our tests, you should get the route that you’d expect from the dd() call we tried earlier:

phpunit
PHPUnit 6.4.4 by Sebastian Bergmann and contributors.
 
.string(23) "{"title":"Hello World"}"
string(24) "http://localhost/posts/1"

Now the original test using the route() helper will work as expected if you remove the dd() from the test case.

Configuration

If you want to make the application URL configurable, you could update the application to import a local configuration.

Let’s first create a config folder and copy the app configuration:

$ mkdir config/
$ cp vendor/laravel/lumen-framework/config/app.php config/

Next, open the config/app.php file and add the following somewhere to the array:

'url' => env('APP_URL', 'http://localhost'),

Last, you need to register the configuration file by adding the following line to the bootstrap/app.php file after the application instance is created:

$app->configure('app');

Learn More

Lumen’s testing API is around testing HTTP APIs and thus is slightly different yet familiar. To make Lumen more lightweight than Laravel, there are some differences and tradeoffs made. For example, Lumen uses the FastRoute package for the router instead of the router that ships with Laravel.

I feel that often Lumen is misunderstood as a micro-framework that is more generic, when in fact, it’s a framework for making APIs. Once you stick within those boundaries, Lumen can be a perfect fit for building APIs. I suggest reading over the whole manual, specifically the testing documentation.