HTTP Tests

• Introduction
• Making Requests
  • Customizing Request Headers
  • Cookies
  • Session / Authentication
  • Debugging Responses
  • Exception Handling
• Testing JSON APIs
  • Fluent JSON Testing
• Testing File Uploads
• Testing Views
  • Rendering Blade and Components
• Available Assertions
  • Response Assertions
  • Authentication Assertions
  • Validation Assertions

Introduction

Laravel provides a very fluent API for making HTTP requests to your application and examining the responses. For example, take a look at the feature test defined below:

1<?php
2 
3test('the application returns a successful response', function () {
4    $response = $this->get('/');
5 
6    $response->assertStatus(200);
7});
1<?php
2 
3test('the application returns a successful response', function () {
4    $response = $this->get('/');
5 
6    $response->assertStatus(200);
7});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic test example.
11     */
12    public function test_the_application_returns_a_successful_response(): void
13    {
14        $response = $this->get('/');
15 
16        $response->assertStatus(200);
17    }
18}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic test example.
11     */
12    public function test_the_application_returns_a_successful_response(): void
13    {
14        $response = $this->get('/');
15 
16        $response->assertStatus(200);
17    }
18}

The get method makes a GET request into the application, while the assertStatus method asserts that the returned response should have the given HTTP status code. In addition to this simple assertion, Laravel also contains a variety of assertions for inspecting the response headers, content, JSON structure, and more.

Making Requests

To make a request to your application, you may invoke the get, post, put, patch, or delete methods within your test. These methods do not actually issue a "real" HTTP request to your application. Instead, the entire network request is simulated internally.

Instead of returning an Illuminate\Http\Response instance, test request methods return an instance of Illuminate\Testing\TestResponse, which provides a variety of helpful assertions that allow you to inspect your application's responses:

1<?php
2 
3test('basic request', function () {
4    $response = $this->get('/');
5 
6    $response->assertStatus(200);
7});
1<?php
2 
3test('basic request', function () {
4    $response = $this->get('/');
5 
6    $response->assertStatus(200);
7});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic test example.
11     */
12    public function test_a_basic_request(): void
13    {
14        $response = $this->get('/');
15 
16        $response->assertStatus(200);
17    }
18}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic test example.
11     */
12    public function test_a_basic_request(): void
13    {
14        $response = $this->get('/');
15 
16        $response->assertStatus(200);
17    }
18}

In general, each of your tests should only make one request to your application. Unexpected behavior may occur if multiple requests are executed within a single test method.

Customizing Request Headers

You may use the withHeaders method to customize the request's headers before it is sent to the application. This method allows you to add any custom headers you would like to the request:

1<?php
2 
3test('interacting with headers', function () {
4    $response = $this->withHeaders([
5        'X-Header' => 'Value',
6    ])->post('/user', ['name' => 'Sally']);
7 
8    $response->assertStatus(201);
9});
1<?php
2 
3test('interacting with headers', function () {
4    $response = $this->withHeaders([
5        'X-Header' => 'Value',
6    ])->post('/user', ['name' => 'Sally']);
7 
8    $response->assertStatus(201);
9});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic functional test example.
11     */
12    public function test_interacting_with_headers(): void
13    {
14        $response = $this->withHeaders([
15            'X-Header' => 'Value',
16        ])->post('/user', ['name' => 'Sally']);
17 
18        $response->assertStatus(201);
19    }
20}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic functional test example.
11     */
12    public function test_interacting_with_headers(): void
13    {
14        $response = $this->withHeaders([
15            'X-Header' => 'Value',
16        ])->post('/user', ['name' => 'Sally']);
17 
18        $response->assertStatus(201);
19    }
20}

Cookies

You may use the withCookie or withCookies methods to set cookie values before making a request. The withCookie method accepts a cookie name and value as its two arguments, while the withCookies method accepts an array of name / value pairs:

 1<?php
 2 
 3test('interacting with cookies', function () {
 4    $response = $this->withCookie('color', 'blue')->get('/');
 5 
 6    $response = $this->withCookies([
 7        'color' => 'blue',
 8        'name' => 'Taylor',
 9    ])->get('/');
10 
11    //
12});
 1<?php
 2 
 3test('interacting with cookies', function () {
 4    $response = $this->withCookie('color', 'blue')->get('/');
 5 
 6    $response = $this->withCookies([
 7        'color' => 'blue',
 8        'name' => 'Taylor',
 9    ])->get('/');
10 
11    //
12});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    public function test_interacting_with_cookies(): void
10    {
11        $response = $this->withCookie('color', 'blue')->get('/');
12 
13        $response = $this->withCookies([
14            'color' => 'blue',
15            'name' => 'Taylor',
16        ])->get('/');
17 
18        //
19    }
20}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    public function test_interacting_with_cookies(): void
10    {
11        $response = $this->withCookie('color', 'blue')->get('/');
12 
13        $response = $this->withCookies([
14            'color' => 'blue',
15            'name' => 'Taylor',
16        ])->get('/');
17 
18        //
19    }
20}

