RefreshDatabase

IlluminateFoundationTestingRefreshDatabase is imported at the top of every newly generated test file, and it’s the most commonly used database migration trait. This trait was introduced in Laravel 5.5 and is only available in projects running on that version or later.

The point of this, and the other database traits, is to ensure your database tables are correctly migrated at the start of each test.

RefreshDatabase takes two steps to do this. First, it runs your migrations on your test database once at the beginning of each test run (when you run phpunit, not for each individual test method). And second, it wraps each individual test method in a database transaction and rolls back the transaction at the end of the test.

That means you have your database migrated for your tests and cleared out fresh after each test runs, without having to run your migrations again before every test—making this the fastest possible option. When in doubt, stick with this.

WithoutMiddleware

If you import IlluminateFoundationTestingWithoutMiddleware into your test class, it will disable all middleware for any test in that class. This means you won’t have to worry about the authentication middleware, or CSRF protection, or anything else that might be useful in the real application but distracting in a test.

If you’d like to disable middleware for just a single method instead of the entire test class, call $this->withoutMiddleware() at the top of the method for that test.

DatabaseMigrations

If you import the IlluminateFoundationTestingDatabaseMigrations trait instead of the RefreshDatabase trait, it will run your entire set of database migrations fresh before each test. Laravel makes this happen by running php artisan migrate:fresh in the setUp() method before every test runs.

DatabaseTransactions

IlluminateFoundationTestingDatabaseTransactions, on the other hand, expects your database to be properly migrated before your tests start. It wraps every test in a database transaction, which it rolls back at the end of each test. This means that, at the end of each test, your database will be returned to the exact same state it was in prior to the test.

TestCase

Any application tests should extend the TestCase class (tests/TestCase.php) that’s included with Laravel by default. Your application’s TestCase class will extend the abstract IlluminateFoundationTestingTestCase class, which brings in quite a few goodies.

The first thing the two TestCase classes (yours and its abstract parent) do is handle booting the Illuminate application instance for you, so you have a fully bootstrapped application available. They also “refresh” the application between each test, which means they’re not entirely recreating the application between tests, but rather making sure you don’t have any data lingering.

The parent TestCase also sets up a system of hooks that allow callbacks to be run before and after the application is created, and imports a series of traits that provide you with methods for interacting with every aspect of your application. These traits include InteractsWithContainer, MakesHttpRequests, and InteractsWithConsole, and they bring in a broad variety of custom assertions and testing methods.

As a result, your application tests have access to a fully bootstrapped application instance and application-test-minded custom assertions, with a series of simple and powerful wrappers around each to make them easy to use.

That means you can write $this->get('/')->assertStatus(200) and know that your application is actually behaving as if it were responding to a normal HTTP request, and that the response is being fully generated and then checked as a browser would check it. It’s pretty powerful stuff, considering how little work you had to do to get it running.

Testing Basic Pages with $this->get() and Other HTTP Calls

At the very basic level, Laravel’s HTTP testing allows you to make simple HTTP requests (GET, POST, etc.) and then make simple assertions about their impact or response.

There are more tools we’ll cover later (in “A Quick Introduction to BrowserKit Testing” and “Testing with Dusk”) that allow for more complex page interactions and assertions, but let’s start at the base level. Here are the calls you can make:

• $this->get($uri, $headers = [])

• $this->post($uri, $data = [], $headers = [])

• $this->put($uri, $data = [], $headers = [])

• $this->patch($uri, $data = [], $headers = [])

• $this->delete($uri, $data = [], $headers = [])

• $this->option($uri, $data = [], $headers = [])

These methods are the basis of the HTTP testing framework. Each takes at least a URI (usually relative) and headers, and all but get() also allow for passing data along with the request.

And, importantly, each returns a $response object that represents the HTTP response. This response object is almost exactly the same as an Illuminate Response object, the same thing we return out of our controllers. However, it’s actually an instance of IlluminateFoundationTestingTestResponse, which wraps a normal Response with some assertions for testing.

Take a look at Example 12-8 to see a common usage of post() and a common response assertion.

public function test_it_stores_new_packages()
{
    $response = $this->post(route('packages.store'), [
        'name' => 'The greatest package',
    ]);

    $response->assertOk();
}

