Weave Code
Pest Plugin Agent Laravel Package
pestphp/pest-plugin-agent
Pest Plugin Agent extends Pest with agent-focused testing helpers and expectations, making it simple to write expressive, reliable tests for AI agent workflows in Laravel and PHP projects. Integrates with Pest's familiar syntax for confident agent testing.
AI agent verification plugin for Pest
Frequently asked questions about Pest Plugin Agent
- What is pestphp/pest-plugin-agent and what does the --agent flag actually do?
- It is a small Pest extension that lets an AI coding agent verify its own work with a single command. Running vendor/bin/pest --agent='<php snippet>' writes a temporary it('verify', ...) test file, executes it under your project's existing Pest configuration, and then deletes it. The snippet is a raw PHP body with no opening tag and no use statements, so every class must be fully qualified. That single command is essentially the whole product surface.
- How do I install Pest Plugin Agent in a Laravel project?
- Install it as a dev dependency with composer require --dev pestphp/pest-plugin-agent inside an existing Laravel project that already uses Pest. There is no service provider to register, no config file to publish, and no migration of your existing tests. It reuses the uses() and namespace bindings in tests/Pest.php, so your factories, actingAs(), Mail::fake() and seeders work unchanged. Because it is a dev-only dependency, you can remove it in an afternoon if it does not fit.
- Which Pest, PHP, and Laravel versions are supported by Pest Plugin Agent?
- There is currently no published version-support matrix for Pest majors, PHP, or Laravel, which is a real gap for anyone evaluating it. Confirm official support with the maintainer before relying on it, and pin the version in composer.json. Treat --agent as an experimental API until stability is documented, since the plugin is young and the browser-side helpers have already changed.
- Why does my --agent snippet fail with Class "User" not found?
- The generated temporary test file contains no namespace imports, so an unqualified User resolves to a class named User in the global namespace. Prefix every class reference with a leading backslash, for example \App\Models\User::factory() or \Illuminate\Support\Facades\Mail::fake(). The same rule applies to enums, exceptions, and any helper class you reference inside the snippet.
- How do I avoid shell quoting problems when passing a PHP snippet to pest --agent?
- Always use single outer quotes around the snippet, because double outer quotes let the shell interpolate $variables before PHP ever sees them. That silently corrupts the snippet and can produce a failure that looks real, or worse, a weakened check that passes. Never hand-escape dollar signs. If the snippet needs an apostrophe or a literal single quote, write the PHP body to a file and pass it with --agent="$(cat snippet.php)", which is the documented fallback.
- Can I use Pest Plugin Agent for browser tests with Playwright?
- Yes, as a separate optional layer, provided you have pestphp/pest-plugin-browser and Playwright configured. Your existing browser flows work through --agent, but use only documented API methods. onMobile() does not exist (the correct chain is ->on()->mobile()), and waitForText() is deprecated, so unverified method names will fail. Check the plugin's docs for the current browser API before writing snippets.
- Does --agent work with parallel test execution and in CI containers?
- Behavior under parallel test execution is not documented, and CI containers without a browser installed will break any browser-based snippets. For non-browser snippets it runs the same Pest runner your suite uses, so a normal CI image with your usual PHP setup should work. If you rely on it in CI, test the parallel case explicitly and keep browser verification in a separate job.
- Is it safe to run pest --agent in production?
- No. By design, --agent executes arbitrary PHP inside a bootstrapped Laravel application, so it belongs in local development and CI only. Treat it as a dev dependency surface and keep it out of production images and deployments. The same caution applies to any tool that runs agent-generated code against a real application container.
- Why is RefreshDatabase commented out in the generated agent test?
- It is a guardrail, not an oversight. If a snippet runs RefreshDatabase against a persistent or shared database, it will wipe that database. Point --agent at an in-memory or otherwise expendable test database, and only enable the trait deliberately when you are certain of the target connection. This is the single most dangerous default to get wrong in a real project.
- Is Pest Plugin Agent maintained, and what should I ask before adopting it?
- The project is early stage with a small maintainer base, so treat it as a convenient dev dependency rather than load-bearing infrastructure. Before a pilot, ask which Pest, PHP, and Laravel versions are officially supported, whether --agent is a stable API, how it behaves under parallel runs and browser-less CI, whether there is a timeout or snippet size cap, and whether temp-file cleanup survives an interrupted run. Also ask for a recommended pattern for auditing or gating agent-generated snippets, such as an allowlist plus logging. Alternatives are simply running a hand-written temporary Pest test yourself, which is more verbose but has none of these risks.
Weaver
How can I help you explore Laravel packages today?