Session / Authentication

Laravel provides several helpers for interacting with the session during HTTP testing. First, you may set the session data to a given array using the withSession method. This is useful for loading the session with data before issuing a request to your application:

1<?php
2 
3test('interacting with the session', function () {
4    $response = $this->withSession(['banned' => false])->get('/');
5 
6    //
7});
1<?php
2 
3test('interacting with the session', function () {
4    $response = $this->withSession(['banned' => false])->get('/');
5 
6    //
7});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    public function test_interacting_with_the_session(): void
10    {
11        $response = $this->withSession(['banned' => false])->get('/');
12 
13        //
14    }
15}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    public function test_interacting_with_the_session(): void
10    {
11        $response = $this->withSession(['banned' => false])->get('/');
12 
13        //
14    }
15}

Laravel's session is typically used to maintain state for the currently authenticated user. Therefore, the actingAs helper method provides a simple way to authenticate a given user as the current user. For example, we may use a model factory to generate and authenticate a user:

 1<?php
 2 
 3use App\Models\User;
 4 
 5test('an action that requires authentication', function () {
 6    $user = User::factory()->create();
 7 
 8    $response = $this->actingAs($user)
 9                     ->withSession(['banned' => false])
10                     ->get('/');
11 
12    //
13});
 1<?php
 2 
 3use App\Models\User;
 4 
 5test('an action that requires authentication', function () {
 6    $user = User::factory()->create();
 7 
 8    $response = $this->actingAs($user)
 9                     ->withSession(['banned' => false])
10                     ->get('/');
11 
12    //
13});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use App\Models\User;
 6use Tests\TestCase;
 7 
 8class ExampleTest extends TestCase
 9{
10    public function test_an_action_that_requires_authentication(): void
11    {
12        $user = User::factory()->create();
13 
14        $response = $this->actingAs($user)
15                         ->withSession(['banned' => false])
16                         ->get('/');
17 
18        //
19    }
20}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use App\Models\User;
 6use Tests\TestCase;
 7 
 8class ExampleTest extends TestCase
 9{
10    public function test_an_action_that_requires_authentication(): void
11    {
12        $user = User::factory()->create();
13 
14        $response = $this->actingAs($user)
15                         ->withSession(['banned' => false])
16                         ->get('/');
17 
18        //
19    }
20}

You may also specify which guard should be used to authenticate the given user by passing the guard name as the second argument to the actingAs method. The guard that is provided to the actingAs method will also become the default guard for the duration of the test:

1$this->actingAs($user, 'web')
1$this->actingAs($user, 'web')

Debugging Responses

After making a test request to your application, the dump, dumpHeaders, and dumpSession methods may be used to examine and debug the response contents:

 1<?php
 2 
 3test('basic test', function () {
 4    $response = $this->get('/');
 5 
 6    $response->dumpHeaders();
 7 
 8    $response->dumpSession();
 9 
10    $response->dump();
11});
 1<?php
 2 
 3test('basic test', function () {
 4    $response = $this->get('/');
 5 
 6    $response->dumpHeaders();
 7 
 8    $response->dumpSession();
 9 
10    $response->dump();
11});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic test example.
11     */
12    public function test_basic_test(): void
13    {
14        $response = $this->get('/');
15 
16        $response->dumpHeaders();
17 
18        $response->dumpSession();
19 
20        $response->dump();
21    }
22}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic test example.
11     */
12    public function test_basic_test(): void
13    {
14        $response = $this->get('/');
15 
16        $response->dumpHeaders();
17 
18        $response->dumpSession();
19 
20        $response->dump();
21    }
22}

Alternatively, you may use the dd, ddHeaders, and ddSession methods to dump information about the response and then stop execution:

 1<?php
 2 
 3test('basic test', function () {
 4    $response = $this->get('/');
 5 
 6    $response->ddHeaders();
 7 
 8    $response->ddSession();
 9 
10    $response->dd();
11});
 1<?php
 2 
 3test('basic test', function () {
 4    $response = $this->get('/');
 5 
 6    $response->ddHeaders();
 7 
 8    $response->ddSession();
 9 
10    $response->dd();
11});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic test example.
11     */
12    public function test_basic_test(): void
13    {
14        $response = $this->get('/');
15 
16        $response->ddHeaders();
17 
18        $response->ddSession();
19 
20        $response->dd();
21    }
22}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic test example.
11     */
12    public function test_basic_test(): void
13    {
14        $response = $this->get('/');
15 
16        $response->ddHeaders();
17 
18        $response->ddSession();
19 
20        $response->dd();
21    }
22}

Exception Handling

