When you're developing APIs or any web-based product using Laravel 11, testing plays a crucial role in ensuring that your application behaves as expected. Whether you're using PHPUnit, Pest PHP, or any other testing framework like Codeception, the goal remains the same: building confidence that your application performs reliably under all circumstances.

In this guide, we’ll break down some key aspects of testing APIs in Laravel 11 using the Pest PHP testing framework. Don’t worry if you prefer PHPUnit—most of the testing principles we discuss will apply regardless of the framework.

Why Testing Matters

Before diving into the code, let’s quickly cover why testing is essential. Testing isn't just about catching bugs—it’s about guaranteeing that each part of your API functions correctly and continues to work as intended when other parts of the system are modified.

Getting Started with Testing Your Laravel API

When working with APIs, the first thing you might want to test is how different types of users interact with your endpoints. For instance, let’s start by checking the status codes returned for authenticated and unauthenticated users.

#[Test]
public function unauthenticated_user_gets_correct_status_code(): void
{
    $this->getJson('/api/services')->assertStatus(HttpResponse::HTTP_UNAUTHORIZED);
}

Here, we’re testing that an unauthenticated user attempting to access the services route gets an HTTP 401 Unauthorized status code. This is a simple yet important test to ensure security measures are in place.

Testing for Authenticated Users

Next up, you’ll want to verify that authenticated users get the expected status code and data they are authorized to see.

#[Test]
public function authenticated_user_gets_correct_status_code(): void
{
    $this->actingAs(
        User::factory()->create(),
    )->getJson('/api/services')->assertStatus(HttpResponse::HTTP_OK);
}

Here, we authenticate the user using Laravel's actingAs() helper, run the same request, and expect an HTTP_OK status (200).

Simplifying with Fluent JSON Testing in Laravel 11

When testing your API, you’ll often need to check that the data returned by the API matches the expected format. Laravel’s Fluent JSON Testing makes this easy by allowing you to assert various parts of the JSON response.

For example, say you want to ensure that users only see resources they own.

#[Test]
public function user_sees_only_their_own_resources(): void
{
    $user = User::factory()->create();
    $otherUser = User::factory()->create();

    Service::factory()->count(2)->for($user)->create();
    Service::factory()->count(10)->for($otherUser)->create();

    $this->actingAs($user)->getJson('/api/services')->assertJsonCount(2, 'data');
}

In this test, the user should only see the two services they own, even though there are a total of twelve services in the database.

Structuring API Responses: Ensuring Compliance

Another crucial part of API development is ensuring that responses follow the correct structure, especially when working with standards like JSON.

Testing your response structure helps maintain consistency and meets API design expectations.

#[Test]
public function response_comes_in_standard_format(): void
{
    $user = User::factory()->create();
    Service::factory()->count(2)->for($user)->create();

    $response = $this->actingAs($user)->getJson('/api/services');

    $response->assertJsonStructure([
        'data' => [
            '*' => [
                'id',
                'type',
                'attributes' => [
                    'name',
                    'url',
                    'created_at'
                ],
                'links'
            ]
        ]
    ]);
}

This ensures that the API response includes the necessary keys like id, type, attributes, and links, adhering to the expected API response format.

Pagination: Ensuring Correct Data Flow

Most APIs implement some form of pagination to prevent overloading clients with data. Testing pagination ensures the API delivers the correct amount of data per page.

#[Test]
public function pagination_works_correctly(): void
{
    $user = User::factory()->create();
    Service::factory()->count(15)->for($user)->create();

    $this->actingAs($user)->getJson('/api/services')->assertJsonStructure([
        'data',
        'links',
        'meta'
    ])->assertJsonCount(10, 'data'); // assuming pagination is set to 10 items per page
}

By testing pagination, you ensure that your API delivers the correct number of records on each page and includes necessary metadata like links and meta for the pagination controls.

Debugging Tests: What to Do When Tests Fail

Even the best-written tests fail from time to time. When they do, it’s important to know how to debug them. One simple method is using Laravel's dump() and dd() functions to inspect the data:

dd($response->json());

This allows you to see the exact output of your API and diagnose what might be causing the test to fail.

Conclusion

Testing is a fundamental part of building reliable Laravel APIs. By ensuring that unauthenticated users receive the correct status codes, authenticated users access the correct data, and API responses follow the required structure, you can build robust, scalable applications. Tools like Pest PHP, PHPUnit, and Laravel’s Fluent JSON Testing make this process smooth and manageable.