Articles

Everything You Can Test In Your Laravel Application

· 23 min readCoding

A common challenge in testing is not only HOW to test something, but WHAT you can test. That's why I have made a list of all the things I like to test in my applications.

This article is about the How and What to test in Laravel. If you want to learn about the Why you should write tests, check out my 3 Compelling Reasons For Developers To Write Tests article.

All test examples focus on testing concepts and can be applied to all testing frameworks. My examples are written with PEST.

Looking for something specific? Pick it:

Note: All examples can also be found on the dedicated repository.

Testing Page Response Status

Testing page response is one of the simplest tests to write; still, it is extremely useful.

It makes sure a page responds with the correct HTTP status code, primarily a 200 response.

PHPPlayer 1 console
it('gives back a successful response for home page', function () {
$this->get('/')->assertOk();
});
B: top · A: copyB

It's a straightforward test, but knowing your home page does not throw an error is crucial. So, if you want to write your first test, this is the one to start with.

Reference: Learn more about testing page responses on the official docs.

Testing Page Response Text

This test is similar to the first page response test. We also test the response, but this time we are interested in the content of the response.

PHPPlayer 1 console
it('lists products', function () {
// Arrange
$firstProduct = Product::factory()->create();
$secondProduct = Product::factory()->create();
// Act & Assert
$this->get('/')
->assertOk()
->assertSeeTextInOrder([
$firstProduct->title,
$secondProduct->title,
]);
});
B: top · A: copyB

Here we are ensuring we see our product titles on the home page. This is useful if you load the products from the database and ensure they are shown.

Here you also can be more specific, like when you only want to show released products.

PHPPlayer 1 console
it('lists released products', function () {
// Arrange
$releasedProduct = Product::factory()
->released()
->create();
$draftProduct = Product::factory()
->create();
// Act & Assert
$this->get('/')
->assertOk()
->assertSeeText($releasedProduct->title)
->assertDontSeeText($draftProduct->title);
});
B: top · A: copyB

It also demos how to test something that is not shown, which can be helpful too. This test wouldn't be that helpful if we only have static text on the home page.

Reference: Learn more about testing page responses on the official docs.

Testing Page Response View

Next to testing the response status and content, you can also test the view that is returned.

PHPPlayer 1 console
it('returns correct view', function() {
// Act & Assert
$this->get('/')
->assertOk()
->assertViewIs('home');
});
B: top · A: copyB

You can take this even further and test the data that is passed to the view.

PHPPlayer 1 console
it('returns correct view', function() {
// Act & Assert
$this->get('/')
->assertOk()
->assertViewIs('home')
->assertViewHas('products');
});
B: top · A: copyB
Reference: Learn more about testing page responses on the official docs.

Testing Page Response JSON

Often you want to return JSON data from your API. This is where you can use Laravel's JSON helpers, like the assertJson method.

PHPPlayer 1 console
it('returns all products as JSON', function () {
// Arrange
$product = Product::factory()->create();
$anotherProduct = Product::factory()->create();
// Act & Assert
$this->post('api/products')
->assertOk()
->assertJson([
[
'title' => $product->title,
'description' => $product->description,
],
[
'title' => $anotherProduct->title,
'description' => $anotherProduct->description,
],
]);
});
B: top · A: copyB
Reference: Learn more about testing page responses on the official docs.

Testing Against The Database

Since we store data in the database, we want to make sure that data is stored correctly. This is where Laravel can help you with some handy assertion helpers.

PHPPlayer 1 console
it('stores a product', function () {
// Act
$this->actingAs(User::factory()->create())
->post('product', [
'title' => 'Product name',
'description' => 'Product description',
])->assertSuccessful();
// Assert
$this->assertDatabaseCount(Product::class, 1);
$this->assertDatabaseHas(Product::class, [
'title' => 'Product name',
'description' => 'Product description',
]);
});
B: top · A: copyB

The example ensures that a product is created and stored in the database for our post route.

Reference: Find all database assertions on the official documentation.

Testing Validation

Validation is a crucial part of many applications. You want to make sure that only valid data can be submitted. By default, Laravel sends validation errors back to the user, which we can check with the assertInvalid method.

