Screentest CLI

https://github.com/jeffersongoncalves/screentest-cli
Admin
Screentest CLI is an automated screenshot generation tool for Filament plugins that spins up...
Tokens:4,994
Snippets:33
Trust Score:9.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quick Start: Initialize and Run Screentest

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/README.md

Quick start commands: navigate to your Filament plugin, initialize the config interactively, then run the full pipeline (setup, seed, capture, readme, cleanup).

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

# Initialize config (interactive)
screentest init

# Run the complete pipeline
screentest run
```

--------------------------------

### Screentest Configuration Example (screentest.json)

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/README.md

Example screentest.json configuration controlling the entire pipeline: plugin metadata, filakit kit, install plugins, seed settings, screenshot definitions, output themes, and README update options.

```json
{
  "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 },
      "fullPage": false,
      "before": [
        { "action": "wait", "delay": 500 }
      ]
    }
  ],
  "output": {
    "directory": "screenshots",
    "themes": ["light", "dark"],
    "format": "png"
  },
  "readme": {
    "update": true,
    "section_marker": "<!-- SCREENSHOTS -->",
    "template": "table"
  }
}
```

--------------------------------

### Example screentest.json configuration

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/AGENTS.md

A JSONC example showing the structure of a screentest.json file. The install.publish array is the #1 cause of blank/404 screenshots, and the env object writes KEY=value pairs into the temp project's .env. Ordering matters: install/publish/post-install run before seeding and before the browser loads any page.

```jsonc
{
  "plugin": { "name": "...", "package": "vendor/package" },
  "filakit": { "kit": "filakitphp/basev5" },
  "install": {
    "extra_packages": [],           // composer packages beyond the plugin itself
    "plugins": [{ "class": "Vendor\\Plugin\\Class", "panel": "admin" }],
    "publish": [],                  // vendor:publish --tag=<...> — see below, this is the #1 cause of blank/404 screenshots
    "post_install_commands": ["migrate"],
    "env": {}                       // KEY=value pairs written into the temp project's .env — see below
  },
  "seed": {
    "auto_detect": true,
    "user": { "email": "admin@example.com", "password": "password", "name": "Admin User" },
    "models": [{ "model": "Vendor\\Plugin\\Models\\Thing", "count": 10 }]
  },
  "screenshots": [{ "name": "thing-list", "url": "/admin/things" }],
  "output": { "directory": "screenshots", "themes": ["light", "dark"], "format": "png" },
  "readme": { "update": true, "section_marker": "<!-- SCREENSHOTS -->", "template": "table" }
}
```

--------------------------------

### Install dependencies with composer install

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/AGENTS.md

Run this command in the repository root to install the project's Composer dependencies.

```bash
composer install
```

--------------------------------

### Install Screentest CLI with Composer

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/README.md

Installs the Screentest CLI globally via Composer. Requires PHP 8.2+ and Composer.

```bash
composer global require jeffersongoncalves/screentest-cli
```

--------------------------------

### Run screentest init non-interactively

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/AGENTS.md

Use this command in CI or agent harnesses without a TTY. It skips all prompts and uses the provided flags or defaults. --name and --package default to the analyzer's guess, --screenshots defaults to 'all', and --no-readme skips the README update.

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

--------------------------------

### Discover publish tags for .php.stub migrations

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/AGENTS.md

Use to discover the exact publish tag(s) for a package that ships migrations as .php.stub. The first command publishes everything and prints the tag names; the second tests a guessed tag and reports "No publishable resources for tag [...]" if wrong. Run this in a temp or scratch project before adding the confirmed tag to install.publish in screentest.json.

```bash
cd <temp-or-scratch-project>
php artisan vendor:publish --provider="Vendor\Plugin\PluginServiceProvider"   # publishes everything, prints exact tag names used
# or, once you have a guess:
php artisan vendor:publish --tag=<guess> --force   # "No publishable resources for tag [...]" means wrong guess
```

--------------------------------

### Enable feature flags in screentest.json install.env

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/AGENTS.md

Set env-backed feature flags in screentest.json to enable resource registration for plugins that gate resources on config values. These values are written into the temp project's .env before install/seed/serve via ProjectService::ensureEnvironment(). Use when a resource 404s because its route is not registered due to a false default.

```json
"install": {
  "env": {
    "SHORT_URL_API_ENABLED": "true",
    "SHORT_URL_DOMAINS_ENABLED": "true",
    "SHORT_URL_BIO_ENABLED": "true"
  }
}
```

--------------------------------

### Run Pest and Pint commands

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/AGENTS.md

Use these commands to run the Pest test suite and Laravel Pint code style checks. The --test flag for Pint performs a check only, while running Pint without flags applies fixes.

```bash
php vendor/bin/pest --parallel   # Pest test suite
```

```bash
php vendor/bin/pint --test       # Laravel Pint (check only)
```

```bash
php vendor/bin/pint              # Laravel Pint (fix)
```

--------------------------------

### Configure a signed route URL for Screenshot

Source: https://github.com/jeffersongoncalves/screentest-cli/blob/main/AGENTS.md

Use this JSON configuration in a Screenshot URL definition to generate a signed route URL. The `signed` flag must be true to produce a valid signature; otherwise, the route is resolved by name without a signature. This is required when the target route is protected by Laravel's `signed` middleware.

```json
{ "name": "confirm", "route": "newsletter.confirm", "routeParams": { "emailGroupMember": 1 }, "signed": true }
```
Tokens:
Raw