Testing Inertia Applications

jengo/inertia provides seamless testing utilities that integrate cleanly with CodeIgniter 4's FeatureTestTrait and Pest PHP without requiring awkward trait method aliasing or custom request verb overrides.

---

1. Setting Up Test Cases

In your Pest test or PHPUnit test case, simply use CodeIgniter's FeatureTestTrait and Jengo's InertiaAssertions trait:

namespace Tests\Feature;

use CodeIgniter\Test\CIUnitTestCase;
use CodeIgniter\Test\FeatureTestTrait;
use Jengo\Inertia\Testing\InertiaAssertions;

class DashboardTest extends CIUnitTestCase
{
    use FeatureTestTrait;
    use InertiaAssertions;
}

Or when using Pest:

use Tests\Support\FeatureRequestTestCase;

uses(FeatureRequestTestCase::class);

test('dashboard renders user data', function () {
    $result = $this->get('/dashboard');

    $this->assertInertia($result, function ($page) {
        $page->component('Dashboard')
            ->has('auth.user')
            ->where('auth.user.name', 'Ian')
            ->etc();
    });
});

---

2. Fluent Inertia Assertions (assertInertia)

The assertInertia() assertion verifies that the HTTP response was generated by Inertia and yields a fluent AssertableInertia object to test components, props, and reload behaviors.

$result = $this->get('/orders');

$this->assertInertia($result, function (AssertableInertia $page) {
    $page->component('Orders/Index')
        ->has('orders', 10)
        ->where('orders.0.status', 'completed')
        ->missing('secret_token')
        ->etc();
});

---

3. The inertia_test() / inertia() Helper

If you prefer fluent chaining directly on the response object:

$result = $this->get('/dashboard');

$this->inertia($result)
    ->assertInertiaFlash('message', 'Profile updated')
    ->assertInertiaFlashMissing('error');

You can also inspect props directly using dot-notation:

$props = $this->inertia($result)->inertiaProps();
$name = $this->inertia($result)->inertiaProps('user.name');

---

4. Testing Component Existence on Disk

You can ensure that tested page components actually exist in your frontend codebase by configuring $testing['ensure_page_exists'] in app/Config/Inertia.php:

public array $testing = [
    'ensure_page_exists' => true,
    'page_paths' => [
        resource_path('js/Pages'),
    ],
];

When enabled, calling $page->component('Dashboard') verifies that the component file physically exists on disk, failing the test if the file is absent:

$result = $this->get('/dashboard');

$result->assertInertia(fn (AssertableInertia $page) => $page
    ->component('Dashboard') // Fails if Dashboard component file is missing on disk
    ->has('totalUsers')
);