PHPackages                             spatie/phpunit-watcher - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Testing & Quality](/categories/testing)
4. /
5. spatie/phpunit-watcher

ActiveLibrary[Testing & Quality](/categories/testing)

spatie/phpunit-watcher
======================

Automatically rerun PHPUnit tests when source code changes

1.24.4(4mo ago)8839.2M—5.7%7620MITPHPPHP ^8.1CI passing

Since Jul 28Pushed 4mo ago10 watchersCompare

[ Source](https://github.com/spatie/phpunit-watcher)[ Packagist](https://packagist.org/packages/spatie/phpunit-watcher)[ Docs](https://github.com/spatie/phpunit-watcher)[ GitHub Sponsors](https://github.com/spatie)[ RSS](/packages/spatie-phpunit-watcher/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (8)Versions (54)Used By (20)

Automatically rerun PHPUnit tests when source code changes
==========================================================

[](#automatically-rerun-phpunit-tests-when-source-code-changes)

[![Latest Version on Packagist](https://camo.githubusercontent.com/321b874acaeeabbd431c399082e332e53d801a281f8225425c8a92129b0f79e5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7370617469652f706870756e69742d776174636865722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/phpunit-watcher)[![Tests](https://github.com/spatie/phpunit-watcher/workflows/Tests/badge.svg)](https://github.com/spatie/phpunit-watcher/workflows/Tests/badge.svg)[![Total Downloads](https://camo.githubusercontent.com/652fc81022db1f0764559fb258b35b2aaae5288e9f182479d05548a0d48bd618/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7370617469652f706870756e69742d776174636865722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/phpunit-watcher)

Wouldn't it be great if your PHPUnit tests would be automatically rerun whenever you change some code? This package can do exactly that.

With the package installed you can do this:

```
phpunit-watcher watch
```

Here's how it looks like:

[![watcher screenshot](https://camo.githubusercontent.com/923db66d25206b2e35c31fd1d08178e6e5d024e70dbe46bf96401d0411dacc62/68747470733a2f2f7370617469652e6769746875622e696f2f706870756e69742d776174636865722f73637265656e73686f74732f776174636865722e6a7067)](https://camo.githubusercontent.com/923db66d25206b2e35c31fd1d08178e6e5d024e70dbe46bf96401d0411dacc62/68747470733a2f2f7370617469652e6769746875622e696f2f706870756e69742d776174636865722f73637265656e73686f74732f776174636865722e6a7067)

This will run the tests and rerun them whenever a file in the `app`, `src` or `tests` directory is modified.

Want to pass some arguments to PHPUnit? No problem, just tack them on:

```
phpunit-watcher watch --filter=it_can_run_a_single_test
```

In his excellent talk at Laracon EU 2017 [Amo Chohan](https://github.com/amochohan) shows our phpunit-watcher in action.

[![Amo Chohan demo](https://camo.githubusercontent.com/a6934b2434394f655e4c266e3b799e463b779c9b9486dc1f1dcf22dca0c7fb91/68747470733a2f2f7370617469652e6769746875622e696f2f706870756e69742d776174636865722f766964656f7468756d622e706e67)](https://youtu.be/CF1UhUj9LG0?t=26m13s)

Support us
----------

[](#support-us)

[![](https://camo.githubusercontent.com/b59313ceb574a881f9f7292c29359ba3624aa9520e092cd1210e4e8f8aa49ec8/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f706870756e69742d776174636865722e6a70673f743d31)](https://spatie.be/github-ad-click/phpunit-watcher)

We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).

We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).

Installation
------------

[](#installation)

You can install this package globally like this

```
composer global require spatie/phpunit-watcher
```

After that `phpunit-watcher watch` can be run in any directory on your system.

Alternatively you can install the package locally as a dev dependency in your project

```
composer require spatie/phpunit-watcher --dev
```

Locally installed you can run it with `vendor/bin/phpunit-watcher watch`

Usage
-----

[](#usage)

All the examples assume you've installed the package globally. If you opted for the local installation prepend `vendor/bin/` everywhere where `phpunit-watcher` is mentioned.

You can start the watcher with:

```
phpunit-watcher watch
```

This will run the tests and rerun them whenever a file in the `src` or `tests` directory is modified.

Want to pass some arguments to PHPUnit? No problem, just tack them on:

```
phpunit-watcher watch --filter=it_can_run_a_single_test
```

#### Notes on interactive commands

[](#notes-on-interactive-commands)

When running `phpunit-watcher` from a Composer script, you may need to [redirect input](https://github.com/spatie/phpunit-watcher/issues/54) in order for the interactive commands to work and [disabled the default timeout](https://getcomposer.org/doc/06-config.md#process-timeout):

```
{
    "scripts": {
        "test:watch": [
            "Composer\\Config::disableProcessTimeout",
            "phpunit-watcher watch < /dev/tty"
        ]
    }
}
```

On Windows, Currently, TTY is not being supported, so any interaction has been disabled. While watching for changes works, any arguments for PHPUnit have to be provided when initially calling `phpunit-watcher`.

Customization
-------------

[](#customization)

Certain aspects of the behaviour of the tool can be modified. The file for options may be named `.phpunit-watcher.yml`, `phpunit-watcher.yml` or `phpunit-watcher.yml.dist`. The tool will look for a file in that order.

If a config file does not exist in the project directory, the tool will check if a file exists in any of the parent directories of the project directory.

Here's some example content. Read on for a more detailed explanation of all the options.

```
watch:
  directories:
    - src
    - tests
  fileMask: '*.php'
notifications:
  passingTests: false
  failingTests: false
phpunit:
  binaryPath: vendor/bin/phpunit
  arguments: '--stop-on-failure'
  timeout: 180
```

### Customize watched directories and files

[](#customize-watched-directories-and-files)

You can customize the directories being watched by creating a file named `.phpunit-watcher.yml` in your project directory. Here's some example content:

```
watch:
  directories:
    - src
    - tests
  exclude:
    - lib
  fileMask: '*.php'
  ignoreDotFiles: true
  ignoreVCS: true
  ignoreVCSIgnored: false
```

See [the documentation for Finder](https://symfony.com/doc/current/components/finder.html) for more details.

If you experience performance delays with large repositories, try adding `exclude` entries for any large subdirectories that you don't need to watch. Enabling the `ignore...` options can also be helpful. It's also important to ensure you're also using the `'*.php'` file mask.

### Desktop notifications

[](#desktop-notifications)

By default the tool will display desktop notifications whenever the tests pass or fail. If you want to disable certain desktop notifications update `.phpunit-watcher.yml` by adding a `notifications` key.

```
notifications:
  passingTests: false
  failingTests: false
```

### Help messages

[](#help-messages)

By default the tool will display a helper for keyboard actions after each run. You can hide these help messages by adding a `hideManual` key in the `.phpunit-watcher.yml`.

```
hideManual: true
```

### Customize PHPUnit

[](#customize-phpunit)

#### Binary

[](#binary)

By default the tool use `vendor/bin/phpunit` as default PHPUnit binary file, however, it may be useful to be able to customize this value for people who have a binary file in a different location.

You can specificy it in the `.phpunit-watcher.yml` config file. Here's an example:

```
phpunit:
  binaryPath: ./vendor/phpunit/phpunit/phpunit
```

#### Initial arguments

[](#initial-arguments)

If you want to use pass the same arguments to PHPUnit everytime to watcher starts, you can specificy those in the `.phpunit-watcher.yml` config file. Here's an example:

```
phpunit:
  arguments: '--stop-on-failure'
```

When starting the tool with some arguments (eg `phpunit-watcher watch --filter=my_favourite_test`) those arguments will get used instead of the ones specified in the config file.

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.

Testing
-------

[](#testing)

```
composer test
```

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details.

Security
--------

[](#security)

If you've found a bug regarding security please mail  instead of using the issue tracker.

Postcardware
------------

[](#postcardware)

You're free to use this package (it's [MIT-licensed](LICENSE.md)), but if you use it often we highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using.

Our address is: Spatie, Kruikstraat 22, 2018 Antwerp, Belgium.

We publish all received postcards [on our company website](https://spatie.be/en/opensource/postcards).

Credits
-------

[](#credits)

- [Freek Van der Herten](https://github.com/freekmurze)
- [All Contributors](../../contributors)

We started creating this package after reading [this excellent article](https://www.sitepoint.com/write-javascript-style-test-watchers-php/) by [Christoper Pitt](https://twitter.com/assertchris)

Interactive commands were inspired by [Jest](https://facebook.github.io/jest/).

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

72

—

ExcellentBetter than 100% of packages

Maintenance75

Regular maintenance activity

Popularity68

Solid adoption and visibility

Community52

Growing community involvement

Maturity85

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 66.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~60 days

Recently: every ~148 days

Total

52

Last Release

134d ago

Major Versions

0.0.2 → 1.0.02017-07-31

PHP version history (6 changes)0.0.1PHP ^7.0

1.10.0PHP ^7.1

1.11.0PHP ^7.2

1.23.1PHP ^7.2 | ^8.0

1.23.5PHP ^7.2 | ^8.0 | ^8.1

1.24.0PHP ^8.1

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/7535935?v=4)[Spatie](/maintainers/spatie)[@spatie](https://github.com/spatie)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (137 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (8 commits)")[![Nielsvanpach](https://avatars.githubusercontent.com/u/10651054?v=4)](https://github.com/Nielsvanpach "Nielsvanpach (7 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (7 commits)")[![iandunn](https://avatars.githubusercontent.com/u/484068?v=4)](https://github.com/iandunn "iandunn (4 commits)")[![romainnorberg](https://avatars.githubusercontent.com/u/7681951?v=4)](https://github.com/romainnorberg "romainnorberg (4 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (3 commits)")[![casperboone](https://avatars.githubusercontent.com/u/15815208?v=4)](https://github.com/casperboone "casperboone (3 commits)")[![KentarouTakeda](https://avatars.githubusercontent.com/u/4785040?v=4)](https://github.com/KentarouTakeda "KentarouTakeda (3 commits)")[![AlexVanderbist](https://avatars.githubusercontent.com/u/6287961?v=4)](https://github.com/AlexVanderbist "AlexVanderbist (2 commits)")[![ntwb](https://avatars.githubusercontent.com/u/1016458?v=4)](https://github.com/ntwb "ntwb (2 commits)")[![obstschale](https://avatars.githubusercontent.com/u/1058710?v=4)](https://github.com/obstschale "obstschale (2 commits)")[![rubenvanassche](https://avatars.githubusercontent.com/u/619804?v=4)](https://github.com/rubenvanassche "rubenvanassche (2 commits)")[![sibprogrammer](https://avatars.githubusercontent.com/u/187856?v=4)](https://github.com/sibprogrammer "sibprogrammer (2 commits)")[![akoepcke](https://avatars.githubusercontent.com/u/5311185?v=4)](https://github.com/akoepcke "akoepcke (2 commits)")[![lucassabreu](https://avatars.githubusercontent.com/u/3457213?v=4)](https://github.com/lucassabreu "lucassabreu (2 commits)")[![MaxGiting](https://avatars.githubusercontent.com/u/9828591?v=4)](https://github.com/MaxGiting "MaxGiting (2 commits)")[![mikeerickson](https://avatars.githubusercontent.com/u/183153?v=4)](https://github.com/mikeerickson "mikeerickson (2 commits)")[![zedentox](https://avatars.githubusercontent.com/u/3627991?v=4)](https://github.com/zedentox "zedentox (1 commits)")[![bencarrr](https://avatars.githubusercontent.com/u/8208631?v=4)](https://github.com/bencarrr "bencarrr (1 commits)")

---

Tags

phpunittestingwatcherspatiephpunit-watcher

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/spatie-phpunit-watcher/health.svg)

```
[![Health](https://phpackages.com/badges/spatie-phpunit-watcher/health.svg)](https://phpackages.com/packages/spatie-phpunit-watcher)
```

###  Alternatives

[infection/infection

Infection is a Mutation Testing framework for PHP. The mutation adequacy score can be used to measure the effectiveness of a test set in terms of its ability to detect faults.

2.2k26.2M1.8k](/packages/infection-infection)[phpbench/phpbench

PHP Benchmarking Framework

2.0k13.0M627](/packages/phpbench-phpbench)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

19562.3M1.3k](/packages/drupal-core)[sulu/sulu

Core framework that implements the functionality of the Sulu content management system

1.3k1.3M152](/packages/sulu-sulu)[magento/magento2-functional-testing-framework

Magento2 Functional Testing Framework

15511.5M30](/packages/magento-magento2-functional-testing-framework)[prestashop/prestashop

PrestaShop is an Open Source e-commerce platform, committed to providing the best shopping cart experience for both merchants and customers.

9.0k15.4k](/packages/prestashop-prestashop)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)