Sometimes you may need to test that your application is throwing a specific exception. To accomplish this, you may "fake" the exception handler via the Exceptions facade. Once the exception handler has been faked, you may utilize the assertReported and assertNotReported methods to make assertions against exceptions that were thrown during the request:

 1<?php
 2 
 3use App\Exceptions\InvalidOrderException;
 4use Illuminate\Support\Facades\Exceptions;
 5 
 6test('exception is thrown', function () {
 7    Exceptions::fake();
 8 
 9    $response = $this->get('/order/1');
10 
11    // Assert an exception was thrown...
12    Exceptions::assertReported(InvalidOrderException::class);
13 
14    // Assert against the exception...
15    Exceptions::assertReported(function (InvalidOrderException $e) {
16        return $e->getMessage() === 'The order was invalid.';
17    });
18});
 1<?php
 2 
 3use App\Exceptions\InvalidOrderException;
 4use Illuminate\Support\Facades\Exceptions;
 5 
 6test('exception is thrown', function () {
 7    Exceptions::fake();
 8 
 9    $response = $this->get('/order/1');
10 
11    // Assert an exception was thrown...
12    Exceptions::assertReported(InvalidOrderException::class);
13 
14    // Assert against the exception...
15    Exceptions::assertReported(function (InvalidOrderException $e) {
16        return $e->getMessage() === 'The order was invalid.';
17    });
18});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use App\Exceptions\InvalidOrderException;
 6use Illuminate\Support\Facades\Exceptions;
 7use Tests\TestCase;
 8 
 9class ExampleTest extends TestCase
10{
11    /**
12     * A basic test example.
13     */
14    public function test_exception_is_thrown(): void
15    {
16        Exceptions::fake();
17 
18        $response = $this->get('/');
19 
20        // Assert an exception was thrown...
21        Exceptions::assertReported(InvalidOrderException::class);
22 
23        // Assert against the exception...
24        Exceptions::assertReported(function (InvalidOrderException $e) {
25            return $e->getMessage() === 'The order was invalid.';
26        });
27    }
28}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use App\Exceptions\InvalidOrderException;
 6use Illuminate\Support\Facades\Exceptions;
 7use Tests\TestCase;
 8 
 9class ExampleTest extends TestCase
10{
11    /**
12     * A basic test example.
13     */
14    public function test_exception_is_thrown(): void
15    {
16        Exceptions::fake();
17 
18        $response = $this->get('/');
19 
20        // Assert an exception was thrown...
21        Exceptions::assertReported(InvalidOrderException::class);
22 
23        // Assert against the exception...
24        Exceptions::assertReported(function (InvalidOrderException $e) {
25            return $e->getMessage() === 'The order was invalid.';
26        });
27    }
28}

The assertNotReported and assertNothingReported methods may be used to assert that a given exception was not thrown during the request or that no exceptions were thrown:

1Exceptions::assertNotReported(InvalidOrderException::class);
2 
3Exceptions::assertNothingReported();
1Exceptions::assertNotReported(InvalidOrderException::class);
2 
3Exceptions::assertNothingReported();

You may totally disable exception handling for a given request by invoking the withoutExceptionHandling method before making your request:

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

In addition, if you would like to ensure that your application is not utilizing features that have been deprecated by the PHP language or the libraries your application is using, you may invoke the withoutDeprecationHandling method before making your request. When deprecation handling is disabled, deprecation warnings will be converted to exceptions, thus causing your test to fail:

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

The assertThrows method may be used to assert that code within a given closure throws an exception of the specified type:

1$this->assertThrows(
2    fn () => (new ProcessOrder)->execute(),
3    OrderInvalid::class
4);
1$this->assertThrows(
2    fn () => (new ProcessOrder)->execute(),
3    OrderInvalid::class
4);

If you would like to inspect and make assertions against the exception that is thrown, you may provide a closure as the second argument to the assertThrows method:

1$this->assertThrows(
2    fn () => (new ProcessOrder)->execute(),
3    fn (OrderInvalid $e) => $e->orderId() === 123;
4);
1$this->assertThrows(
2    fn () => (new ProcessOrder)->execute(),
3    fn (OrderInvalid $e) => $e->orderId() === 123;
4);

Testing JSON APIs

Laravel also provides several helpers for testing JSON APIs and their responses. For example, the json, getJson, postJson, putJson, patchJson, deleteJson, and optionsJson methods may be used to issue JSON requests with various HTTP verbs. You may also easily pass data and headers to these methods. To get started, let's write a test to make a POST request to /api/user and assert that the expected JSON data was returned:

 1<?php
 2 
 3test('making an api request', function () {
 4    $response = $this->postJson('/api/user', ['name' => 'Sally']);
 5 
 6    $response
 7        ->assertStatus(201)
 8        ->assertJson([
 9            'created' => true,
10         ]);
11});
 1<?php
 2 
 3test('making an api request', function () {
 4    $response = $this->postJson('/api/user', ['name' => 'Sally']);
 5 
 6    $response
 7        ->assertStatus(201)
 8        ->assertJson([
 9            'created' => true,
10         ]);
11});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic functional test example.
11     */
12    public function test_making_an_api_request(): void
13    {
14        $response = $this->postJson('/api/user', ['name' => 'Sally']);
15 
16        $response
17            ->assertStatus(201)
18            ->assertJson([
19                'created' => true,
20            ]);
21    }
22}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic functional test example.
11     */
12    public function test_making_an_api_request(): void
13    {
14        $response = $this->postJson('/api/user', ['name' => 'Sally']);
15 
16        $response
17            ->assertStatus(201)
18            ->assertJson([
19                'created' => true,
20            ]);
21    }
22}

