api-testing

api-testing

When to use

Use this skill when writing or reviewing API endpoint tests — integration tests, contract validation, response structure checks, or external service mocking.

Procedure: Write API tests

1. Understand the endpoint — Read the controller, form request, and existing tests. Understand expected behavior, edge cases, and auth requirements before writing anything.
2. Set up test data — Use seeders (preferred) or factories. Mock external services with Http::fake().
3. Enumerate test cases — Run the test-case-discovery funnel first; cover success, validation errors, authorization failures, and edge cases — floor per behavior: 1 happy + 1 boundary + 1 error (+1 abuse case; on data-returning endpoints the three broken-access-control negative tests are mandatory).
4. Assert response — Check status code, JSON structure, data values. Use assertJsonStructure().
5. Verify — Run the test. Must pass. Check no flaky assertions (no time-dependent, no random ordering).

Example

describe('GET /api/v1/projects', function () {
    it('returns paginated projects for authenticated user', function () {
        $user = loginAsTestUser();

        $response = $this->getJson('/api/v1/projects');

        $response->assertOk()
            ->assertJsonStructure([
                'data' => [['id', 'title', 'status']],
                'meta' => ['current_page', 'per_page', 'total'],
            ]);
    });

    it('returns 401 for unauthenticated request', function () {
        $this->getJson('/api/v1/projects')
            ->assertUnauthorized();
    });

    it('returns 403 when user lacks permission', function () {
        loginAsRestrictedUser();

        $this->getJson('/api/v1/projects')
            ->assertForbidden();
    });
});

Test categories

Happy path

Test the expected success scenario with valid input:

it('creates a project', function () {
    loginAsTestUser();

    $this->postJson('/api/v1/projects', [
        'title' => 'New Project',
        'customer_id' => $customerId,
    ])
        ->assertCreated()
        ->assertJsonPath('data.title', 'New Project');

    $this->assertDatabaseHas('projects', ['title' => 'New Project']);
});