RefreshDatabase

Illuminate\Foundation\Testing\RefreshDatabase is imported at the top of every newly-generated test file, and it’s the most commonly-used database migration trait (we’ll cover the two less-common options 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 (not the individual test methods, but just when you’re running phpunit). 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, cleared out fresh after each test runs, and all this without having to run your migrations again before every test, making it the fastest possible option. When in doubt, stick with this.

WithoutMiddleware

If you import Illuminate\Foundation\Testing\WithoutMiddleware 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 Illuminate\Foundation\Testing\DatabaseMigrations 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

Illuminate\Foundation\Testing\DatabaseTransactions, on the other hand, expects your database to be properly migrated before your tests start. Then, 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 Illuminate\Foundation\Testing\TestCase 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 re-creating 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, InteractsWithConsole, and more, 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, 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 (BrowserKit Testing in “A quick intro to BrowserKit Testing” and Dusk in “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 = [])

These methods are all the basis of the HTTP testing framework. Each takes a 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 Illuminate\Foundation\Testing\TestResponse, 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 also if you’re 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 make all of the same sort 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 = [])

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 38 assertions available on the $response object, so I recommend you take a look at all of them in the testing docs. Let’s look at a few of the most important and most common.

$response->assertOk()

Asserts that the response’s status code is 200.

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

$response->assertStatus($status)

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

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

$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, $strict = false)

Asserts that the passed array is represented (in JSON format) in the returned JSON. The $strict parameter makes for a === comparison instead of a == comparison, which, to be honest, I have never used.

$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 it 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 it optionally checks that the value of that data is $value.

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

$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 browser has been sent 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->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 assertSessionHasErrors there’s also assertSessionHasNoErrors, and assertSessionHasErrorsIn. For assertJson there’s also assertJsonCount, assertJsonFragment, assertJsonMissing, assertJsonMissingExact, assertJsonStructure, and assertJsonValidationErrors. So, 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():

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

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.

First, there are likely going to be times where you want to fake your events just for the sake of suppressing their actions. For example, if you have your app pushing notifications to Slack every time a new user signed up, and that’s happening in an event listener, you might want all of your events to stop working in your tests.

Let’s take a look at how to suppress these events by calling the fake() method on use Illuminate\Support\Facades\Event in Example 12-13.

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

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

But 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-14 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 we’re also asserting that the dispatched event contains certain data.

Each of the following features in Laravel have their own set of assertions you can make after faking them, but you can also just choose to fake them to restrict their effects.

Bus and Queue Fakes

The bus facade, which represents how Laravel dispatches jobs, works just like events. 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 also represents how Laravel dispatches jobs, but for when they’re pushed up to queues. Its available methods are assertedPushed(), assertPushedOn(), and assertNotPushed().

Take a look at Example 12-15 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-16 to see it 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('admin@novapackages.com');
    });

    // 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 the mail facade, you’re not going to test who it 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-17 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-18.

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 endlessly simpler to test file uploads and other storage-related items.

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 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-20.

// 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-21).

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(), must make 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-22, 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');
}

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 at 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 fake-able 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-23.

// PeopleController
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-24 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 on three new methods to your $this->artisan() call: expectsQuestion(), expectsOutput(), and assertExitCode(). The expects methods will work on any of the interactive prompts, including confirm(), anticipate(), and more, and the assertExitCode() method is a shortcut to what we looked at in Example 12-26.

Take a look at Example 12-27 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.

How do I pick which tool to use for browser testing?