In most examples like Example 12-8, you’ll also test that the record exists in the database and shows up on the index page, and maybe that it doesn’t test successfully unless you define the package author and are logged in. But don’t worry, we’ll get to all of that. For now, you can make calls to your application routes with many different verbs and make assertions against both the response and the state of your application afterward. Great!

Testing JSON APIs with $this->getJson() and Other JSON HTTP Calls

You can also do all of the same sorts of HTTP tests with your JSON APIs. There are convenience methods for that, too:

• $this->getJson($uri, $headers = [])

• $this->postJson($uri, $data = [], $headers = [])

• $this->putJson($uri, $data = [], $headers = [])

• $this->patchJson($uri, $data = [], $headers = [])

• $this->deleteJson($uri, $data = [], $headers = [])

• $this->optionJson($uri, $data = [], $headers = [])

These methods work just the same as the normal HTTP call methods, except they also add JSON-specific Accept, CONTENT_LENGTH, and CONTENT_TYPE headers. Take a look at Example 12-9 to see an example.

public function test_the_api_route_stores_new_packages()
{
    $response = $this->postJSON(route('api.packages.store'), [
        'name' => 'The greatest package',
    ], ['X-API-Version' => '17']);

    $response->assertOk();
}

Assertions Against $response

There are 40 assertions available on the $response object in Laravel 5.8, so I’ll refer you to the testing docs for details on all of them. Let’s look at a few of the most important and most common ones:

$response->assertOk()

Asserts that the response’s status code is 200:

$response = $this->get('terms');
$response->assertOk();

$response->assertSuccessful()

While assertOk() asserts that the code is a 200, assertSuccessful() checks if the code is any anything in the 200 group:

$response = $this->post('articles', [
    'title' => 'Testing Laravel',
    'body'  => 'My article about testing Laravel',
]);
// Assuming this returns 201 CREATED...
$response->assertSuccessful();

$response->assertUnauthorized()

Asserts that the response’s status code is 401:

$response = $this->patch('settings', ['password' => 'abc']);
$response->assertUnauthorized();

$response->assertForbidden()

Asserts that the response’s status code is 403:

$response = $this->actingAs($normalUser)->get('admin');
$response->assertForbidden();

$response->assertNotFound()

Asserts that the response’s status code is 404:

$response = $this->get('posts/first-post');
$response->assertNotFound();

$response->assertStatus($status)

Asserts that the response’s status code is equal to the provided $status:

$response = $this->get('admin');
$response->assertStatus(401); // Unauthorized

$response->assertSee($text) and $response->assertDontSee($text)

Asserts that the response contains (or doesn’t contain) the provided $text:

$package = factory(Package::class)->create();
$response = $this->get(route('packages.index'));
$response->assertSee($package->name);

$response->assertJson(_array $json)

Asserts that the passed array is represented (in JSON format) in the returned JSON:

$this->postJson(route('packages.store'), ['name' => 'GreatPackage2000']);
$response = $this->getJson(route('packages.index'));
$response->assertJson(['name' => 'GreatPackage2000']);

$response->assertViewHas($key, $value = null)

Asserts that the view on the visited page had a piece of data available at $key, and optionally checks that the value of that variable was $value:

$package = factory(Package::class)->create();
$response = $this->get(route('packages.show'));
$response->assertViewHas('name', $package->name);

$response->assertSessionHas($key, $value = null)

Asserts that the session has data set at $key, and optionally checks that the value of that data is $value:

$response = $this->get('beta/enable');
$response->assertSessionHas('beta-enabled', true);

$response->assertSessionHasInput($key, $value = null)

Asserts that the given keys and values are flashed in the session array input. This is helpful when testing the validation error returns the correct old values.

$response = $this->post('users', ['name' => 'Abdullah']);
// Assuming it errored, check that the entered name is flashed;
$response->assertSessionHasInput(['name' => 'Abdullah']);

$response->assertSessionHasErrors()

With no parameters, asserts that there’s at least one error set in Laravel’s special errors session container. Its first parameter can be an array of key/value pairs that define the errors that should be set and its second parameter can be the string format that the checked errors should be formatted against, as demonstrated here:

// Assuming the "/form" route requires an email field, and we're
// posting an empty submission to it to trigger the error
$response = $this->post('form', []);