PHPPlayer 1 console
it('requires the title', function () {
// Act
$this->actingAs(User::factory()->create())
->post('product', [
'description' => 'Product description',
])->assertInvalid(['title' => 'required']);
});
it('requires the description', function () {
// Act
$this->actingAs(User::factory()->create())
->post('product', [
'title' => 'Product name',
])->assertInvalid(['description' => 'required']);
});
B: top · A: copyB

When dealing with many validation rules, using datasets can be pretty helpful. This can clean up your tests a lot.

PHPPlayer 1 console
it('requires title and description tested with a dataset', function($data, $error) {
// Act
$this->actingAs(User::factory()->create())
->post('product', $data)->assertInvalid($error);
})->with([
'title required' => [['description' => 'text'], ['title' => 'required']],
'description required' => [['title' => 'Title'], ['description' => 'required']],
]);
B: top · A: copyB
Reference: Learn more about validation assertions on the official docs.

Testing Models / Relationships

First, I like to test every relationship of a model. To be precise, we do not want to test the functionality of the relationship; this is what Laravel already does. We want to make sure that relationships are defined.

PHPPlayer 1 console
it('has products', function () {
// Arrange
$user = User::factory()
->has(Product::factory())
->create();
// Act
$products = $user->products;
// Assert
expect($products)
->toBeInstanceOf(Collection::class)
->first()->toBeInstanceOf(Product::class);
});
B: top · A: copyB

Developers have different opinions about what logic should be handled in a model, and that's ok. But if you add it, make sure also to test it.

PHPPlayer 1 console
it('only returns released courses for query scope', function () {
// Arrange
Course::factory()->released()->create();
Course::factory()->create();
// Act & Assert
expect(Course::released()->get())
->toHaveCount(1)
->first()->id->toEqual(1);
});
B: top · A: copyB

Another example would be a model accessor like:

PHPPlayer 1 console
protected function firstName(): Attribute
{
return Attribute::make(
get: fn (string $value) => ucfirst($value),
);
}
B: top · A: copyB

And the test would look like this:

PHPPlayer 1 console
it('capitalizes the first character of the first name', function () {
// Arrange
$user = User::factory()->create(['first_name' => 'christoph'])
// Act & Assert
expect($user->first_name)
->toBe('Christoph');
});
B: top · A: copyB

Testing Sending Mails

Laravel provides a lot of testing helpers, especially when using Facades.

PHPPlayer 1 console
class PublishPodcastController extends Controller
{
public function __invoke(Podcast $podcast)
{
// publish podcast
// ...
Mail::to($podcast->author)->send(new PodcastPublishedMail());
}
}
B: top · A: copyB

At the end of this controller, we are sending an email. In our test, we can hit the controller through an endpoint and make sure this email would have been sent.

PHPPlayer 1 console
it('sends email to podcast author', function() {
// Arrange
Mail::fake();
$podcast = Podcast::factory()->create();
// Act
$this->post(route('publish-podcast', $podcast));
// Assert
Mail::assertSent(PodcastPublishedMail::class);
});
B: top · A: copyB

Always run the Mail::fake() method at the beginning of your tests when testing emails. This makes sure no actual email is being sent to a user.

Most helper methods like assertSent also accept a callback as the second argument. In our case, it receives the mailable object. It contains all the email data, like the email to which it needs to be sent.

