PHPackages                             t73biz/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. t73biz/phpunit-watcher

ActiveLibrary

t73biz/phpunit-watcher
======================

Automatically rerun PHPUnit tests when source code changes

1.0.1(2y ago)05MITPHPPHP ^7.2 | ^8.0 | ^8.1

Since Jun 30Pushed 2y agoCompare

[ Source](https://github.com/t73biz/phpunit-watcher)[ Packagist](https://packagist.org/packages/t73biz/phpunit-watcher)[ Docs](https://github.com/rongchaplin/phpunit-watcher)[ RSS](/packages/t73biz-phpunit-watcher/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (7)Versions (3)Used By (0)

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

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

[![Latest Version on Packagist](https://camo.githubusercontent.com/77f4bff7fbb074e7ea31b059cd9230cd633ae9d960d3f5be8e380d0258d256e9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f74373362697a2f706870756e69742d776174636865722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/spatie/phpunit-watcher)[![Tests](https://github.com/rongchaplin/phpunit-watcher/workflows/Tests/badge.svg)](https://github.com/rongchaplin/phpunit-watcher/workflows/Tests/badge.svg)[![Total Downloads](https://camo.githubusercontent.com/a9e1650941ff321d46d5e60d37e451085782adb7ad9f60d35d7458f76c27530b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f74373362697a2f706870756e69742d776174636865722e7376673f7374796c653d666c61742d737175617265)](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)

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

[](#installation)

You can install this package globally like this

```
composer global require t73biz/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 t73biz/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 specify 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/t73biz/.github/blob/main/CONTRIBUTING.md) for details.

Credits
-------

[](#credits)

- [Freek Van der Herten](https://github.com/freekmurze)
- [Ron Chaplin](https://github.com/t73biz)
- [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

25

—

LowBetter than 37% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity4

Limited adoption so far

Community19

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 71.3% 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 ~0 days

Total

2

Last Release

1045d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/e0acd8279d47a96b9ba7a8463ba5ef0b9dbbfd6e14b4d3a2c02ccc7f08bf0ba2?d=identicon)[t73biz](/maintainers/t73biz)

---

Top Contributors

[![freekmurze](https://avatars.githubusercontent.com/u/483853?v=4)](https://github.com/freekmurze "freekmurze (129 commits)")[![AdrianMrn](https://avatars.githubusercontent.com/u/12762044?v=4)](https://github.com/AdrianMrn "AdrianMrn (8 commits)")[![romainnorberg](https://avatars.githubusercontent.com/u/7681951?v=4)](https://github.com/romainnorberg "romainnorberg (4 commits)")[![iandunn](https://avatars.githubusercontent.com/u/484068?v=4)](https://github.com/iandunn "iandunn (4 commits)")[![casperboone](https://avatars.githubusercontent.com/u/15815208?v=4)](https://github.com/casperboone "casperboone (3 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)")[![obstschale](https://avatars.githubusercontent.com/u/1058710?v=4)](https://github.com/obstschale "obstschale (2 commits)")[![ntwb](https://avatars.githubusercontent.com/u/1016458?v=4)](https://github.com/ntwb "ntwb (2 commits)")[![akoepcke](https://avatars.githubusercontent.com/u/5311185?v=4)](https://github.com/akoepcke "akoepcke (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)")[![lucassabreu](https://avatars.githubusercontent.com/u/3457213?v=4)](https://github.com/lucassabreu "lucassabreu (2 commits)")[![thiagolcks](https://avatars.githubusercontent.com/u/1413859?v=4)](https://github.com/thiagolcks "thiagolcks (1 commits)")[![traubisoda](https://avatars.githubusercontent.com/u/1913152?v=4)](https://github.com/traubisoda "traubisoda (1 commits)")[![yjv-XCV](https://avatars.githubusercontent.com/u/28530308?v=4)](https://github.com/yjv-XCV "yjv-XCV (1 commits)")[![adalessa](https://avatars.githubusercontent.com/u/7914601?v=4)](https://github.com/adalessa "adalessa (1 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)")[![binaryk](https://avatars.githubusercontent.com/u/6833714?v=4)](https://github.com/binaryk "binaryk (1 commits)")

---

Tags

spatiephpunit-watcher

###  Code Quality

TestsPHPUnit

### Embed Badge

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

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

###  Alternatives

[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.4k5.6M648](/packages/sylius-sylius)[spatie/phpunit-watcher

Automatically rerun PHPUnit tests when source code changes

8839.2M475](/packages/spatie-phpunit-watcher)[shopware/platform

The Shopware e-commerce core

3.3k1.5M3](/packages/shopware-platform)[drupal/core

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

19462.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)[tightenco/jigsaw

Simple static sites with Laravel's Blade.

2.2k438.5k29](/packages/tightenco-jigsaw)

PHPackages © 2026

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