In addition, JSON response data may be accessed as array variables on the response, making it convenient for you to inspect the individual values returned within a JSON response:

1expect($response['created'])->toBeTrue();
1expect($response['created'])->toBeTrue();

1$this->assertTrue($response['created']);
1$this->assertTrue($response['created']);

Asserting Exact JSON Matches

As previously mentioned, the assertJson method may be used to assert that a fragment of JSON exists within the JSON response. If you would like to verify that a given array exactly matches the JSON returned by your application, you should use the assertExactJson method:

 1<?php
 2 
 3test('asserting an exact json match', function () {
 4    $response = $this->postJson('/user', ['name' => 'Sally']);
 5 
 6    $response
 7        ->assertStatus(201)
 8        ->assertExactJson([
 9            'created' => true,
10        ]);
11});
 1<?php
 2 
 3test('asserting an exact json match', function () {
 4    $response = $this->postJson('/user', ['name' => 'Sally']);
 5 
 6    $response
 7        ->assertStatus(201)
 8        ->assertExactJson([
 9            'created' => true,
10        ]);
11});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic functional test example.
11     */
12    public function test_asserting_an_exact_json_match(): void
13    {
14        $response = $this->postJson('/user', ['name' => 'Sally']);
15 
16        $response
17            ->assertStatus(201)
18            ->assertExactJson([
19                'created' => true,
20            ]);
21    }
22}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic functional test example.
11     */
12    public function test_asserting_an_exact_json_match(): void
13    {
14        $response = $this->postJson('/user', ['name' => 'Sally']);
15 
16        $response
17            ->assertStatus(201)
18            ->assertExactJson([
19                'created' => true,
20            ]);
21    }
22}

Asserting on JSON Paths

If you would like to verify that the JSON response contains the given data at a specified path, you should use the assertJsonPath method:

1<?php
2 
3test('asserting a json path value', function () {
4    $response = $this->postJson('/user', ['name' => 'Sally']);
5 
6    $response
7        ->assertStatus(201)
8        ->assertJsonPath('team.owner.name', 'Darian');
9});
1<?php
2 
3test('asserting a json path value', function () {
4    $response = $this->postJson('/user', ['name' => 'Sally']);
5 
6    $response
7        ->assertStatus(201)
8        ->assertJsonPath('team.owner.name', 'Darian');
9});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic functional test example.
11     */
12    public function test_asserting_a_json_paths_value(): void
13    {
14        $response = $this->postJson('/user', ['name' => 'Sally']);
15 
16        $response
17            ->assertStatus(201)
18            ->assertJsonPath('team.owner.name', 'Darian');
19    }
20}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    /**
10     * A basic functional test example.
11     */
12    public function test_asserting_a_json_paths_value(): void
13    {
14        $response = $this->postJson('/user', ['name' => 'Sally']);
15 
16        $response
17            ->assertStatus(201)
18            ->assertJsonPath('team.owner.name', 'Darian');
19    }
20}

The assertJsonPath method also accepts a closure, which may be used to dynamically determine if the assertion should pass:

1$response->assertJsonPath('team.owner.name', fn (string $name) => strlen($name) >= 3);
1$response->assertJsonPath('team.owner.name', fn (string $name) => strlen($name) >= 3);

Fluent JSON Testing