When choosing a tool for browser testing, I suggest you use the core application testing tools whenever possible (those which we’ve covered up until 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 are 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 this blog post from Caleb Porzio and this Laracon talk from Samantha Geitz.

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.

Installing Dusk

To install Dusk, run these two commands:

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

Then edit your .env file to set your APP_URL variable to the same URL you use to view your site in your local browser; something like http://mysite.test.

To run your Dusk tests, just run php artisan dusk, and you can pass all the same parameters you’re used to from PHPUnit (e.g. php artisan dusk --filter=my_best_test).

Writing Dusk Tests

To generate a new Dusk test, use the following command:

php artisan dusk:make RatingTest

This test will be placed in tests/Browser/RatingTest.php.

To write your Dusk Tests, imagine that you’re directing one or more web browsers to go visit your application and take certain actions. That’s what the syntax will look like, as you can see in Example 12-28.

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() creates a browser, which you pass into a closure, and then within the closure you instruct the browser which actions to take.

It’s important to note that, unlike Laravel’s other application testing tools, which mimic the behavior of your forms, Dusk is actually spinning up a browser, sending events to the browser to type those words, and then sending an event to the browser to press that button. This is a real browser and Dusk is fully driving it.

You can also “ask” for more than one browser by adding parameters to the closure, which allows you to test how multiple users might interact with the web site (for example, with a chat system). Take a look at this example from the docs:

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

There’s a huge suite of actions and assertions available that we won’t cover here (check the docs), but let’s look at a few of the other tools Dusk provides.

Authentication and databases

As you can see in Example 12-29, the syntax for authentication is a little different from the rest of the Laravel application testing: $browser->loginAs($user).

Interactions with the page

If you’ve ever written jQuery, interacting with the page using Dusk will come naturally. Take a look at Example 12-30 to see the common patterns for selecting items with Dusk.

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

As you can see, adding the dusk attribute to your page elements allows you to reference them directly in a way that won’t change when the display or layout of the page changes later; when any method asks for a selector, pass in the @ sign and then the content of your dusk attribute.

Let’s take a look at a few of the methods you can call on $browser.

Waiting

Because Dusk interacts with JavaScript and is directing an actual browser, the concept of time and timeouts and “waiting” needs to be addressed. Dusk offers a few methods you can use to ensure your tests handle timing issues correctly. Some of these methods are useful for interacting with intentionally slow or delayed elements of the page, but some of them are also just useful for getting around initialization times on your components.

pause($milliseconds)

Pauses the execution of Dusk tests for the given number of milliseconds. The simplest “wait” option; makes any future commands you send to the browser wait that amount of time before operating.

Take a look at Example 12-32 to see how to use this and other waiting methods in the midst of an assertion chain.

Example 12-32. How to use Dusk’s waiting methods

$browser->click('chat')
    ->pause(500)
    ->assertSee('How can we help?');

waitFor($selector, $maxSeconds = null) and waitForMissing($selector, $maxSeconds = null)

Waits until the given element exists on the page (waitFor()) or disappears from the page (waitForMissing()), or times out after the optional second parameter’s second count.

$browser->waitFor('@chat', 5);
$browser->waitUntilMissing('@loading', 5);

whenAvailable($selector, $callback)

Similar to waitFor(), but accepts a closure as the second parameter which will define what action to take when the specified element becomes available.

$browser->whenAvailable('@chat', function ($chat) {
    $chat->assertSee('How can we help you?');
});

waitForText($text, $maxSeconds = null)

Waits for text to show up on the page, or times out after the optional second parameter’s second count.

$browser->waitForText('Your purchase has been completed.', 5);

waitForLink($linkText, $maxSeconds = null)

Waits for a link to exist with the given link text, or times out after the optional second parameter’s second count.

$browser->waitForLink('Clear these results', 2);

waitForLocation($path)

Waits until the page URL matches the provided path.

$browser->waitForLocation('auth/login');

waitForRoute($routeName)

Waits until the page URL matches the URL for the provided route.

$browser->waitForRoute('packages.show', [$package->id]);

waitForReload()

Waits until the page reloads.

waitUntil($expression)

Waits until the provided JavaScript expression evaluates as true:

$browser->waitUntil('App.packages.length > 0', 7);

Other assertions

As I’ve mentioned, there’s a huge list of assertions you can make against your app with Dusk. Here are a few that I use most commonly, and you can see the full list in the Dusk docs.

• assertTitleContains($text)

• assertQueryStringHas($keyName)

• assertHasCookie($cookieName)

• assertSourceHas($htmlSourceCode)

• assertChecked($selector)

• assertSelectHasOption($selectorForSelect, $optionValue)

• assertVisible($selector)

• assertFocused()

• assertVue($dataLocation, $dataValue, $selector)

So far, everything we’ve covered makes it possible for you to test individual elements on your pages. But Dusk will often be used to test more complex applications and single-page apps, which means we’re going to need organizational structures around our assertions.

The first organizational structures we have encountered have been the Dusk attribute (<div dusk="abc"> creating a selector named @abc you can refer to later) and the closures we can use towrap certain portions of our code (for example, with whenAvailable()).

Dusk offers two more organizational tools: Pages and Components. Let’s start with pages.

Pages

A page is a class that you’ll generate which contains two pieces of functionality: first, a URL and assertions to define which page in your app should be attached to this Dusk page, and second, shorthand like we used inline (@abc generated by the dusk="abc" attribute in our HTML) but just for this page, and without needing to edit our HTML.

To generate your first Dusk page, let’s imagine we have a “create package” page of our app. Generate a Dusk page for it:

php artisan dusk:page CreatePackage

Take a look at Example 12-33 to see what our generated class will look like.

<?php

namespace Tests\Browser\Pages;

use Laravel\Dusk\Browser;

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

The url() method defines where Dusk should expect the location to be for this page; assert() lets you run additional assertions to verify you’re on the right page; and elements() provides shortcuts for @dusk-style selectors.

Let’s make a few quick modifications for our “create package” page, to make it look like Example 12-34.

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

Now that we have a functional page, we can navigate to it, and access its defined elements:

// In a test
$browser->visit(new Tests\Browser\Pages\CreatePackage)
    ->type('@title', 'My package title');

One common use for pages is to define a common action you want to take in your tests; consider these almost like macros for Dusk. You can define a method on your page and then call it from your code, as you can see in Example 12-35.

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

Components

If you want the same functionality as Dusk pages offer, but without the constraint to a specific URL, you’ll likely want to reach for Dusk components. These classes are shaped very similarly to pages, but instead of being bound to a URL, they’re each bound to a selector.

In NovaPackages.com, we have a little Vue component for rating packages and displaying ratings. Let’s make a Dusk component for it.

php artisan dusk:component RatingWidget

Take a look at Example 12-36 to see what that will generate.

<?php

namespace Tests\Browser\Components;

use Laravel\Dusk\Browser;
use Laravel\Dusk\Component 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',
        ];
    }
}

As you can see, this is basically the same as a Dusk page, but we’re encapsulating our work to an HTML element instead of a URL. Everything else is basically the same. Take a look at Example 12-37 to see our rating widget example in Dusk component form.

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

Using components works just like using pages, as you can see in Example 12-38.

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

That’s a good, brief overview of what Dusk can do. There’s a lot more—more assertions, more edge cases, more gotcha’s, more examples—in the Dusk docs, so I’d recommend a read through there if you plan to work with Dusk.