HTTP Tests

Introduction
Customizing Request Headers
Session / Authentication
Testing JSON APIs
Testing File Uploads
Available Assertions
Response Assertions
Authentication Assertions

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

<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Foundation\Testing\WithoutMiddleware;

class ExampleTest extends TestCase

{
/**
* A basic test example.
*
* @return void
*/
public function testBasicTest()
{
$response = $this->get('/');

$response->assertStatus(200);
}
}

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.

Customizing Request Headers

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

<?php

class ExampleTest extends TestCase

{
/**
* A basic functional test example.
*
* @return void
*/
public function testBasicExample()
{
$response = $this->withHeaders([
'X-Header' => 'Value',
])->json('POST', '/user', ['name' => 'Sally']);

$response
->assertStatus(200)
->assertJson([
'created' => true,
]);
}
}

Session / Authentication
Laravel provides several helpers for working 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:

<?php

class ExampleTest extends TestCase

{
public function testApplication()
{
$response = $this->withSession(['foo' => 'bar'])
->get('/');
}
}

Of course, one common use of the session is for maintaining state for the authenticated user. 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:

<?php

2 of 10
 use App\User;

class ExampleTest extends TestCase

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

$response = $this->actingAs($user)
->withSession(['foo' => 'bar'])
->get('/');
}
}

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:

$this->actingAs($user, 'api')

Testing JSON APIs

Laravel also provides several helpers for testing JSON APIs and their responses. For example, the
json , get , post , put , patch , and delete methods may be used to issue 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 /user and assert that the expected data was returned:

<?php

class ExampleTest extends TestCase

{
/**
* A basic functional test example.
*
* @return void
*/
public function testBasicExample()
{
$response = $this->json('POST', '/user', ['name' => 'Sally']);

$response
->assertStatus(200)
->assertJson([
'created' => true,
]);
}
}

3 of 10
 The assertJson method converts the response to an array and utilizes
PHPUnit::assertArraySubset 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.

Verifying An Exact JSON Match

If you would like to verify that the given array is an exact match for the JSON returned by the
application, you should use the assertExactJson method:

<?php

class ExampleTest extends TestCase

{
/**
* A basic functional test example.
*
* @return void
*/
public function testBasicExample()
{
$response = $this->json('POST', '/user', ['name' => 'Sally']);

$response
->assertStatus(200)
->assertExactJson([
'created' => true,
]);
}
}

Testing File Uploads

The class provides a fake method which may be used to generate
Illuminate\Http\UploadedFile

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:

<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Foundation\Testing\WithoutMiddleware;

4 of 10
 class ExampleTest extends TestCase
{
public function testAvatarUpload()
{
Storage::fake('avatars');

$response = $this->json('POST', '/avatar', [

'avatar' => UploadedFile::fake()->image('avatar.jpg')
]);

// Assert the file was stored...

Storage::disk('avatars')->assertExists('avatar.jpg');

// Assert a file does not exist...

Storage::disk('avatars')->assertMissing('missing.jpg');
}
}

Fake File Customization

When creating files using the fake method, you may specify the width, height, and size of the image
in order to better test your validation rules:

UploadedFile::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:

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

Available Assertions
Response Assertions

Laravel provides a variety of custom assertion methods for your PHPUnit tests. These assertions may
be accessed on the response that is returned from the json , get , post , put , and delete test
methods:

assertCookie assertJsonFragment assertSessionHas

assertCookieExpired assertJsonMissing assertSessionHasAll
assertCookieMissing assertJsonMissingExact assertSessionHasErrors
assertDontSee assertJsonStructure assertSessionHasErrorsIn
assertDontSeeText assertJsonValidationErrors assertSessionMissing
assertExactJson assertPlainCookie assertStatus
assertHeader assertRedirect assertSuccessful
assertHeaderMissing assertSee assertViewHas
assertJson assertSeeText assertViewHasAll

5 of 10
assertViewIs assertViewMissing

assertCookie

Assert that the response contains the given cookie:

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

assertCookieExpired

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

$response->assertCookieExpired($cookieName);

assertCookieMissing

Assert that the response does not contains the given cookie:

$response->assertCookieMissing($cookieName);

assertDontSee

Assert that the given string is not contained within the response:

$response->assertDontSee($value);

assertDontSeeText

Assert that the given string is not contained within the response text:

$response->assertDontSeeText($value);

assertExactJson

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

$response->assertExactJson(array $data);

assertHeader

Assert that the given header is present on the response:

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

6 of 10
assertHeaderMissing

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

$response->assertHeaderMissing($headerName);

assertJson

Assert that the response contains the given JSON data:

$response->assertJson(array $data);

assertJsonFragment

Assert that the response contains the given JSON fragment:

$response->assertJsonFragment(array $data);

assertJsonMissing

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

$response->assertJsonMissing(array $data);

assertJsonMissingExact

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

$response->assertJsonMissingExact(array $data);

assertJsonStructure

Assert that the response has a given JSON structure:

$response->assertJsonStructure(array $structure);

assertJsonValidationErrors

Assert that the response has the given JSON validation errors for the given keys:

$response->assertJsonValidationErrors($keys);

7 of 10
assertPlainCookie

Assert that the response contains the given cookie (unencrypted):

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

assertRedirect

Assert that the response is a redirect to a given URI:

$response->assertRedirect($uri);

assertSee

Assert that the given string is contained within the response:

$response->assertSee($value);

assertSeeText

Assert that the given string is contained within the response text:

$response->assertSeeText($value);

assertSessionHas

Assert that the session contains the given piece of data:

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

assertSessionHasAll

Assert that the session has a given list of values:

$response->assertSessionHasAll($key, $value = null);

assertSessionHasErrors

Assert that the session contains an error for the given field:

$response->assertSessionHasErrors(array $keys, $format = null, $errorBag = 'default');

8 of 10
assertSessionHasErrorsIn

Assert that the session has the given errors:

$response->assertSessionHasErrorsIn($errorBag, $keys = [], $format = null);

assertSessionMissing

Assert that the session does not contain the given key:

$response->assertSessionMissing($key);

assertStatus

Assert that the response has a given code:

$response->assertStatus($code);

assertSuccessful

Assert that the response has a successful status code:

$response->assertSuccessful();

assertViewHas

Assert that the response view was given a piece of data:

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

assertViewHasAll

Assert that the response view has a given list of data:

$response->assertViewHasAll(array $data);

assertViewIs

Assert that the given view was returned by the route:

$response->assertViewIs($value);

9 of 10
assertViewMissing

Assert that the response view is missing a piece of bound data:

$response->assertViewMissing($key);

Authentication Assertions

Laravel also provides a variety of authentication related assertions for your PHPUnit tests:

Method Description

$this->assertAuthenticated($guard = null);
Assert that the user is
authenticated.

$this->assertGuest($guard = null);
Assert that the user is not
authenticated.

$this->assertAuthenticatedAs($user, $guard = null);

Assert that the given user is
authenticated.

$this->assertCredentials(array $credentials, $guard = null);

Assert that the given
credentials are valid.

$this->assertInvalidCredentials(array $credentials, $guard = null);

Assert that the given
credentials are invalid.

10 of 10