Screentest Cli Laravel Package

Getting Started

• Install the screentest binary (Laravel Zero app) as a dev dependency or globally, and confirm Docker is available — the bundled headless Chrome lives under stubs/docker/, so screenshots won't render without it.
• cd into the Filament plugin you want to document (not the host app), then run screentest init. It analyzes the plugin, guesses the package name, detects resources/pages, and writes a screentest.json at the repo root.
• For CI or an agent harness with no TTY, drive init with flags instead of prompts:

  screentest init --path=. \
    --name="My Plugin" \
    --package=vendor/my-plugin \
    --screenshots=all \
    --no-readme
  

  Add --deps=vendor/wrapped-package when the plugin is a thin wrapper around a standalone "kit" package.
• Review the generated screentest.json in this order: plugin → filakit → install.publish → install.env → seed → screenshots → output → readme. Those are the fields that break screenshots most often.
• First real run: screentest run. It executes the full pipeline create → install → publish → post-install → build assets → seed → serve → capture → readme, drops PNGs into output.directory, and rewrites the README section between the configured markers.
• Where to look first if something is off: the README, stubs/screentest.json.stub (the fully annotated config reference), and stubs/docker/ for the browser image. Then CaptureService for URL resolution and warning behavior.

Implementation Patterns

• Treat screentest.json as committed config. One file per plugin repo, reviewed in PRs like any other build config. It declares targets, seeding, and README output in one place.
• Respect pipeline order. install (extra packages, plugin registration, publish, post_install_commands, env) always runs before seed, which runs before serve and capture. Ordering inside the JSON doesn't matter — a publish tag being present does.
• Publish stub migrations explicitly. For packages using spatie/laravel-package-tools with ->hasMigrations(), migrations ship as *.php.stub and are not auto-loaded. Add the publish tag to install.publish; the tag is shortName() . '-migrations' (e.g. laravel-short-url → short-url-migrations). Confirm with php artisan vendor:publish --provider="Vendor\Plugin\PluginServiceProvider" inside a scratch project rather than guessing.
• Set env flags for conditionally registered resources. If a plugin gates a Filament resource on config('package.feature.enabled', false) backed by env('SOME_FLAG', false), put "SOME_FLAG": "true" in install.env. These are written into the temp project's .env before install/seed/serve.
• Seed what the URLs need. seed.auto_detect: true plus an explicit seed.models list ({ "model": "...", "count": 10 }) covers list pages and /1/edit-style URLs. Explicit models beat auto-detection when factories miss required relations.
• Prefer named routes for anything gated. Use route + routeParams with signed: true for routes behind Laravel's signed middleware; a literal url can't carry a valid signature because it depends on the temp project's APP_KEY. CaptureService::resolveRouteUrls() injects a throwaway screentest:resolve-urls command into the temp project to generate real signed URLs.
• Document both themes. output.themes: ["light", "dark"] gives parity between Filament panel modes in a single run; expect roughly 2× capture time.
• Drive README updates via a stable marker and template (<!-- SCREENSHOTS -->, "template": "table"). Keep everything inside the marker generated, everything outside hand-written.
• Split runs for iteration. screentest run = full pipeline from scratch; screentest capture reuses the temp project and just re-shoots the configured URLs. Use capture while tuning selectors/URLs, run for a clean verification and CI.
• CI shape. Invoke screentest run on release PRs or a scheduled job, fail the build on non-zero exit, and upload output.directory as an artifact. Use --no-readme on init if README updates are handled elsewhere.

Gotchas and Tips

• Identical, content-less screenshots across every page = missing publish flag. Symptom: every listing/edit shot is the same generic Laravel error page (or SQLSTATE ... no such table: X with debug on). Fix install.publish first; don't chase CSS or selectors.
• One 404, everything else fine = env-gated resource. A route that doesn't exist (real 404) is different from a route that exists but errors (500). Grep getResources() for config('...') calls, then check the referenced package's config/*.php for the matching env(..., false) default and set it in install.env.
• Seeding can fail silently. Generating and running seeds: ✔ can still leave a table empty when a factory throws on required relations. If an /1/edit screenshot looks wrong, verify row count before assuming a capture bug.
• Never hardcode signed URLs. A literal url with a signature will 403 in the temp project. Use route/routeParams/signed: true; a bad route name or param surfaces as a normal failed CaptureResult per theme, which is the signal to look at.
• Warnings are not failures. capture/run prints a warning (after the run, no non-zero exit) when a screenshot's HTTP status is 4xx/5xx or the HTML looks like a Laravel debug page. A green CI run can still ship blank PNGs — scrape the CLI output or diff PNG sizes in CI if you need hard guarantees.
• v1.0.41 is a hardening patch (guest capture, login detection, version argument). Low upgrade risk, but explicitly regression-test: guest capture, authenticated capture alongside it, and version-argument parsing (null/empty/invalid values must not break a run).
• Validate the version argument at the boundary. Normalize/fall back to a configured version and pass the resolved string into the capture payload; don't read it ad hoc deeper in the pipeline.
• Long-running workers (Octane/queues): the temp-project capture path is stateful. Don't reuse a service instance across requests/jobs; resolve identity before any dispatch.
• Docker is load-bearing. Missing or misconfigured Docker is the most common "nothing renders" cause on a fresh machine or CI runner; check the stubs/docker/ image before debugging Filament code.
• Assets must build. If pages render unstyled, look at the build assets stage for Vite/npm failures in the temp project, not the screenshot config.
• Marketing vs. reality. The package description advertises baseline diffs and viewport matrices, but the documented config surface centers on theme screenshot generation and README updates. Plan your workflow around capture + README for docs; don't assume a regression-diff engine unless you can find it in the config schema.
• Don't commit the temp project. Treat the throwaway Laravel+Filament app as ephemeral; commit only screentest.json and the generated images under output.directory.