This allows you to make even more assertions, like about the `to-address´ of the email.

PHPPlayer 1 console
Mail::assertSent(PodcastPublishedMail::class, function(PodcastPublishedMail $mail) use ($podcast) {
return $mail->hasTo($podcast->author->email);
});
B: top · A: copyB
Reference: Learn more about testing mailables on the official docs.

Testing Mail Content

It also makes sense to test the content of an email. This is especially useful when you have a lot of emails in your application. You want to make sure that the content is correct.

PHPPlayer 1 console
it('contains the product title', function () {
// Arrange
$product = Product::factory()->make();
// Act
$mail = new PaymentSuccessfulMail($product);
// Assert
expect($mail)
->assertHasSubject('Your payment was successful')
->assertSeeInHtml($product->title);
});
B: top · A: copyB
Reference: Learn about all the other assertions for testing mail content on the official docs.

Testing Jobs & Queues

I like to test jobs and queues separately, starting from the outside. This means I test a job is being pushed to a queue.

PHPPlayer 1 console
it('dispatches an import products job', function () {
// Arrange
Queue::fake();
// Act
$this->post('import');
// Assert
Queue::assertPushed(ImportProductsJob::class);
});
B: top · A: copyB

This ensures that my job will be pushed to the queue for a specific trigger, like hitting an endpoint. Again, the Queue::fake() takes care of not pushing a job. We do not want to run the job at this point.

But we still have to test the job, right? Of course. It contains the crucial logic of this feature:

PHPPlayer 1 console
it('imports products', function() {
// Act
(new ImportProductsJob)->handle();
// Assert
$this->assertDatabaseCount(Product::class, 50);
// Make more assertions about the imported data
})
B: top · A: copyB

This new test concentrates on the job and what it should do. We trigger the job directly by calling the handle on it, which every job has.

Testing Notifications

Notifications are great for informing your users about important events. Make sure to test them too:

PHPPlayer 1 console
it('sends notification about new product', function () {
// Arrange
Notification::fake();
$user = User::factory()->create();
$product = Product::factory()->create();
// Act
$this->artisan(InformAboutNewProductCommand::class, [
'productId' => $product->id,
'userId' => $user->id,
]);
// Assert
Notification::assertSentTo(
[$user], NewProductNotification::class
);
});
B: top · A: copyB

In the example above, we test a notification sent to a user when a new product is created. We are using the artisan method to trigger the notification. This is a great way to test notifications triggered by a command.

Again, there is a fake method for the notification facade that makes sure no actual notification is being sent.

Reference: Learn more about testing notifications on the official docs.

Testing Actions

Actions are just simple classes that have one specific job. They are a great way to organize your code, and separate your logic from your controllers to keep them clean. But how do you test them?

Let's start again from the outside. First, we want to test that our action is called when hitting a specific endpoint.

PHPPlayer 1 console
it('calls add-product-to-user action', function () {
// Assert
$this->mock(AddProductToUserAction::class)
->shouldReceive('handle')
->atLeast()->once();
// Arrange
$product = Product::factory()->create();
$user = User::factory()->create();
// Act
$this->post("purchase/$user->id/$product->i");
});
B: top · A: copyB

We can do this by mocking our action class and expecting that the handle method is called. But, again, we are here not interested in what our action does; we want to make sure it is called when we hit our purchase controller.

To make this work, we must ensure that the container resolves our action.

PHPPlayer 1 console
class PurchaseController extends Controller
{
public function __invoke(User $user, Product $product): void
{
app(AddProductToUserAction::class->handle($user, $product);
// Send purchase success email, etc.
}
}
B: top · A: copyB

Then we can also test the action itself. Like a job, we call the handle method to trigger the action.

PHPPlayer 1 console
it('adds product to user', function () {
// Arrange
$product = Product::factory()->create();
$user = User::factory()->create();
// Act
(new AddProductToUserAction())->handle($user, $product);
// Assert
expect($user->products)
->toHaveCount(1)
->first()->id->toEqual($product->id);
});
B: top · A: copyB

Testing Commands

Commands, similar to actions or jobs, can be tested by triggering them directly. This is a great way to test the logic of your command.

PHPPlayer 1 console
it('merges two accounts', function () {
// Arrange
$user = User::factory()->create();
$userToBeMerged = User::factory()->create();
// Act
$this->artisan(MergeAccountsCommand::class, [
'userId' => $user->id,
'userToBeMergedId' => $userToBeMerged->id,
]);
// Assert
$this->assertDatabaseCount(User::class, 1);
$this->assertDatabaseHas(User::class, [
'id' => $user->id,
'name' => $user->name,
'email' => $user->email,
]);
});
B: top · A: copyB

Most interesting is the artisan method, which we can call in any Laravel test. It will trigger the command and run it. We can pass the arguments and options to the command as an array. The rest is very similar to other tests.

But there are some more things we can do with commands. We can also expect output of a command like questions or information messages.

PHPPlayer 1 console
it('asks for user ids', function() {
// Arrange
$user = User::factory()->create();
$userToBeMerged = User::factory()->create();
// Act & Assert
$this->artisan(MergeAccountsCommand::class)
->expectsQuestion('Please provide the user ID of the user you want to keep', $user->id)
->expectsQuestion('Please provide the user ID of the user you want to merge', $userToBeMerged->id)
->expectsOutput('Accounts merged successfully')
->assertSuccessful();
});
B: top · A: copyB

As you can see in the example above, this is very useful for testing commands that ask for user input. We can also expect output and make sure the command was successful, which means an exit code of 0.

Reference: Learn more about testing commands on the official docs.

Testing Middlewares

A Middleware is always connected to a request, so I like to test the whole request instead of the isolated middleware.

In our example, we have an archive page and first test the page's content.

PHPPlayer 1 console
it('shows archived products', function () {
// Arrange
$product = Product::factory()->create();
$archivedProduct = Product::factory()->archived()->create();
// Act & Assert
$this->get(action(PageArchiveController::class))
->assertSeeText($archivedProduct->title)
->assertDontSeeText($product->title);
});
B: top · A: copyB
Note: Instead of providing the string to the route "get" method manually, I'm using the "action" helper, which gets the route of a controller.

But we also attached a middleware to this route to check if the archive feature is enabled. If not, we will return a 404.

PHPPlayer 1 console
it('returns 404 when archive feature disabled', function() {
// Arrange
Feature::define('archive', false);
// Act & Assert
$this->get(action(PageArchiveController::class))
->assertNotFound();
});
B: top · A: copyB

As you can see, we do not test the middleware in isolation but the whole request and desired outcome.

Testing Cache

Caching is a crucial part of every application. But how do we test it? Let's take a look at this simple controller:

PHPPlayer 1 console
class CachedProductsApiController extends Controller
{
public function __invoke()
{
return Cache::remember('products', 60, function () {
return Product::all();
});
}
}
B: top · A: copyB

It uses the remember method of the Cache facade to cache the products for 60 minutes. And here is how we can test it:

PHPPlayer 1 console
it('calls cache remember method', function () {
// Assert
Cache::shouldReceive('remember')
->once()
->with('products', 60, Closure::class)
->andReturn(Product::all());
// Act
$this->post(action(CachedProductsApiController::class));
});
B: top · A: copyB

Similar to custom mocks, we can use the shouldReceive method of the Cache facade to mock the remember method. We can also make sure it is called with the correct parameters and returns the expected result.

Testing File Uploads

Similar to testing mails, notifications, or jobs, we can also test file uploads with the help of a facade.

PHPPlayer 1 console
it('uploads CSV file', function () {
// Arrange
Storage::fake('uploads');
$file = UploadedFile::fake()->image('statistics.csv');
// Act
$this->post(action(CsvUploadController::class), [
'file' => $file,
])->assertOk();
// Assert
Storage::disk('uploads')->assertExists($file->hashName());
});
B: top · A: copyB

The fake method of the Storage facade makes sure we do not store any files on our real storage disks. And the UploadedFile class helps us to create test files.

The storage facade also provides handy assertion helpers like assertExists, to make sure the file was uploaded.

Testing Exceptions

Sometimes it is a good thing when an exception is thrown because we intentionally want to stop the execution of our code. We can test that too.

PHPPlayer 1 console
it('stops if at least one account not found', function () {
// Act
$this->artisan(MergeAccountsCommand::class, [
'userId' => 1,
'userToBeMergedId' => 2,
]);
})->throws(ModelNotFoundException::class);
B: top · A: copyB

We can chain the throws method to our test in PEST. This will make sure that the exception is thrown.

Testing Units (Unit Tests)

Unit tests are great for testing small pieces of code, like a single method. No other dependencies are involved. This makes them very fast and easy to write.

Our example is about a data object. It contains a method that creates a new instance from an a webhook payload.

PHPPlayer 1 console
class UserData
{
public function __construct(
public string $email,
public string $name,
public string $country,
)
{}
public static function fromWebhookPayload(array $webhookCallData): UserData
{
return new self(
$webhookCallData['client_email'],
$webhookCallData['client_name'],
$webhookCallData['client_country'],
);
}
}
B: top · A: copyB

In the corresponding test, we only test what this method returns.

PHPPlayer 1 console
it('creates UserData object from paddle webhook call', function () {
// Arrange
$payload = [
'client_email' => 'test@test.at',
'client_name' => 'Christoph Rumpel',
'client_country' => 'AT',
];
// Act
$userData = UserData::fromWebhookPayload($payload);
// Assert
expect($userData)
->email->toBe('test@test.at')
->name->toBe('Christoph Rumpel')
->country->toBe('AT');
});
B: top · A: copyB

Faking HTTP Calls

Sometimes you need to make HTTP calls in your application. This could be to fetch data from an external API or to send data to another service. You often want to fake these calls in your tests so you do not have to rely on an external service.

PHPPlayer 1 console
it('import product', function () {
// Arrange
Http::fake();
// Act & Assert
// ...
});
B: top · A: copyB

The fake method on the HTTP facade will ensure no real call is made and that the response is always a 200 status code.

But you can be more specific too. For example, we are testing an action that fetches data from an external API and saves it to the database.

PHPPlayer 1 console
it('imports product', function() {
// Arrange
Http::fake([
'https://christoph-rumpel.com/import' => Http::response([
'title' => 'My new product',
'description' => 'This is a description',
]),
]);
$user = User::factory()->create();
// Act
(new ImportProductAction)->handle($user);
// Assert
$this->assertDatabaseHas(Product::class, [
'title' => 'My new product',
'description' => 'This is a description',
]);
});
B: top · A: copyB

Testing HTTP Calls

Next to faking HTTP calls, you can also test if a specific call was made. This is useful when you want to ensure that your code makes the right calls.

PHPPlayer 1 console
it('make the right call', function () {
// Arrange
Http::fake();
$user = User::factory()->create();
// Act
(new ImportProductAction)->handle($user);
// Assert
Http::assertSent(function ($request) {
return $request->url() === 'https://christoph-rumpel.com/import'
&& $request['accessToken'] === '123456';
});
});
B: top · A: copyB
Reference: Learn more about faking HTTP calls on the official docs.

Mocking Dependencies

When working with code with dependencies, it can be helpful to mock them. This will let you concentrate on the logic of your code and not on the dependencies. This also means mocking can be useful for any kind of tests.

We already did that when testing our action classes, but this works with any dependency. In the following example, we have a controller with two dependencies: a payment provider and a mailer.

PHPPlayer 1 console
class PaymentController extends Controller
{
public function __invoke(PaymentProvider $paymentProvider, Mailer $mailer)
{
$paymentProvider->handle();
$mailer->to(auth()->user())->send(new PaymentSuccessfulMail);
}
}
B: top · A: copyB

In our test, we want to focus on testing that the correct email is being sent. That's why we can mock the payment provider and expect the handle method to be called. As a result, our test will not fail, even though the actual payment provider is never called.

PHPPlayer 1 console
it('sends payment successful mail', function () {
// Arrange
Mail::fake();
// Expect
$this->mock(PaymentProvider::class)
->shouldReceive('handle')
->once();
// Act
$this->post('payment');
// Assert
Mail::assertSent(PaymentSuccessfulMail::class);
});
B: top · A: copyB

Architecture Testing

PEST introduced a new type of test called Architecture Testing. It is a way to test your application's architecture and make sure it is following the rules you defined. This is a great way to make sure your code stays clean and maintainable.

PHPPlayer 1 console
test('no forgotten debug statements')
->expect(['dd', 'dump'])
->not->toBeUsed();
B: top · A: copyB

My favorite rule is to check that I didn't forget any debug statements in my code. I am sure you have been there too. You deploy your application to production, and suddenly you see a dd statement on your page. This is embarrassing and can be avoided with architecture tests.

There are many more rules you can define. Read more about them in the official docs.

Conclusion

Being aware of the different types of tests and how to write them is a great skill to have. It will help you write better code and make sure that your application is working as expected.

You might want to learn more about...

Is there anything I forgot to mention? If so, please let me know on Twitter. I am always happy to learn new things too.