$response->assertSessionHasErrors();
$response->assertSessionHasErrors([
    'email' => 'The email field is required.',
 ]);
$response->assertSessionHasErrors(
    ['email' => '<p>The email field is required.</p>'],
    '<p>:message</p>'
);

If you’re working with named error bags, you can pass the error bag name as the third parameter.

$response->assertCookie($name, $value = null)

Asserts that the response contains a cookie with name $name, and optionally checks that its value is $value:

$response = $this->post('settings', ['dismiss-warning']);
$response->assertCookie('warning-dismiss', true);

$response->assertCookieExpired($name)

Asserts that the response contains a cookie with name $name and that it is expired:

$response->assertCookieExpired('warning-dismiss');

$response->assertCookieNotExpired($name)

Asserts that the response contains a cookie with name $name and that it is not expired:

$response->assertCookieNotExpired('warning-dismiss');

$response->assertRedirect($uri)

Asserts that the requested route returns a redirect to the given URI:

$response = $this->post(route('packages.store'), [
    'email' => 'invalid'
]);

$response->assertRedirect(route('packages.create'));

For each of these assertions, you can assume that there are many related assertions I haven’t listed here. For example, in addition to assertSessionHasErrors() there are also assertSessionHasNoErrors() and assertSessionHasErrorsIn() assertions; as well as assertJson(), there are also assertJsonCount(), assertJsonFragment(), assertJsonMissing(), assertJsonMissingExact(), assertJsonStructure(), and assertJsonValidationErrors() assertions. Again, take a look at the docs and make yourself familiar with the whole list.

Authenticating Responses

One piece of your application it’s common to test with application tests is authentication and authorization. Most of the time your needs will be met with the actingAs() chainable method, which takes a user (or other Authenticatable object, depending on how your system is set up), as you can see in Example 12-10.

public function test_guests_cant_view_dashboard()
{
    $user = factory(User::class)->states('guest')->create();
    $response = $this->actingAs($user)->get('dashboard');
    $response->assertStatus(401); // Unauthorized
}

public function test_members_can_view_dashboard()
{
    $user = factory(User::class)->states('member')->create();
    $response = $this->actingAs($user)->get('dashboard');
    $response->assertOk();
}

public function test_members_and_guests_cant_view_statistics()
{
    $guest = factory(User::class)->states('guest')->create();
    $response = $this->actingAs($guest)->get('statistics');
    $response->assertStatus(401); // Unauthorized

    $member = factory(User::class)->states('member')->create();
    $response = $this->actingAs($member)->get('statistics');
    $response->assertStatus(401); // Unauthorized
}

public function test_admins_can_view_statistics()
{
    $user = factory(User::class)->states('admin')->create();
    $response = $this->actingAs($user)->get('statistics');
    $response->assertOk();
}

A Few Other Customizations to Your HTTP Tests

If you’d like to set session variables on your requests, you can also chain withSession():

$response = $this->withSession([
    'alert-dismissed' => true,
])->get('dashboard');

If you’d prefer to set your request headers fluently, you can chain withHeaders():

$response = $this->withHeaders([
    'X-THE-ANSWER' => '42',
])->get('the-restaurant-at-the-end-of-the-universe');

Handling Exceptions in Application Tests

Usually, an exception that’s thrown inside your application when you’re making HTTP calls will be captured by Laravel’s exception handler and processed as it would be in normal application. So, the test and route in Example 12-11 would still pass, since the exception would never bubble up the whole way to our test.

// routes/web.php
Route::get('has-exceptions', function () {
    throw new Exception('Stop!');
});

// tests/Feature/ExceptionsTest.php
public function test_exception_in_route()
{
    $this->get('/has-exceptions');

    $this->assertTrue(true);
}

In a lot of cases, this might make sense; maybe you’re expecting a validation exception and you want it to be caught like it would normally be by the framework.

But if you want to temporarily disable the exception handler, that’s an option; just run $this->withoutExceptionHandling(), as shown in Example 12-12.

// tests/Feature/ExceptionsTest.php
public function test_exception_in_route()
{
    // Now throws an error
    $this->withoutExceptionHandling();

    $this->get('/has-exceptions');

    $this->assertTrue(true);
}