Laravel also offers a beautiful way to fluently test your application's JSON responses. To get started, pass a closure to the assertJson method. This closure will be invoked with an instance of Illuminate\Testing\Fluent\AssertableJson which can be used to make assertions against the JSON that was returned by your application. The where method may be used to make assertions against a particular attribute of the JSON, while the missing method may be used to assert that a particular attribute is missing from the JSON:

 1use Illuminate\Testing\Fluent\AssertableJson;
 2 
 3test('fluent json', function () {
 4    $response = $this->getJson('/users/1');
 5 
 6    $response
 7        ->assertJson(fn (AssertableJson $json) =>
 8            $json->where('id', 1)
 9                 ->where('name', 'Victoria Faith')
10                 ->where('email', fn (string $email) => str($email)->is('[email protected]'))
11                 ->whereNot('status', 'pending')
12                 ->missing('password')
13                 ->etc()
14        );
15});
 1use Illuminate\Testing\Fluent\AssertableJson;
 2 
 3test('fluent json', function () {
 4    $response = $this->getJson('/users/1');
 5 
 6    $response
 7        ->assertJson(fn (AssertableJson $json) =>
 8            $json->where('id', 1)
 9                 ->where('name', 'Victoria Faith')
10                 ->where('email', fn (string $email) => str($email)->is('[email protected]'))
11                 ->whereNot('status', 'pending')
12                 ->missing('password')
13                 ->etc()
14        );
15});

 1use Illuminate\Testing\Fluent\AssertableJson;
 2 
 3/**
 4 * A basic functional test example.
 5 */
 6public function test_fluent_json(): void
 7{
 8    $response = $this->getJson('/users/1');
 9 
10    $response
11        ->assertJson(fn (AssertableJson $json) =>
12            $json->where('id', 1)
13                 ->where('name', 'Victoria Faith')
14                 ->where('email', fn (string $email) => str($email)->is('[email protected]'))
15                 ->whereNot('status', 'pending')
16                 ->missing('password')
17                 ->etc()
18        );
19}
 1use Illuminate\Testing\Fluent\AssertableJson;
 2 
 3/**
 4 * A basic functional test example.
 5 */
 6public function test_fluent_json(): void
 7{
 8    $response = $this->getJson('/users/1');
 9 
10    $response
11        ->assertJson(fn (AssertableJson $json) =>
12            $json->where('id', 1)
13                 ->where('name', 'Victoria Faith')
14                 ->where('email', fn (string $email) => str($email)->is('[email protected]'))
15                 ->whereNot('status', 'pending')
16                 ->missing('password')
17                 ->etc()
18        );
19}

Understanding the etc Method

In the example above, you may have noticed we invoked the etc method at the end of our assertion chain. This method informs Laravel that there may be other attributes present on the JSON object. If the etc method is not used, the test will fail if other attributes that you did not make assertions against exist on the JSON object.

The intention behind this behavior is to protect you from unintentionally exposing sensitive information in your JSON responses by forcing you to either explicitly make an assertion against the attribute or explicitly allow additional attributes via the etc method.

However, you should be aware that not including the etc method in your assertion chain does not ensure that additional attributes are not being added to arrays that are nested within your JSON object. The etc method only ensures that no additional attributes exist at the nesting level in which the etc method is invoked.

Asserting Attribute Presence / Absence

To assert that an attribute is present or absent, you may use the has and missing methods:

1$response->assertJson(fn (AssertableJson $json) =>
2    $json->has('data')
3         ->missing('message')
4);
1$response->assertJson(fn (AssertableJson $json) =>
2    $json->has('data')
3         ->missing('message')
4);

In addition, the hasAll and missingAll methods allow asserting the presence or absence of multiple attributes simultaneously:

1$response->assertJson(fn (AssertableJson $json) =>
2    $json->hasAll(['status', 'data'])
3         ->missingAll(['message', 'code'])
4);
1$response->assertJson(fn (AssertableJson $json) =>
2    $json->hasAll(['status', 'data'])
3         ->missingAll(['message', 'code'])
4);

You may use the hasAny method to determine if at least one of a given list of attributes is present:

1$response->assertJson(fn (AssertableJson $json) =>
2    $json->has('status')
3         ->hasAny('data', 'message', 'code')
4);
1$response->assertJson(fn (AssertableJson $json) =>
2    $json->has('status')
3         ->hasAny('data', 'message', 'code')
4);

Asserting Against JSON Collections

Often, your route will return a JSON response that contains multiple items, such as multiple users:

1Route::get('/users', function () {
2    return User::all();
3});
1Route::get('/users', function () {
2    return User::all();
3});

In these situations, we may use the fluent JSON object's has method to make assertions against the users included in the response. For example, let's assert that the JSON response contains three users. Next, we'll make some assertions about the first user in the collection using the first method. The first method accepts a closure which receives another assertable JSON string that we can use to make assertions about the first object in the JSON collection:

 1$response
 2    ->assertJson(fn (AssertableJson $json) =>
 3        $json->has(3)
 4             ->first(fn (AssertableJson $json) =>
 5                $json->where('id', 1)
 6                     ->where('name', 'Victoria Faith')
 7                     ->where('email', fn (string $email) => str($email)->is('[email protected]'))
 8                     ->missing('password')
 9                     ->etc()
10             )
11    );
 1$response
 2    ->assertJson(fn (AssertableJson $json) =>
 3        $json->has(3)
 4             ->first(fn (AssertableJson $json) =>
 5                $json->where('id', 1)
 6                     ->where('name', 'Victoria Faith')
 7                     ->where('email', fn (string $email) => str($email)->is('[email protected]'))
 8                     ->missing('password')
 9                     ->etc()
10             )
11    );

Scoping JSON Collection Assertions

Sometimes, your application's routes will return JSON collections that are assigned named keys:

1Route::get('/users', function () {
2    return [
3        'meta' => [...],
4        'users' => User::all(),
5    ];
6})
1Route::get('/users', function () {
2    return [
3        'meta' => [...],
4        'users' => User::all(),
5    ];
6})

