Pest Plugin Watch Laravel Package

Getting Started

Install the plugin via Composer:

composer require --dev pestphp/pest-plugin-watch

Then run tests in watch mode:

vendor/bin/pest --watch

This is ideal for TDD workflows—start the command and let it re-run tests automatically as files change. Check pest.php or config file (e.g., pest.php) for basic options like --only-changed or --retry-on-failure support via CLI flags.

Implementation Patterns

• TDD Loop: Run pest --watch in a terminal alongside your editor. Modify test or source files, and watch tests re-run instantly.
• CI/Local Dev Separation: Use Pest::beforeEach(fn () => $this->app->make('cache')->flush()) or custom event listeners inside your test suite to reset state before each run in watch mode—avoid side effects between re-runs.
• Integrate with IDE: Set up a terminal panel (e.g., in PhpStorm or VS Code) to run pest --watch, and combine with --filter or --group for targeted retries.
• Custom Watch Paths: Configure Pest::paths([...]) in pest.php to include or exclude directories beyond defaults (e.g., ->paths(['app/', 'tests/'])).

Gotchas and Tips

• Stale File Handles: On macOS/Linux, avoid opening the same file in multiple editors or tools (e.g., tail -f, IDE auto-save conflicts), which can cause the React-based watcher to miss or double-fire events. Use rm -rf .pest/cache && vendor/bin/pest --watch to reset if stuck.
• No Manual --stop-on-failure: This flag is ignored in watch mode—use Pest::failOnWarning(true) and Pest::failOnDeprecation(true) for stricter early feedback.
• Restart Required for Config Changes: pest.php or .pest/ config changes won’t auto-reload mid-watch session. Press Ctrl+C and restart.
• PHP 8.2+ Requirement: Ensure your environment meets the runtime dependency (^8.2.0). Use php -v to confirm.
• Legacy Mode: If you see “watcher is not available” errors, verify react/child-process and react/event-loop are installed—some Composer lockfiles may exclude dev dependencies in production builds.