Open-Source Testing · spatie

phpunit-watcher

phpunit-watcher is a PHP development tool that automatically reruns PHPUnit tests whenever source code changes, eliminating the manual rerun step during test-driven development. It supports global or local installation, custom watch directories, desktop notifications, and PHPUnit argument passthrough for flexible test filtering.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/spatie/phpunit-watcher

875

GitHub stars

Forks

PHP

Primary language

MIT

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	spatie/phpunit-watcher
Owner	spatie
Primary language	PHP
License	MIT — OSI-approved
Stars	875
Forks	76
Open issues	0
Latest release	1.24.4 (2026-01-05)
Last updated	2026-06-26
Source	https://github.com/spatie/phpunit-watcher

What phpunit-watcher is

A Composer-installable CLI utility that monitors specified directories (src, tests by default) for file modifications and triggers PHPUnit test execution via a configured binary path. Uses Symfony Finder component for file monitoring, supports YAML configuration for watch patterns and PHPUnit arguments, and provides interactive keyboard commands for test control.

Quickstart

Get the phpunit-watcher source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/spatie/phpunit-watcher.git2cd phpunit-watcher3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

Test-Driven Development (TDD) Workflow

Developers writing tests before implementation benefit from immediate feedback on test status as code changes, reducing context switching and accelerating red-green-refactor cycles.

Continuous Validation During Feature Development

Teams working on feature branches can ensure existing tests remain passing as they modify implementation without manually invoking PHPUnit between each change.

Local Development in PHP Monorepos

Projects with multiple source directories can configure watch paths per subdirectory, automatically validating changes across custom directory structures without running the full test suite.

Implementation considerations

Install globally via `composer global require spatie/phpunit-watcher` for project-agnostic use, or locally as `--dev` dependency to keep version control consistent across team members.
Create a `.phpunit-watcher.yml` configuration file in the project root to customize watched directories, file masks, and PHPUnit binary paths; the tool searches parent directories for config inheritance.
On Unix/Linux/macOS, use Composer script helpers with input redirection (`< /dev/tty`) and disabled process timeout to ensure interactive commands work correctly when invoked via `composer run`.
Optimize performance on large repositories by excluding non-essential directories (e.g., vendor, node_modules) and enabling VCS ignore filters (`ignoreVCS: true`) in the YAML config.
Verify PHPUnit binary path matches your project structure; default assumes `vendor/bin/phpunit`, but custom paths (e.g., `./vendor/phpunit/phpunit/phpunit`) may be required.

When to avoid it — and what to weigh

Large Codebases with Slow Test Suites — If test execution takes >30 seconds per run, frequent reruns may create I/O bottlenecks and hinder developer productivity rather than improve it; consider test parallelization or segmentation first.
Windows Development Without TTY Support — Interactive command features (e.g., filtering tests mid-run) are disabled on Windows; users must provide all PHPUnit arguments upfront, limiting real-time test control.
CI/CD or Headless Server Environments — This tool is designed for interactive local development; it is not suitable for automated pipelines, containers, or environments where human keyboard input cannot be provided.
Projects Requiring Strict Process Isolation — If your testing strategy mandates complete test process restart between runs (e.g., for state cleanup), continuous rerun behavior may introduce false positives or state leakage.

License & commercial use

Licensed under the MIT License (MIT). Permits unrestricted commercial and private use, modification, and distribution provided the license notice is retained. Standard OSI-approved permissive license.

MIT license explicitly permits commercial use. No licensing restrictions documented for business deployments. No commercial licensing tier mentioned; free use is clear.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Adequate
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Tool executes PHPUnit binary as configured; ensure the binary path and watched directories are controlled and validated. Security contact ([email protected]) is provided for vulnerability reporting. No specific OWASP-class vulnerabilities or exploitation details documented. File monitoring relies on OS-level file system APIs; no custom encryption or authentication is employed.

Alternatives to consider

Jest (JavaScript/Node.js equivalent)

Offers similar test-watch functionality with interactive commands, snapshots, and better support for monorepos. Mentioned as inspiration in phpunit-watcher credits but targets different ecosystem.

PHPSpec with watch plugins

Behavior-driven development alternative with third-party watch support. Targets specification-first workflows; lighter learning curve for non-TDD teams but smaller ecosystem.

Manual PHPUnit + shell script/Makefile

Zero-dependency approach using `inotifywait` (Linux) or `entr` (macOS) to trigger PHPUnit. More control but requires custom scripting and OS-specific tooling.

Software development agency

Build on phpunit-watcher with DEV.co software developers

Reduce friction in your testing workflow. Install phpunit-watcher today and get instant feedback as you code. MIT-licensed, production-ready, and actively maintained.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

phpunit-snapshot-assertions Watcher phpunit-bridge

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Testing AI Application Development API Development Talk to DEV.co

phpunit-watcher FAQ

Can I run phpunit-watcher in CI/CD pipelines?

No. The tool is designed for interactive local development and requires keyboard input. Use PHPUnit directly or test automation frameworks for pipelines.

How do I exclude vendor or other large directories from being watched?

Add an `exclude` key under `watch:` in `.phpunit-watcher.yml` with directory names (e.g., `exclude: [vendor, node_modules]`). The Symfony Finder component documentation provides additional options.

Does phpunit-watcher support Windows?

Yes, file watching works on Windows. However, interactive keyboard commands are disabled; you must pass all PHPUnit arguments when starting the watcher (e.g., `phpunit-watcher watch --filter=test_name`).

What if my tests take a long time to run?

Consider splitting tests into fast/slow groups and watching only fast tests during development. Use PHPUnit's `--group` or `--exclude-group` arguments passed to phpunit-watcher to reduce rerun time.

Custom software development services

Need help beyond evaluating phpunit-watcher? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source testing integrations — and maintain them long-term.

Accelerate Your PHP Test-Driven Development

Reduce friction in your testing workflow. Install phpunit-watcher today and get instant feedback as you code. MIT-licensed, production-ready, and actively maintained.

Talk to DEV.co Schedule a Consultation