Phpunit Watcher Laravel Package

Getting Started

Install globally via composer global require spatie/phpunit-watcher, then run phpunit-watcher watch in any project directory to start automatic test reruns. The watcher will automatically detect changes in app, src, and tests directories and re-run PHPUnit on file modifications. This is ideal for TDD workflows—make a code change and immediately see test results without manual command repetition.

Implementation Patterns

• Inline filtering: Pass PHPUnit arguments directly to the watch command, e.g., phpunit-watcher watch --filter=FeatureTest for targeted test cycles.
• Config-driven setup: Create .phpunit-watcher.yml in project root to define persistent settings like watched directories, PHPUnit binary path, timeout, and initial arguments (e.g., --stop-on-failure). This ensures consistent behavior across team members.
• Composer integration: Add "test:watch": "phpunit-watcher watch < /dev/tty" to composer.json scripts, and disable timeouts with Composer\\Config::disableProcessTimeout for full interactivity.
• Nested config reuse: Leverage config lookup through parent directories for monorepos—place a shared config in the root and override only needed values in subdirectories.

Gotchas and Tips

• TTY on Windows: Interactive commands (keyboard shortcuts) are disabled due to lack of TTY support; set all PHPUnit args during initial invocation only.
• Performance tuning: For large repos, use exclude in config to omit directories like vendor/node_modules, and always specify fileMask: '*.php' to avoid watching non-PHP files.
• Config precedence: CLI args override config file settings—test with --filter= after config is set to avoid surprises.
• Desktop notifications: Disable failing/passing test notifications with notifications.failingTests: false to reduce noise during early development.
• Hidden help tips: Set hideManual: true in config to suppress repetitive keyboard instruction text after each test run.
• Config file lookup: The tool checks .phpunit-watcher.yml → phpunit-watcher.yml → phpunit-watcher.yml.dist and searches parent directories—ensure no stale config in parent folders overrides your project settings.