And if for some reason you need to turn it back on (maybe you turned it off in setUp() but want it back on for just one test), you can run $this->withExceptionHandling().

Debugging Responses

In Laravel 5.8+, you can easily dump out the headers with dumpHeaders() or the body with dump(). It’s also possible to do this before 5.8, but it’s a bit more work.

$response = $this->get('/');

// Before 5.8
dump($response->headers->all());
dump(json_decode($response->getContent())); // json
dump($response->getContent()); // not json

// In 5.8+
$response->dumpHeaders();
$response->dump();

Using Model Factories in Tests

Model factories are amazing tools that make it easy to seed randomized, well-structured database data for testing (or other purposes). You’ve already seen them in use in several examples in this chapter.

We’ve already covered them in depth, so check out “Model Factories” to learn more.

Seeding in Tests

If you use seeds in your application, you can run the equivalent of php artisan db:seed by running $this->seed() in your test.

You can also pass a seeder class name to just seed that one class:

$this->seed(); // Seeds all
$this->seed(UserSeeder::class); // Seeds users

Event Fakes

Let’s use event fakes as our first example of how Laravel makes it possible to mock its internal systems. There are likely going to be times when you want to fake events just for the sake of suppressing their actions. For example, suppose your app pushes notifications to Slack every time a new user signs up. You have a “user signed up” event that’s dispatched when this happens, and it has a listener that notifies a Slack channel that a user has signed up. You don’t want those notifications to go to Slack every time you run your tests, but you might want to assert that the event was sent, or the listener was triggered, or something else. This is one reason for faking certain aspects of Laravel in our tests: to pause the default behavior and instead make assertions against the system we’re testing.

Let’s take a look at how to suppress these events by calling the fake() method on IlluminateSupportFacadesEvent, as shown in Example 12-14.

public function test_controller_does_some_thing()
{
    Event::fake();

    // Call controller and assert it does whatever you want without
    // worrying about it pinging Slack
}

Once we’ve run the fake() method, we can also call special assertions on the Event facade: namely, assertDispatched() and assertNotDispatched(). Take a look at Example 12-15 to see them in use.

public function test_signing_up_users_notifies_slack()
{
    Event::fake();

    // Sign user up

    Event::assertDispatched(UserJoined::class, function ($event) use ($user) {
        return $event->user->id === $user->id;
    });

    // Or sign multiple users up and assert it was dispatched twice

    Event::assertDispatched(UserJoined::class, 2);

    // Or sign up with validation failures and assert it wasn't dispatched

    Event::assertNotDispatched(UserJoined::class);
}

Note that the (optional) closure we’re passing to assertDispatched() makes it so we’re not just asserting that the event was dispatched, but also that the dispatched event contains certain data.

Bus and Queue Fakes

The Bus facade, which represents how Laravel dispatches jobs, works just like Event. You can run fake() on it to disable the impact of your jobs, and after faking it you can run assertDispatched() or assertNotDispatched().

The Queue facade represents how Laravel dispatches jobs when they’re pushed up to queues. Its available methods are assertedPushed(), assertPushedOn(), and assertNotPushed().

Take a look at Example 12-16 to see how to use both.

public function test_popularity_is_calculated()
{
    Bus::fake();

    // Synchronize package data...

    // Assert a job was dispatched
    Bus::assertDispatched(
        CalculatePopularity::class,
        function ($job) use ($package) {
            return $job->package->id === $package->id;
        }
    );

    // Assert a job was not dispatched
    Bus::assertNotDispatched(DestroyPopularityMaybe::class);
}

public function test_popularity_calculation_is_queued()
{
    Queue::fake();

    // Synchronize package data...

    // Assert a job was pushed to any queue
    Queue::assertPushed(CalculatePopularity::class, function ($job) use ($package) {
        return $job->package->id === $package->id;
    });

    // Assert a job was pushed to a given queue named "popularity"
    Queue::assertPushedOn('popularity', CalculatePopularity::class);

    // Assert a job was pushed twice
    Queue::assertPushed(CalculatePopularity::class, 2);

    // Assert a job was not pushed
    Queue::assertNotPushed(DestroyPopularityMaybe::class);
}

Mail Fakes