When testing these routes, you may use the has method to assert against the number of items in the collection. In addition, you may use the has method to scope a chain of assertions:

 1$response
 2    ->assertJson(fn (AssertableJson $json) =>
 3        $json->has('meta')
 4             ->has('users', 3)
 5             ->has('users.0', fn (AssertableJson $json) =>
 6                $json->where('id', 1)
 7                     ->where('name', 'Victoria Faith')
 8                     ->where('email', fn (string $email) => str($email)->is('[email protected]'))
 9                     ->missing('password')
10                     ->etc()
11             )
12    );
 1$response
 2    ->assertJson(fn (AssertableJson $json) =>
 3        $json->has('meta')
 4             ->has('users', 3)
 5             ->has('users.0', fn (AssertableJson $json) =>
 6                $json->where('id', 1)
 7                     ->where('name', 'Victoria Faith')
 8                     ->where('email', fn (string $email) => str($email)->is('[email protected]'))
 9                     ->missing('password')
10                     ->etc()
11             )
12    );

However, instead of making two separate calls to the has method to assert against the users collection, you may make a single call which provides a closure as its third parameter. When doing so, the closure will automatically be invoked and scoped to the first item in the collection:

 1$response
 2    ->assertJson(fn (AssertableJson $json) =>
 3        $json->has('meta')
 4             ->has('users', 3, fn (AssertableJson $json) =>
 5                $json->where('id', 1)
 6                     ->where('name', 'Victoria Faith')
 7                     ->where('email', fn (string $email) => str($email)->is('[email protected]'))
 8                     ->missing('password')
 9                     ->etc()
10             )
11    );
 1$response
 2    ->assertJson(fn (AssertableJson $json) =>
 3        $json->has('meta')
 4             ->has('users', 3, fn (AssertableJson $json) =>
 5                $json->where('id', 1)
 6                     ->where('name', 'Victoria Faith')
 7                     ->where('email', fn (string $email) => str($email)->is('[email protected]'))
 8                     ->missing('password')
 9                     ->etc()
10             )
11    );

Asserting JSON Types

You may only want to assert that the properties in the JSON response are of a certain type. The Illuminate\Testing\Fluent\AssertableJson class provides the whereType and whereAllType methods for doing just that:

1$response->assertJson(fn (AssertableJson $json) =>
2    $json->whereType('id', 'integer')
3         ->whereAllType([
4            'users.0.name' => 'string',
5            'meta' => 'array'
6        ])
7);
1$response->assertJson(fn (AssertableJson $json) =>
2    $json->whereType('id', 'integer')
3         ->whereAllType([
4            'users.0.name' => 'string',
5            'meta' => 'array'
6        ])
7);

You may specify multiple types using the | character, or passing an array of types as the second parameter to the whereType method. The assertion will be successful if the response value is any of the listed types:

1$response->assertJson(fn (AssertableJson $json) =>
2    $json->whereType('name', 'string|null')
3         ->whereType('id', ['string', 'integer'])
4);
1$response->assertJson(fn (AssertableJson $json) =>
2    $json->whereType('name', 'string|null')
3         ->whereType('id', ['string', 'integer'])
4);

The whereType and whereAllType methods recognize the following types: string, integer, double, boolean, array, and null.

Testing File Uploads

The Illuminate\Http\UploadedFile class provides a fake method which may be used to generate dummy files or images for testing. This, combined with the Storage facade's fake method, greatly simplifies the testing of file uploads. For example, you may combine these two features to easily test an avatar upload form:

 1<?php
 2 
 3use Illuminate\Http\UploadedFile;
 4use Illuminate\Support\Facades\Storage;
 5 
 6test('avatars can be uploaded', function () {
 7    Storage::fake('avatars');
 8 
 9    $file = UploadedFile::fake()->image('avatar.jpg');
10 
11    $response = $this->post('/avatar', [
12        'avatar' => $file,
13    ]);
14 
15    Storage::disk('avatars')->assertExists($file->hashName());
16});
 1<?php
 2 
 3use Illuminate\Http\UploadedFile;
 4use Illuminate\Support\Facades\Storage;
 5 
 6test('avatars can be uploaded', function () {
 7    Storage::fake('avatars');
 8 
 9    $file = UploadedFile::fake()->image('avatar.jpg');
10 
11    $response = $this->post('/avatar', [
12        'avatar' => $file,
13    ]);
14 
15    Storage::disk('avatars')->assertExists($file->hashName());
16});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Illuminate\Http\UploadedFile;
 6use Illuminate\Support\Facades\Storage;
 7use Tests\TestCase;
 8 
 9class ExampleTest extends TestCase
10{
11    public function test_avatars_can_be_uploaded(): void
12    {
13        Storage::fake('avatars');
14 
15        $file = UploadedFile::fake()->image('avatar.jpg');
16 
17        $response = $this->post('/avatar', [
18            'avatar' => $file,
19        ]);
20 
21        Storage::disk('avatars')->assertExists($file->hashName());
22    }
23}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Illuminate\Http\UploadedFile;
 6use Illuminate\Support\Facades\Storage;
 7use Tests\TestCase;
 8 
 9class ExampleTest extends TestCase
