Filament Screenshot Catalogue Laravel Package

Getting Started

Minimal Steps to First Use

1. Install the Package

   composer require --dev visualbuilder/filament-screenshot-catalogue
   

2. Register a Panel Descriptor Add a service provider (e.g., ScreenshotCatalogueServiceProvider) to bootstrap/providers.php with a PanelDescriptor for your Filament panel:

   PanelRegistry::register(new PanelDescriptor(
       key: 'admin',
       panelId: 'admin',
       domain: env('ADMIN_DOMAIN'),
       email: env('SCREENSHOT_ADMIN_EMAIL'),
       password: env('SCREENSHOT_ADMIN_PASSWORD'),
       authenticator: fn() => auth('web')->setUser(\App\Models\User::first()),
   ));
   

3. Set Up Dependencies Ensure Node.js 18+ and Playwright are installed:

   npm install playwright && npx playwright install chromium
   

4. Configure S3 Disk Add an S3 disk (e.g., s3_public) in config/filesystems.php and update config/screenshot-catalogue.php:

   'disk' => 's3_public',
   'path_prefix' => 'screenshots',
   

5. Generate Sitemap Discover all panel URLs:

   php artisan panel:sitemap --panel=admin
   

6. Capture Screenshots Queue a job to capture all pages:

   php artisan screenshot:dispatch --panel=admin --tag=latest
   

7. Access the Catalogue The browsable index (index.html) will be uploaded to S3 at: s3://{disk}/{prefix}/{env}/admin/latest/.

First Use Case: Debugging a UI Issue

• Run a one-off capture for a specific page (e.g., dashboard):

  php artisan screenshot:capture --panel=admin --page=dashboard --tag=debug
  

• Access the generated index.html to inspect the screenshot at different viewports (desktop/tablet/mobile) and modes (light/dark).

Implementation Patterns

Workflows

1. Continuous Visual QA

   • Schedule screenshot:dispatch in CI/CD (e.g., post-deploy) with a unique tag (e.g., tag=build-123).
   • Compare new screenshots against a baseline (e.g., using diff tools or AI like Claude) to catch regressions.

2. Design Reviews

   • Use --tag=design-review to generate a versioned catalogue for stakeholders.
   • Share the index.html link (hosted via S3 static website) for feedback.

3. Marketing Assets

   • Capture screenshots with capture_time_css to override animations (e.g., lock a hero section in place).
   • Export PNGs from S3 for marketing collateral.

4. AI-Driven Regression Testing

   • Integrate with tools like Claude (via the published skill) to auto-analyze screenshots for visual changes.
   • Example Claude prompt:

     Compare these two screenshots of a Filament panel dashboard:
     [screenshot-1.png] [screenshot-2.png]
     Highlight any visual differences, including layout shifts, missing elements, or style changes.
     

Integration Tips

1. Queue Workers

   • Run screenshot:dispatch in a queue worker (e.g., Redis) to avoid timeouts for large panels:

     php artisan queue:work
     

2. Custom Viewports

   • Override default viewports in config/screenshot-catalogue.php:

     'viewports' => [
         'desktop' => ['width' => 1920, 'height' => 1080],
         'mobile'  => ['width' => 414,  'height' => 896],
     ],
     

3. Exclude Pages

   • Skip sensitive or dynamic pages (e.g., users.edit with variable data):

     'excluded_slugs' => ['users.edit', 'settings.profile'],
     

4. Branding

   • Customize the catalogue’s appearance by publishing assets:

     php artisan vendor:publish --tag=filament-screenshot-catalogue-config
     

     Then update config/screenshot-catalogue.php:

     'brand' => [
         'name' => 'MyApp Admin',
         'logo' => public_path('logo.svg'),
     ],
     

5. Tenanted Panels

   • Set the tenant in the authenticator closure:

     authenticator: fn() => Filament::setTenant(\App\Models\Tenant::find(1)),
     

Gotchas and Tips

Pitfalls

1. Missing Dependencies

   • Error: Class 'Visualbuilder\FilamentScreenshotCatalogue\PanelRegistry' not found.
   • Fix: Ensure the package is installed (composer require --dev) and the provider is registered conditionally (wrap in class_exists for dev-only installs).

2. Playwright Failures

   • Error: Cannot find Chromium executable or TimeoutError.
   • Fix:
     • Install Playwright browsers explicitly:

       npx playwright install chromium firefox
       

     • Add --headful to debug:

       php artisan screenshot:capture --panel=admin --page=dashboard --tag=debug --headful
       

3. Authentication Issues

   • Error: "Unable to log in" or "403 Forbidden".
   • Fix:
     • Verify the authenticator closure sets the correct user/tenant.
     • Check if the user has the required permissions in Filament (e.g., viewAny for all resources).

4. S3 Upload Failures

   • Error: "Disk [s3_public] not configured".
   • Fix: Ensure the S3 disk is defined in config/filesystems.php and credentials are valid.

5. CSS Injection Not Working

   • Error: Animations or dynamic content still visible in screenshots.
   • Fix: Use capture_time_css to force a stable state:

     'capture_time_css' => '
         .fi-topbar { transition: none !important; }
         .dynamic-element { opacity: 0 !important; }
     ',
     

Debugging Tips

1. Log Sitemap Generation

   • Inspect storage/app/sitemap-admin.json to verify all expected pages are included. Exclude dynamic pages with excluded_slugs.

2. Check Queue Jobs

   • Monitor job progress with:

     php artisan queue:list
     php artisan queue:work --once
     

3. Inspect Playwright Output

   • Run Playwright in headful mode to see the browser:

     php artisan screenshot:capture --panel=admin --page=dashboard --tag=debug --headful
     

4. Validate S3 Structure

   • Verify the S3 path matches your path_prefix and disk config. Example:

     s3://my-bucket/screenshots/staging/admin/latest/dashboard/desktop-light.png
     

Extension Points

1. Custom Playwright Runner

   • Publish and override the Node runner:

     php artisan vendor:publish --tag=filament-screenshot-catalogue-js
     

   • Modify resources/js/runner.js to add custom Playwright logic (e.g., wait for specific elements).

2. Post-Capture Hooks

   • Extend the RebuildScreenshotIndexJob to add metadata or transform PNGs:

     // app/Providers/ScreenshotCatalogueServiceProvider.php
     use Visualbuilder\FilamentScreenshotCatalogue\Jobs\RebuildScreenshotIndexJob;
     
     RebuildScreenshotIndexJob::macro('addMetadata', function ($metadata) {
         $this->metadata = $metadata;
     });
     

3. Claude Integration

   • Use the published Claude skill to auto-generate reports:

     php artisan vendor:publish --tag=filament-screenshot-catalogue-claude-skills
     

   • Example Claude prompt (from .claude/commands/screenshot-catalogue.md):

     Analyze the visual differences between these two screenshots of the Filament dashboard:
     [screenshot-1.png] [screenshot-2.png]
     Focus on layout, colors, and missing elements. Provide a bullet-point summary.
     

4. Dynamic Tagging

   • Override the tag logic in app/Providers/ScreenshotCatalogueServiceProvider.php to use Git commit hashes:

     PanelRegistry::register(new PanelDescriptor(
         // ...
         tag: fn() => exec('git rev-parse --short HEAD'),
     ));