The Mail facade, when faked, offers four methods: assertSent(), assertNotSent(), assertQueued(), and assertNotQueued(). Use the Queued methods when your mail is queued and the Sent methods when it’s not.

Just like with assertDispatched(), the first parameter will be the name of the mailable and the second parameter can be empty, the number of times the mailable has been sent, or a closure testing that the mailable has the right data in it. Take a look at Example 12-17 to see a few of these methods in action.

public function test_package_authors_receive_launch_emails()
{
    Mail::fake();

    // Make a package public for the first time...

    // Assert a message was sent to a given email address
    Mail::assertSent(PackageLaunched::class, function ($mail) use ($package) {
        return $mail->package->id === $package->id;
    });

    // Assert a message was sent to given email addresses
    Mail::assertSent(PackageLaunched::class, function ($mail) use ($package) {
        return $mail->hasTo($package->author->email) &&
               $mail->hasCc($package->collaborators) &&
               $mail->hasBcc('[email protected]');
    });

    // Or, launch two packages...

    // Assert a mailable was sent twice
    Mail::assertSent(PackageLaunched::class, 2);

    // Assert a mailable was not sent
    Mail::assertNotSent(PackageLaunchFailed::class);
}

All of the messages checking for recipients (hasTo(), hasCc(), and hasBcc()) can take either a single email address or an array or collection of addresses.

Notification Fakes

The Notification facade, when faked, offers two methods: assertSentTo() and assertNothingSent().

Unlike with the Mail facade, you’re not going to test who the notification was sent to manually in a closure. Rather, the assertion itself requires the first parameter be either a single notifiable object or an array or collection of them. Only after you’ve passed in the desired notification target can you test anything about the notification itself.

The second parameter is the class name for the notification, and the (optional) third parameter can be a closure defining more expectations about the notification. Take a look at Example 12-18 to learn more.

public function test_users_are_notified_of_new_package_ratings()
{
    Notification::fake();

    // Perform package rating...

    // Assert author was notified
    Notification::assertSentTo(
        $package->author,
        PackageRatingReceived::class,
        function ($notification, $channels) use ($package) {
            return $notification->package->id === $package->id;
        }
    );

    // Assert a notification was sent to the given users
    Notification::assertSentTo(
        [$package->collaborators], PackageRatingReceived::class
    );

    // Or, perform a duplicate package rating...

    // Assert a notification was not sent
    Notification::assertNotSentTo(
        [$package->author], PackageRatingReceived::class
    );
}

You may also find yourself wanting to assert that your channel selection is working—that notifications are sent via the right channels. You can test that as well, as you can see in Example 12-19.