10{
11    public function test_avatars_can_be_uploaded(): void
12    {
13        Storage::fake('avatars');
14 
15        $file = UploadedFile::fake()->image('avatar.jpg');
16 
17        $response = $this->post('/avatar', [
18            'avatar' => $file,
19        ]);
20 
21        Storage::disk('avatars')->assertExists($file->hashName());
22    }
23}

If you would like to assert that a given file does not exist, you may use the assertMissing method provided by the Storage facade:

1Storage::fake('avatars');
2 
3// ...
4 
5Storage::disk('avatars')->assertMissing('missing.jpg');
1Storage::fake('avatars');
2 
3// ...
4 
5Storage::disk('avatars')->assertMissing('missing.jpg');

Fake File Customization

When creating files using the fake method provided by the UploadedFile class, you may specify the width, height, and size of the image (in kilobytes) in order to better test your application's validation rules:

1UploadedFile::fake()->image('avatar.jpg', $width, $height)->size(100);
1UploadedFile::fake()->image('avatar.jpg', $width, $height)->size(100);

In addition to creating images, you may create files of any other type using the create method:

1UploadedFile::fake()->create('document.pdf', $sizeInKilobytes);
1UploadedFile::fake()->create('document.pdf', $sizeInKilobytes);

If needed, you may pass a $mimeType argument to the method to explicitly define the MIME type that should be returned by the file:

1UploadedFile::fake()->create(
2    'document.pdf', $sizeInKilobytes, 'application/pdf'
3);
1UploadedFile::fake()->create(
2    'document.pdf', $sizeInKilobytes, 'application/pdf'
3);

Testing Views

Laravel also allows you to render a view without making a simulated HTTP request to the application. To accomplish this, you may call the view method within your test. The view method accepts the view name and an optional array of data. The method returns an instance of Illuminate\Testing\TestView, which offers several methods to conveniently make assertions about the view's contents:

1<?php
2 
3test('a welcome view can be rendered', function () {
4    $view = $this->view('welcome', ['name' => 'Taylor']);
5 
6    $view->assertSee('Taylor');
7});
1<?php
2 
3test('a welcome view can be rendered', function () {
4    $view = $this->view('welcome', ['name' => 'Taylor']);
5 
6    $view->assertSee('Taylor');
7});

 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    public function test_a_welcome_view_can_be_rendered(): void
10    {
11        $view = $this->view('welcome', ['name' => 'Taylor']);
12 
13        $view->assertSee('Taylor');
14    }
15}
 1<?php
 2 
 3namespace Tests\Feature;
 4 
 5use Tests\TestCase;
 6 
 7class ExampleTest extends TestCase
 8{
 9    public function test_a_welcome_view_can_be_rendered(): void
10    {
11        $view = $this->view('welcome', ['name' => 'Taylor']);
12 
13        $view->assertSee('Taylor');
14    }
15}

The TestView class provides the following assertion methods: assertSee, assertSeeInOrder, assertSeeText, assertSeeTextInOrder, assertDontSee, and assertDontSeeText.

If needed, you may get the raw, rendered view contents by casting the TestView instance to a string:

1$contents = (string) $this->view('welcome');
1$contents = (string) $this->view('welcome');

Sharing Errors

Some views may depend on errors shared in the global error bag provided by Laravel. To hydrate the error bag with error messages, you may use the withViewErrors method:

1$view = $this->withViewErrors([
2    'name' => ['Please provide a valid name.']
3])->view('form');
4 
5$view->assertSee('Please provide a valid name.');
1$view = $this->withViewErrors([
2    'name' => ['Please provide a valid name.']
3])->view('form');
4 
5$view->assertSee('Please provide a valid name.');

Rendering Blade and Components

If necessary, you may use the blade method to evaluate and render a raw Blade string. Like the view method, the blade method returns an instance of Illuminate\Testing\TestView:

1$view = $this->blade(
2    '<x-component :name="$name" />',
3    ['name' => 'Taylor']
4);
5 
6$view->assertSee('Taylor');
1$view = $this->blade(
2    '<x-component :name="$name" />',
3    ['name' => 'Taylor']
4);
5 
6$view->assertSee('Taylor');

You may use the component method to evaluate and render a Blade component. The component method returns an instance of Illuminate\Testing\TestComponent:

1$view = $this->component(Profile::class, ['name' => 'Taylor']);
2 
3$view->assertSee('Taylor');
1$view = $this->component(Profile::class, ['name' => 'Taylor']);
2 
3$view->assertSee('Taylor');

Available Assertions

Response Assertions

Laravel's Illuminate\Testing\TestResponse class provides a variety of custom assertion methods that you may utilize when testing your application. These assertions may be accessed on the response that is returned by the json, get, post, put, and delete test methods:

assertBadRequest

Assert that the response has a bad request (400) HTTP status code:

1$response->assertBadRequest();
1$response->assertBadRequest();

assertAccepted

Assert that the response has an accepted (202) HTTP status code:

