Screentest Cli Laravel Package

Product Decisions This Supports

• Documentation and marketplace-quality gates for Filament plugins. Every screenshot in your plugin README becomes a reproducible build artifact rather than a hand-captured PNG that silently rots after a CSS refactor or a Filament major bump. This directly supports the "does this package look maintained and usable?" decision that plugin adopters make in the first ten seconds.
• Release readiness / upgrade risk. Before tagging a Filament or Laravel upgrade, run screentest against the plugin's own resource and page set in light and dark themes. A diff in the captured output is fast evidence that a dependency upgrade broke layout, navigation, or the panel theme — cheaper than maintaining a bespoke browser test suite for chrome-level UI that has no meaningful assertions.
• Build vs. buy for visual QA. Buying here means adopting a single JSON config and a CLI; building means standing up a throwaway Filament host app, seeding factories, driving headless Chrome, and templating README output — roughly the whole create → install → publish → post-install → build assets → seed → serve → capture → readme pipeline. The buy case is strong for anyone maintaining more than a couple of Filament plugins; the build case wins only if you already own a Playwright/Puppeteer harness with fixtures and CI wiring.
• Scope decisions on plugin surface area. The screentest.json analyzer detects resources and pages and lets you select which ones to capture (--screenshots=all or a comma list). What you choose to capture is a de facto statement of what your plugin's public surface is; resources that never appear in any screenshot are candidates for removal or for being flagged as advanced/opt-in.
• Support-ticket and onboarding cost. Screenshots are the cheapest form of "how do I know this is installed correctly?" Reducing setup ambiguity lowers support load and shortens the time-to-first-successful-render for new users.
• CI policy. Non-zero exit codes plus the built-in safety net (warning when a capture returns 4xx/5xx or matches a Laravel Whoops/Ignition error page) turns "screenshots exist" into a checkable signal. This supports a decision to enforce screenshot freshness on PRs rather than relying on reviewer diligence.
• Agent-assisted maintenance. init is explicitly non-interactive under a no-tty harness, with flags for name, package, screenshot selection, README update, and --deps for wrapped "kit" packages. This supports a roadmap item to let coding agents regenerate docs as part of routine dependency chores.

When to Consider This Package

Consider it when most of the following hold:

• You maintain one or more Filament plugins (or Filament panels) where the visible surface is admin resources and pages rather than a public marketing site.
• Your README already carries, or should carry, a screenshot table, and you are tired of it going stale.
• You can run headless Chrome in Docker in your environment (the package ships stubs/docker/); if containers are off the table, evaluate that cost first.
• Your plugin's setup is expressible as a declarative config: Composer package name, plugin class and panel, publish tags, post-install commands, .env keys, seed models, screenshot URLs.
• You want captures in both light and dark themes without writing theme-switching browser code.
• Your routes are ordinary authenticated panel routes, or you can express the awkward ones declaratively — signed routes via route/routeParams/signed are supported, so signature-gated confirmation pages are in scope.

Look elsewhere when:

• You need real visual regression testing with baselines and thresholds. The repository's own description.md describes route-based capture, baseline diffs, configurable pixel thresholds, and multi-viewport comparison — but the README, AGENTS.md, and release notes describe a Filament screenshot generator with README templating. That is a material discrepancy, not a detail. Until it is resolved, assume this is a screenshot generator and plan a separate tool (Percy, BackstopJS, Playwright toHaveScreenshot) for pixel-diff gating. Validate before you put it in a release gate.
• Your UI is not Filament. The pipeline is built around filakit base projects and panel resource discovery; a generic Inertia/Livewire app gets little of the value.
• You need stability guarantees. Two stars and a v1.0.4x patch cadence on a single-maintainer package mean you should be prepared to read the source, pin the version, and possibly fork. Do not make it a hard dependency of a release process you cannot debug.
• You require a vendor with support terms, SSO, or a hosted dashboard. This is a local CLI; there is no hosted anything.
• Your setup cannot be scripted. If installing your plugin requires interactive prompts or manual clicks, the pipeline stalls at install and no amount of config tuning helps.
• You need multi-guard, SSO, or heavily customized auth flows in the generated app. The capture path assumes straightforward seeding and login; the v1.0.41 hardening touched guest capture, login detection, and version-argument handling, which is a signal that these edges are still being shored up.

Adoption criteria if you proceed: pin the version; write screentest.json from stubs/screentest.json.stub and commit it; run the pipeline once locally and read the post-run warnings rather than only opening the PNGs; add it to CI as a non-blocking job first, then promote to blocking once it has been green for a few releases.

How to Pitch It (Stakeholders)

To executives — the one-paragraph version: Our Filament plugins live or die on whether they look right when someone first installs them, and today that evidence is hand-taken screenshots that go stale silently after a theme tweak or a dependency bump. This tool rebuilds a throwaway Laravel + Filament project, installs our plugin into it, seeds realistic data, captures every configured page in light and dark mode with headless Chrome, and rewrites the README table. It converts an undocumented manual chore into a repeatable command with an exit code, and it is small enough to evaluate in an afternoon.

To engineering — the honest version: This is a documentation automation and smoke-visual tool, not a regression-testing framework. It does not store baselines or compute pixel diffs, whatever the repo description says. What it does well is the boring part: standing up a disposable host app, publishing migration stubs that hasMigrations() leaves unpublished, flipping the env()-backed config flags that otherwise 404 an entire resource, seeding before a /1/edit capture, and generating signed URLs inside the temp project where the APP_KEY actually exists. That is precisely the plumbing nobody wants to write twice.

The risks to state up front: two stars, one maintainer, a version history that is still hardening edge cases in guest capture and login detection. It is a productivity win, not infrastructure you should bet a release process on. Pin it, vendor it or fork it if it becomes load-bearing, and if a true visual-regression gate is on the roadmap, budget for a second tool rather than assuming this one covers it.

The ask: one engineer-day to write the config for our two most-used plugins, run it locally, and report back on whether the captures are trustworthy enough to wire into CI as a non-blocking check — plus a decision on whether this becomes our standard README-screenshot path or stays a per-plugin experiment.