public function test_users_are_notified_by_their_preferred_channel()
{
    Notification::fake();

    $user = factory(User::class)->create(['slack_preferred' => true]);

    // Perform package rating...

    // Assert author was notified via Slack
    Notification::assertSentTo(
        $user,
        PackageRatingReceived::class,
        function ($notification, $channels) use ($package) {
            return $notification->package->id === $package->id
                && in_array('slack', $channels);
        }
    );

Storage Fakes

Testing files can be extraordinarily complex. Many traditional methods require you to actually move files around in your test directories, and formatting the form input and output can be very complicated.

Thankfully, if you use Laravel’s Storage facade, it’s infinitely simpler to test file uploads and other storage-related items. Example 12-20 demonstrates.

public function test_package_screenshot_upload()
{
    Storage::fake('screenshots');

    // Upload a fake image
    $response = $this->postJson('screenshots', [
        'screenshot' => UploadedFile::fake()->image('screenshot.jpg'),
    ]);

    // Assert the file was stored
    Storage::disk('screenshots')->assertExists('screenshot.jpg');

    // Or, assert a file does not exist
    Storage::disk('screenshots')->assertMissing('missing.jpg');
}

A Quick Introduction to Mocking

Essentially, mocks and other similar tools make it possible to create an object that in some way mimics a real class, but for testing purposes isn’t the real class. Sometimes this is done because the real class is too difficult to instantiate just to inject it into a test, or maybe because the real class communicates with an external service.

As you can probably tell from the examples that follow, Laravel encourages working with the real application as much as possible—which means avoiding too great of a dependence on mocks. But they have their place, which is why Laravel includes Mockery, a mocking library, out of the box, and is why many of its core services offer faking utilities.

A Quick Introduction to Mockery

Mockery allows you to quickly and easily create mocks from any PHP class in your application. Imagine you have a class that depends on a Slack client, but you don’t want the calls to actually go out to Slack. Mockery makes it simple to create a fake Slack client to use in your tests, like you can see in Example 12-21.

// app/SlackClient.php
class SlackClient
{
    // ...

    public function send($message, $channel)
    {
        // Actually sends a message to Slack
    }
}

// app/Notifier.php
class Notifier
{
    private $slack;

    public function __construct(SlackClient $slack)
    {
        $this->slack = $slack;
    }

    public function notifyAdmins($message)
    {
        $this->slack->send($message, 'admins');
    }
}

// tests/Unit/NotifierTest.php
public function test_notifier_notifies_admins()
{
    $slackMock = Mockery::mock(SlackClient::class)->shouldIgnoreMissing();

    $notifier = new Notifier($slackMock);
    $notifier->notifyAdmins('Test message');
}

There are a lot of elements at work here, but if you look at them one by one, they make sense. We have a class named Notifier that we’re testing. It has a dependency named SlackClient that does something that we don’t want it to do when we’re running our tests: it sends actual Slack notifications. So we’re going to mock it.

We use Mockery to get a mock of our SlackClient class. If we don’t care about what happens to that class—if it should simply exist to keep our tests from throwing errors—we can just use shouldIgnoreMissing():

$slackMock = Mockery::mock(SlackClient::class)->shouldIgnoreMissing();

No matter what Notifier calls on $slackMock, it’ll just accept it and return null.

But take a look at test_notifier_notifies_admins(). At this point, it doesn’t actually test anything.

We could just keep shouldIgnoreMissing() and then write some assertions below it. That’s usually what we do with shouldIgnoreMissing(), which makes this object a “fake” or a “stub.”

But what if we want to actually assert that a call was made to the send() method of SlackClient? That’s when we drop shouldIgnoreMissing() and reach for the other should* methods (Example 12-22).

public function test_notifier_notifies_admins()
{
    $slackMock = Mockery::mock(SlackClient::class);
    $slackMock->shouldReceive('send')->once();

    $notifier = new Notifier($slackMock);
    $notifier->notifyAdmins('Test message');
}

shouldReceive('send')->once() is the same as saying “assert that $slackMock will have its send() method called once and only once.” So, we’re now asserting that Notifier, when we call notifyAdmins(), makes a single call to the send() method on SlackClient.

We could also use something like shouldReceive('send')->times(3) or shouldReceive('send')->never(). We can define what parameter we expect to be passed along with that send() call using with(), and we can define what to return with andReturn():

$slackMock->shouldReceive('send')->with('Hello, world!')->andReturn(true);

What if we wanted to use the IoC container to resolve our instance of the Notifier? This might be useful if Notifier had several other dependencies that we didn’t need to mock.

We can do that! We just use the instance() method on the container, as in Example 12-23, to tell Laravel to provide an instance of our mock to any classes that request it (which, in this example, will be Notifier).

public function test_notifier_notifies_admins()
{
    $slackMock = Mockery::mock(SlackClient::class);
    $slackMock->shouldReceive('send')->once();

    app()->instance(SlackClient::class, $slackMock);

    $notifier = app(Notifier::class);
    $notifier->notifyAdmins('Test message');
}

In Laravel 5.8+, there’s also a convenient shortcut to creating and binding a Mockery instance to the container:

$this->mock(SlackClient::class, function ($mock) {
    $mock->shouldReceive('send')->once();
});

There’s a lot more you can do with Mockery: you can use spies, and partial spies, and much more. Going deeper into how to use Mockery is out of the scope of this book, but I encourage you to learn more about the library and how it works by reading the Mockery docs.

Faking Other Facades

There’s one other clever thing you can do with Mockery: you can use Mockery methods (e.g., shouldReceive()) on any facades in your app.

Imagine we have a controller method that uses a facade that’s not one of the fakeable systems we’ve already covered; we want to test that controller method and assert that a certain facade call was made.

Thankfully, it’s simple: we can run our Mockery-style methods on the facade, as you can see in Example 12-25.

// PersonController
public function index()
{
    return Cache::remember('people', function () {
        return Person::all();
    });
}

// PeopleTest
public function test_all_people_route_should_be_cached()
{
    $person = factory(Person::class)->create();

    Cache::shouldReceive('remember')
        ->once()
        ->andReturn(collect([$person]));

    $this->get('people')->assertJsonFragment(['name' => $person->name]);
}

As you can see, you can use methods like shouldReceive() on the facades, just like you do on a Mockery object.

You can also use your facades as spies, which means you can set your assertions at the end and use shouldHaveReceived() instead of shouldReceive(). Example 12-26 illustrates this.

public function test_package_should_be_cached_after_visit()
{
    Cache::spy();

    $package = factory(Package::class)->create();

    $this->get(route('packages.show', [$package->id]));

    Cache::shouldHaveReceived('put')
        ->once()
        ->with('packages.' . $package->id, $package->toArray());
}

Asserting Against Artisan Command Syntax

If you’re working with Laravel 5.7 and later, you can also chain three new methods onto your $this->artisan() call: expectsQuestion(), expectsOutput(), and assertExitCode(). The expects* methods will work on any of the interactive prompts, including confirm(), and anticipate(), and the assertExitCode() method is a shortcut to what we saw in Example 12-28.

Take a look at Example 12-29 to see how it works.

// routes/console.php
Artisan::command('make:post {--expanded}', function () {
    $title = $this->ask('What is the post title?');
    $this->comment('Creating at ' . Str::slug($title) . '.md');

    $category = $this->choice('What category?', ['technology', 'construction'], 0);

    // Create post here

    $this->comment('Post created');
});

// Test file
public function test_make_post_console_commands_performs_as_expected()
{
    $this->artisan('make:post', ['--expanded' => true])
        ->expectsQuestion('What is the post title?', 'My Best Post Now')
        ->expectsOutput('Creating at my-best-post-now.md')
        ->expectsQuestion('What category?', 'construction')
        ->expectsOutput('Post created')
        ->assertExitCode(0);
}

As you can see, the first parameter of expectsQuestion() is the text we’re expecting to see from the question, and the second parameter is the text we’re answering with. expectsOutput() just tests that the passed string is returned.

Choosing a Tool

For browser testing, I suggest you use the core application testing tools whenever possible (those we’ve covered up to this point). If your app is not JavaScript-based and you need to test actual DOM manipulation or form UI elements, use BrowserKit. If you’re developing a JavaScript-heavy app, you’ll likely want to use Dusk, which we’ll cover next.

However, there will also be many instances where you’ll want to use a JavaScript-based test stack (which is out of scope for this book) based on something like Jest and vue-test-utils. This toolset can be very useful for Vue component testing, and Jest’s snapshot functionality simplifies the process of keeping API and frontend test data in sync. To learn more, check out Caleb Porzio’s “Getting Started” blog post and Samantha Geitz’s 2018 Laracon talk.

If you’re working with a JavaScript framework other than Vue, there are no currently preferred frontend testing solutions in the Laravel world. However, the broad React world seems to have settled on Jest and Enzyme.

Testing with Dusk

Dusk is a Laravel tool (installable as a Composer package) that makes it easy to write Selenium-style directions for a ChromeDriver-based browser to interact with your app. Unlike most other Selenium-based tools, Dusk’s API is simple and it’s easy to write code to interact with it by hand. Take a look:

$this->browse(function ($browser) {
    $browser->visit('/register')
        ->type('email', '[email protected]')
        ->type('password', 'secret')
        ->press('Sign Up')
        ->assertPathIs('/dashboard');
});

With Dusk, there’s an actual browser spinning up your entire application and interacting with it. That means you can have complex interactions with your JavaScript and get screenshots of failure states—but it also means everything’s a bit slower and it’s more prone to failure than Laravel’s base application testing suite.

Personally, I’ve found that Dusk is most useful as a regression testing suite, and it works better than something like Selenium. Rather than using it for any sort of test-driven development, I use it to assert that the user experience hasn’t broken (“regressed”) as the app continues to develop. Think of this more like writing tests about your user interface after the interface is built.

The Dusk docs are robust, so I’m not going to go into great depth here, but I want to show you the basics of working with Dusk.

composer require --dev laravel/dusk
php artisan dusk:install

php artisan dusk:make RatingTest

public function testBasicExample()
{
    $user = factory(User::class)->create();

    $this->browse(function ($browser) use ($user) {
        $browser->visit('login')
            ->type('email', $user->email)
            ->type('password', 'secret')
            ->press('Login')
            ->assertPathIs('/home');
    });
}

$this->browse(function ($first, $second) {
    $first->loginAs(User::find(1))
        ->visit('home')
        ->waitForText('Message');

    $second->loginAs(User::find(2))
        ->visit('home')
        ->waitForText('Message')
        ->type('message', 'Hey Taylor')
        ->press('Send');

    $first->waitForText('Hey Taylor')
        ->assertSee('Jeffrey Way');
});

<-- Template -->
<div class="search"><input><button id="search-button"></button></div>
<button dusk="expand-nav"></button>

// Dusk tests
// Option 1: jQuery-style syntax
$browser->click('.search button');
$browser->click('#search-button');

// Option 2: dusk="selector-here" syntax; recommended
$browser->click('@expand-nav');

php artisan dusk:page CreatePackage

<?php

namespace TestsBrowserPages;

use LaravelDuskBrowser;

class CreatePackage extends Page
{
    /**
     * Get the URL for the page
     *
     * @return string
     */
    public function url()
    {
        return '/';
    }

    /**
     * Assert that the browser is on the page
     *
     * @param  Browser  $browser
     * @return void
     */
    public function assert(Browser $browser)
    {
        $browser->assertPathIs($this->url());
    }

    /**
     * Get the element shortcuts for the page
     *
     * @return array
     */
    public function elements()
    {
        return [
            '@element' => '#selector',
        ];
    }
}

class CreatePackage extends Page
{
    public function url()
    {
        return '/packages/create';
    }

    public function assert(Browser $browser)
    {
        $browser->assertTitleContains('Create Package');
        $browser->assertPathIs($this->url());
    }

    public function elements()
    {
        return [
            '@title' => 'input[name=title]',
            '@instructions' => 'textarea[name=instructions]',
        ];
    }
}

// In a test
$browser->visit(new TestsBrowserPagesCreatePackage)
    ->type('@title', 'My package title');

class CreatePackage extends Page
{
    // ... url(), assert(), elements()

    public function fillBasicFields(Browser $browser, $packageTitle = 'Best package')
    {
        $browser->type('@title', $packageTitle)
            ->type('@instructions', 'Do this stuff and then that stuff');
    }
}

$browser->visit(new CreatePackage)
    ->fillBasicFields('Greatest Package Ever')
    ->press('Create Package')
    ->assertSee('Greatest Package Ever');

php artisan dusk:component RatingWidget

<?php

namespace TestsBrowserComponents;

use LaravelDuskBrowser;
use LaravelDuskComponent as BaseComponent;

class RatingWidget extends BaseComponent
{
    /**
     * Get the root selector for the component
     *
     * @return string
     */
    public function selector()
    {
        return '#selector';
    }

    /**
     * Assert that the browser page contains the component
     *
     * @param  Browser  $browser
     * @return void
     */
    public function assert(Browser $browser)
    {
        $browser->assertVisible($this->selector());
    }

    /**
     * Get the element shortcuts for the component
     *
     * @return array
     */
    public function elements()
    {
        return [
            '@element' => '#selector',
        ];
    }
}

class RatingWidget extends BaseComponent
{
    public function selector()
    {
        return '.rating-widget';
    }

    public function assert(Browser $browser)
    {
        $browser->assertVisible($this->selector());
    }

    public function elements()
    {
        return [
            '@5-star' => '.five-star-rating',
            '@4-star' => '.four-star-rating',
            '@3-star' => '.three-star-rating',
            '@2-star' => '.two-star-rating',
            '@1-star' => '.one-star-rating',
            '@average' => '.average-rating',
            '@mine' => '.current-user-rating',
        ];
    }

    public function ratePackage(Browser $browser, $rating)
    {
        $browser->click("@{$rating}-star")
            ->assertSeeIn('@mine', $rating);
    }
}

$browser->visit('/packages/tightenco/nova-stock-picker')
    ->within(new RatingWidget, function ($browser) {
        $browser->ratePackage(2);
        $browser->assertSeeIn('@average', 2);
    });