Testing

Lightpack extends PHPUnit to support integration tests for your HTTP routes, responses, and API endpoints. To feature test a route and its response, create a test class in tests/Http folder in your project root.

You can see an example of a test class provided in tests/ folder.

<?php

namespace Tests\Http;

use Lightpack\Testing\TestCase;

class HomeTest extends TestCase
{
    public function testItRendersHomePage()
    {
        $this->request('GET', '/');
        $this->assertResponseStatus(200);
    }
}

Making Requests

To test an HTTP route, use request() method. For testing a JSON API route, use requestJson() method. Both of these methods are used to simulate an HTTP request.

request()

This method takes 3 parameters:

For example, to make a GET request to /homepage route:

$this->request('GET', '/homepage');

For example, to make a POST request to /products route:

$this->request('POST', '/products', ['name' => 'Lightpack']);

requestJson()

Use this method to make JSON requests. It accepts the same parameters that request() method does. For example, to make a JSON POST request to /products route:

$this->requestJson('POST', '/products', ['name' => 'Lightpack']);

Asserting HTML Responses

Once you have made a request to a route, you can then assert returned response using following assertion methods:

$this->assertRouteNotFound();
$this->assertResponseStatus();
$this->assertResponseBody();
$this->assertResponseBodyContains();

Sets up an expectation that the next request to the given route will throw a RouteNotFoundException. Pass the route as the argument — the method internally makes the GET request and expects the exception.

$this->assertRouteNotFound('/invalid-route');

Asserts that the response status code matches the expected value. Pass the desired HTTP status code (e.g., 200 for OK, 302 for redirect, 404 for not found).

$this->request('POST', '/login', [
    'email' => 'foo@bar.com', 
    'password' => 'secret'
]);

$this->assertResponseStatus(302);

Asserts that the response body matches the given string exactly. Use this to confirm the precise output returned by the route.

$this->request('GET', '/hello');
$this->assertResponseBody('Hello, World!');

Asserts that the response body contains the given string. Use this for partial matches when you don't need to check the entire response.

$this->request('GET', '/page');
$this->assertResponseBodyContains('Welcome');

Asserting JSON Responses

$this->assertResponseHasValidJson();
$this->assertResponseJson();
$this->assertResponseJsonHasKey();
$this->assertResponseJsonKeyValue();
$this->assertResponseJsonKeyMissing();

Asserting Redirect Responses

$this->assertRedirectUrl();
$this->assertRedirectRoute();
$this->assertResponseIsRedirect();

Asserting Sessions

$this->withSession();
$this->assertSessionHas();
$this->assertSessionMissing();
$this->assertSessionHasErrors();
$this->assertSessionHasNoErrors();
$this->assertSessionHasOldInput();

Asserting Headers

$this->withHeaders();
$this->assertResponseHasHeader();
$this->assertResponseHeaderEquals();

Asserting Signed URLs

$this->assertInvalidUrlSignature();

Asserts that the request will throw an InvalidUrlSignatureException with a 403 status code.

Use this before making a request to a signed URL that should fail due to a tampered, invalid, expired, or missing signature.

  $this->assertInvalidUrlSignature();
  $this->request('GET', '/download/123?signature=bad');

Asserting Cookies

$this->withCookies();
$this->assertCookieHas();
$this->assertCookieEquals();
$this->assertCookieMissing();

Asserting Authentication

$this->assertGuest();
$this->assertAuthenticated();

Asserting File Uploads

$this->withFiles();

Asserting Emails

$this->assertMailSent();
$this->assertMailNotSent();
$this->assertMailCount();
$this->assertMailSubject();
$this->assertMailContains();
$this->assertMailSentFrom();
$this->assertMailSentTo();
$this->assertNoMailSentTo();
$this->assertMailSentToAll();
$this->assertMailCc();
$this->assertMailCcAll();
$this->assertMailBcc();
$this->assertMailBccAll();
$this->assertMailReplyTo();
$this->assertMailReplyToAll();
$this->assertMailHasAttachment();
$this->assertMailHasAttachments();
$this->assertMailHasNoAttachments();

Database Testing

For tests that interact with the database, use the DatabaseTrait to automatically manage migrations and transactions.

<?php

use Lightpack\Testing\TestCase;
use Lightpack\Testing\DatabaseTrait;

class UserDatabaseTest extends TestCase
{
    use DatabaseTrait;

    public function testUserCreation()
    {
        $user = new User();
        $user->email = 'test@example.com';
        $user->save();

        $this->assertNotNull($user->id);
    }
}

The DatabaseTrait provides:

Database Assertions

$this->assertDatabaseHas();
$this->assertDatabaseMissing();
$this->assertDatabaseCount();

Authentication Testing

Use auth()->loginAs() to simulate a logged-in user without requiring credentials.

public function testAuthenticatedUserCanAccessDashboard()
{
    $user = new User(1);

    auth()->loginAs($user);

    $this->request('GET', '/dashboard');
    $this->assertResponseStatus(200);
}

Testing protected routes:

public function testGuestCannotAccessProtectedRoute()
{
    $this->request('GET', '/admin/users');
    $this->assertResponseStatus(302);
    $this->assertRedirectRoute('login');
}

Testing API authentication:

public function testApiRequiresAuthentication()
{
    $this->requestJson('GET', '/api/users');
    $this->assertResponseStatus(401);
}

public function testApiWithValidToken()
{
    $this->withHeaders(['Authorization' => 'Bearer valid-token'])
         ->requestJson('GET', '/api/users');
    $this->assertResponseStatus(200);
}

Method Chaining

All assertion methods return $this, allowing you to chain multiple assertions:

$this->request('POST', '/login', [
        'email' => 'user@example.com',
        'password' => 'secret'
    ])
    ->assertResponseStatus(302)
    ->assertRedirectRoute('dashboard')
    ->assertSessionHasNoErrors()
    ->assertMailSent()
    ->assertMailSentTo('user@example.com');