Pest Plugin Agent Laravel Package

Product Decisions This Supports

Agent self-verification as a roadmap primitive. The package answers one narrow, load-bearing question: how does an AI agent prove its own work inside a Laravel codebase? It takes a PHP snippet, wraps it in a temporary Pest test (it('verify', function () { … })), runs it under the project's existing test configuration, and deletes it. If agent-authored PRs are anywhere on the roadmap, this is the verification step underneath them — a roadmap input, not a developer convenience.

Build vs. buy — and the honest answer is "it's barely a build." A competent engineer reproduces this in under a day (write temp file, exec Pest, delete). The buy decision is not about capability. Buy if you are already on Pest and want upstream maintenance plus agent-facing docs at near-zero cost. Build if you need policy upstream won't carry — allowlists, sandboxing, artifact retention, audit logs. Either way, treat this as a low-stakes, reversible call.

Feature scoping: probes vs. regression tests. The docs draw the line explicitly: this is a probe, not a replacement for committed tests. That boundary belongs in your agent guidelines. Probes answer "does this work right now"; real tests answer "this must never break again." Without that rule, teams will ship agent-verified code with zero regression coverage and call it done — the most likely way this investment goes wrong.

Use cases worth trialing:

• Agent self-verification after backend edits — factories, actingAs(), Mail::fake(), notification and queue assertions.
• Visual/design review loops — screenshot a page after a Blade/Livewire/CSS change, including responsive viewports via ->on()->mobile() or ->resize(w, h).
• Full-stack smoke: drive the UI, assert a frontend signal, then assert the backend side effect (mail sent, order row created).
• Pre-handoff confidence checks during code review, so a human reviewer receives evidence rather than a claim.

Decisions this should not drive: CI test strategy, browser-test tooling choice (that is pest-plugin-browser), QA headcount, or coverage targets. This is a developer-experience accelerant — it makes checking faster, not testing better.

Instrument it if you adopt it. Track the percentage of agent tasks that self-verify before handoff, verification runs per completed task, false-negative rate (especially from the quote-interpolation trap), screenshot artifact churn, and human review cycles saved. Those numbers — not the star count — justify keeping it.

When to Consider This Package

Adopt when:

• You are on Laravel + Pest, with tests/Pest.php bindings already configured. Browser verification is optional and pulled in separately via pestphp/pest-plugin-browser plus Playwright.
• An AI agent or assistant is already writing or reviewing code in the repo. Without a caller, the value is zero.
• Your test database is in-memory SQLite or otherwise expendable. The docs explicitly warn that RefreshDatabase against a persistent database will wipe it. That is a hazard, not a footnote.
• You want one-shot verification without artifact sprawl — no scratch test files left behind, no throwaway commits.
• Your team can absorb the operator discipline: single outer quotes, fully qualified class names, documented browser methods only. The fact that the docs are this specific is a signal the maintainers know where agents fail.

Look elsewhere when:

• You are on PHPUnit without Pest. The entire contract is Pest closures and the expectation API. Not portable.
• You need governance before autonomy. --agent executes arbitrary PHP inside a bootstrapped application. In production-adjacent or shared environments, that surface needs a dev-only guardrail and a sandboxed database before anyone greenlights it.
• You need durable artifacts. Probes are ephemeral by design and screenshots are hardcoded to tests/Browser/Screenshots/. If compliance or audit requires retained evidence, wrap it yourself.
• You need vendor confidence. Seven stars, zero dependents, a 0.295 score, single-maintainer risk, and browser-API churn (onMobile() does not exist; waitForText() is deprecated). Acceptable for a dev dependency you can rip out in an afternoon; not acceptable if it becomes load-bearing.
• Your real problem is test coverage, not verification speed. If the suite is thin, this accelerates the wrong thing.

Migration cost if abandoned: near zero. It is a dev dependency wrapping a pattern you can inline into a Composer or shell script.

How to Pitch It (Stakeholders)

For executives. We are investing in AI-assisted development, and the binding constraint is not code generation — it is trust. Agents currently assert that things work; this package makes them demonstrate it in one command, using test infrastructure we already own and pay for. Adoption cost is a dev dependency plus a short enablement doc. The payoff is fewer human review cycles spent re-verifying agent claims and fewer "looks right, isn't" handoffs. It is early-stage, open-source, MIT-licensed, and trivially removable — a low-cost, low-lock-in bet. Recommendation: a contained trial on one or two repos with an in-memory test database, measured against review-cycle time, before any broader rollout. Do not let it become the only thing standing between us and shipping bugs: it verifies, it does not regress-guard.

For engineering. No new test framework, no new config layer, no parallel harness. It runs inside your existing Pest setup — uses() bindings, Feature/Browser namespaces, factories, fakes, and seeders all apply. The value is ergonomics: inline a snippet, get a pass/fail, no temp files to clean up. The costs are operational and known. A shell-quoting trap silently empties $variables under double outer quotes, producing a false pass or a confusing false failure; snippets must be real PHP with fully qualified class names because the generated file has no use imports; and RefreshDatabase against a persistent database is destructive. Treat the bundled SKILL.md as the contract, not as suggestions — most failure modes are already documented there, which is why initial setup effort is genuinely small. Scope it to require-dev, pin the version, point it at an in-memory database, keep committing real regression tests alongside it, and it earns its place.