README

Screentest CLI

CLI tool for automated screenshot generation of Filament plugins. Generates documentation screenshots in light and dark themes with zero manual effort.

Features

• Reads a screentest.json config from your plugin
• Creates a temporary Filament project via filakit
• Installs the plugin via path repository (symlink)
• Auto-generates seeds by analyzing Resources (static analysis)
• Captures screenshots with Puppeteer (light + dark themes)
• Saves to {plugin}/screenshots/{theme}/{name}.png
• Optionally updates README.md with screenshot references

Installation

composer global require jeffersongoncalves/screentest-cli

Quick Start

# Navigate to your Filament plugin directory
cd my-filament-plugin

# Initialize config (interactive)
screentest init

# Run the complete pipeline
screentest run

Commands

Configuration

The screentest.json file controls the entire process:

{
  "plugin": {
    "name": "My Filament Plugin",
    "package": "vendor/my-plugin"
  },
  "filakit": {
    "kit": "filakitphp/basev5"
  },
  "install": {
    "extra_packages": [],
    "plugins": [
      {
        "class": "Vendor\\MyPlugin\\MyPluginPlugin",
        "panel": "admin"
      }
    ],
    "publish": [],
    "post_install_commands": ["migrate"]
  },
  "seed": {
    "auto_detect": true,
    "user": {
      "email": "admin@example.com",
      "password": "password",
      "name": "Admin User"
    },
    "models": []
  },
  "screenshots": [
    {
      "name": "resource-list",
      "url": "admin/resources",
      "selector": "body",
      "viewport": { "width": 1920, "height": 1080, "deviceScaleFactor": 3 },
      "before": [
        { "action": "wait", "delay": 500 }
      ]
    }
  ],
  "output": {
    "directory": "screenshots",
    "themes": ["light", "dark"],
    "format": "png"
  },
  "readme": {
    "update": true,
    "section_marker": "<!-- SCREENSHOTS -->",
    "template": "table"
  }
}

Requirements

• PHP 8.2+
• Node.js (for Puppeteer)
• pnpm
• Composer
• Composer

How It Works

1. Init - Analyzes your plugin's composer.json and Resources to generate a config
2. Setup - Creates a temporary Filament project using filakit, installs your plugin via symlink
3. Seed - Auto-detects Filament Resources, maps fields to Faker methods, generates factories and seeders
4. Capture - Launches Puppeteer, logs into Filament, navigates to each URL, captures screenshots in light and dark themes
5. Readme - Updates your README.md between <!-- SCREENSHOTS --> markers with a table or gallery

Auto-Seed Field Mapping

License

Screentest CLI is open-source software licensed under the MIT license.