Inertia Laravel Testing Laravel Package

Product Decisions This Supports

• De-risking the Inertia.js bet. The standing objection to an Inertia SPA is "we lose easy testability." Server-side assertions on the page object (component name, props, URL, partial reloads) remove that objection without standing up a browser/E2E stack for every page. That makes Inertia a cheaper architectural bet to approve.
• Build vs. buy on test tooling. The real decision is not "this package vs. nothing" — it's "this package vs. homegrown test macros vs. inertia-laravel core." Hand-rolled assertion helpers are permanent maintenance debt; a dev-only dependency is not. But the archived status (last release Jan 2021) is decisive evidence that the ecosystem answer moved into core, so the correct "buy" is now core, and this repo is a reference implementation rather than a dependency.
• Release-gating and QA cost. Prop-contract tests catch the most common Inertia regression — a controller stops sending the shape the frontend destructures — at the server layer, in milliseconds. That shortens manual QA cycles and makes frontend refactors safe to schedule.
• Concrete use cases to scope roadmap work against: asserting component + props on a response; verifying partial reloads and only prop filtering; locking shared props (auth, flash, validation errors); and pinning the backend/frontend data contract during upgrades (Inertia version bumps, Laravel major upgrades, design-system prop changes).
• Dependency-policy signal. An archived, 131-star, single-maintainer, dev-only package is a useful test case for whether your org's supply-chain policy is proportionate: near-zero runtime blast radius, reversible in one composer remove, and therefore a low-stakes place to draw the line rather than a place to make an exception.
• Historical signal on churn. 2.2.5 was a second attempt at fixing 2.2.4's incomplete fix. Correctness churn in the assertion layer is exactly the kind of thing that quietly erodes trust in a test suite — a reminder to pin exact versions and run the full suite on any bump, whatever you adopt.

When to Consider This Package

Adopt only in a narrow legacy case:

• You run Laravel + Inertia.js, your inertia-laravel version predates the bundled assertInertia / AssertableInertia helpers, and you cannot upgrade that dependency this quarter.
• You need prop-contract coverage now and the alternative is bespoke macros or browser tests.
• Your Laravel/PHP versions fall inside the package's (2021-era) support matrix — verify before committing, and expect this to fail on modern PHP.
• You accept it as a temporary, pinned, dev-only stopgap with a named owner and a removal ticket.

Look elsewhere — which is the default answer today:

• It is archived. Unmaintained code in the test layer is worse than no helper: it fails in confusing ways, and nobody upstream will fix it. Do not add it to a new project.
• inertia-laravel core already ships these helpers. This is the first thing to check; if core covers it, this package is a duplicate source of truth and should be dropped, not adopted.
• You need real browser behavior — JS rendering, hydration, client-side routing, visual state. That's Dusk/Playwright; this asserts server payloads only.
• Your prop contracts are already enforced by generated TypeScript types or an OpenAPI/schema layer, making PHP-side assertions duplicative.
• Your org has a hard policy against archived or single-maintainer dependencies (mitigated by dev-only status, but still a policy question to answer explicitly).
• You're still evaluating Inertia vs. alternatives — this is a cost reducer after that decision, never an input to it.

How to Pitch It (Stakeholders)

For executives: A small, free, dev-only testing utility that protects the Inertia frontend investment. It ships nothing to production, adds no runtime risk, and lets us verify page behavior in fast server-side tests instead of slow browser tests — faster, cheaper, safer releases. Cost is essentially zero. However: the project is archived as of 2021, and the same capability now lives in Inertia's own Laravel integration. So the recommendation is not "adopt this" — it's "standardize on the built-in helpers," and treat this repo as a documented pattern for how to write those assertions.

For engineering: It demonstrates fluent assertions over Inertia responses — component(), url(), prop counts and values, nested closures, etc() to permit shared props, missing() to prove lazy props are excluded on partial reloads — so we stop maintaining homegrown test macros and stop burning browser-test minutes on things PHP can assert. Integration was a single dev dependency plus a trait on the base test case. We should get the same ergonomics from core; where core's API differs, port the patterns, not the package.

Known risks to state plainly: (1) Archived and unmaintained — no security or compatibility fixes, and modern PHP/Laravel will likely break it; (2) namespace collision with Inertia\Testing\AssertableInertia, which now exists in core, so which class loads is ambiguous and debugging is confusing; (3) exhaustive-by-default assertions mean newly shared props break tests, which teams misread as flakiness. Mitigations: use core where available, pin exact versions if anything legacy must stay, keep the abstraction thin (a trait on TestCase, nothing deeper), and be able to delete it in an afternoon.

Recommendation: Do not introduce this package. Confirm what your inertia-laravel version already provides, adopt core's helpers, and use this repository's README and assertion patterns as the template for our base test case and prop-contract tests. If a legacy service is stuck on an old inertia-laravel, permit this only as a pinned stopgap with an owner and a removal date.