1$response->assertAccepted();
1$response->assertAccepted();

assertConflict

Assert that the response has a conflict (409) HTTP status code:

1$response->assertConflict();
1$response->assertConflict();

assertCookie

Assert that the response contains the given cookie:

1$response->assertCookie($cookieName, $value = null);
1$response->assertCookie($cookieName, $value = null);

assertCookieExpired

Assert that the response contains the given cookie and it is expired:

1$response->assertCookieExpired($cookieName);
1$response->assertCookieExpired($cookieName);

assertCookieNotExpired

Assert that the response contains the given cookie and it is not expired:

1$response->assertCookieNotExpired($cookieName);
1$response->assertCookieNotExpired($cookieName);

assertCookieMissing

Assert that the response does not contain the given cookie:

1$response->assertCookieMissing($cookieName);
1$response->assertCookieMissing($cookieName);

assertCreated

Assert that the response has a 201 HTTP status code:

1$response->assertCreated();
1$response->assertCreated();

assertDontSee

Assert that the given string is not contained within the response returned by the application. This assertion will automatically escape the given string unless you pass a second argument of false:

1$response->assertDontSee($value, $escaped = true);
1$response->assertDontSee($value, $escaped = true);

assertDontSeeText

Assert that the given string is not contained within the response text. This assertion will automatically escape the given string unless you pass a second argument of false. This method will pass the response content to the strip_tags PHP function before making the assertion:

1$response->assertDontSeeText($value, $escaped = true);
1$response->assertDontSeeText($value, $escaped = true);

assertDownload

Assert that the response is a "download". Typically, this means the invoked route that returned the response returned a Response::download response, BinaryFileResponse, or Storage::download response:

1$response->assertDownload();
1$response->assertDownload();

If you wish, you may assert that the downloadable file was assigned a given file name:

1$response->assertDownload('image.jpg');
1$response->assertDownload('image.jpg');

assertExactJson

Assert that the response contains an exact match of the given JSON data:

1$response->assertExactJson(array $data);
1$response->assertExactJson(array $data);

assertExactJsonStructure

Assert that the response contains an exact match of the given JSON structure:

1$response->assertExactJsonStructure(array $data);
1$response->assertExactJsonStructure(array $data);

This method is a more strict variant of assertJsonStructure. In contrast with assertJsonStructure, this method will fail if the response contains any keys that aren't explicitly included in the expected JSON structure.

assertForbidden

Assert that the response has a forbidden (403) HTTP status code:

1$response->assertForbidden();
1$response->assertForbidden();

assertFound

Assert that the response has a found (302) HTTP status code:

1$response->assertFound();
1$response->assertFound();

assertGone

Assert that the response has a gone (410) HTTP status code:

1$response->assertGone();
1$response->assertGone();

assertHeader

Assert that the given header and value is present on the response:

1$response->assertHeader($headerName, $value = null);
1$response->assertHeader($headerName, $value = null);

assertHeaderMissing

Assert that the given header is not present on the response:

1$response->assertHeaderMissing($headerName);
1$response->assertHeaderMissing($headerName);

assertInternalServerError

Assert that the response has an "Internal Server Error" (500) HTTP status code:

1$response->assertInternalServerError();
1$response->assertInternalServerError();

assertJson

Assert that the response contains the given JSON data:

1$response->assertJson(array $data, $strict = false);
1$response->assertJson(array $data, $strict = false);

The assertJson method converts the response to an array to verify that the given array exists within the JSON response returned by the application. So, if there are other properties in the JSON response, this test will still pass as long as the given fragment is present.

assertJsonCount

Assert that the response JSON has an array with the expected number of items at the given key:

1$response->assertJsonCount($count, $key = null);
1$response->assertJsonCount($count, $key = null);

assertJsonFragment

Assert that the response contains the given JSON data anywhere in the response:

 1Route::get('/users', function () {
 2    return [
 3        'users' => [
 4            [
 5                'name' => 'Taylor Otwell',
 6            ],
 7        ],
 8    ];
 9});
10 
11$response->assertJsonFragment(['name' => 'Taylor Otwell']);
 1Route::get('/users', function () {
 2    return [
 3        'users' => [
 4            [
 5                'name' => 'Taylor Otwell',
 6            ],
 7        ],
 8    ];
 9});
10 
11$response->assertJsonFragment(['name' => 'Taylor Otwell']);

assertJsonIsArray

Assert that the response JSON is an array:

1$response->assertJsonIsArray();
1$response->assertJsonIsArray();

assertJsonIsObject

Assert that the response JSON is an object:

1$response->assertJsonIsObject();
1$response->assertJsonIsObject();

assertJsonMissing

Assert that the response does not contain the given JSON data:

1$response->assertJsonMissing(array $data);
1$response->assertJsonMissing(array $data);

assertJsonMissingExact

Assert that the response does not contain the exact JSON data:

1$response->assertJsonMissingExact(array $data);
1$response->assertJsonMissingExact(array $data);