A tool to automatically rerun PHPUnit tests when source code changes

In the JavaScript world Jest, built by Facebook, is an excellent tool to run tests. Not only can it automatically rerun your tests when source code changes, but there’s also an interactive mode where you can set a filter on which tests to run while the tool is running. Would it be great if we could have these awesome features while working with PHPUnit?

Our newly released phpunit-watcher tool provides a Jest like experience. You can simply install it by running composer global require spatie/phpunit-watcher.

When you start it with phpunit-watcher watch this is what it looks like.

By default it will watch all files in the src, app and tests subdirectories in the directory where it is started. If any of the files in those directories changes (or when a file in there gets created or deleted) the tests will rerun automatically. Cool, right? If you need to watch another directory just add a file named .phpunit-watcher.yml in your project directory. Here's some example content:

watch:
directories:
- myApplication
- tests
fileMask: '*.php'

Extra options can be passed to PHPUnit just by tacking them on the the phpunit-watcher command. Here’s an example where we only run tests whose name contains the word “includes”:

Now, if you want to get rid of that filter, there’s no need to stop the tool. Like the little manual at the bottom will tell you, just press “a” to run all tests again. If you only want to run tests in a specific file or path, just type “p” to get to this screen:

On that screen, just type the name of the file or directory that you want to filter on.

And that’s all there’s really to it. The tool is fairly new, but the past days I’ve really enjoyed using our own tool myself and I wonder how I could ever have worked without it. Now I know that some IDE’s, such as PHPStorm, ship with a PHPUnit watcher built in, but our tool feels nicer (that’s very subjective of course) and will work in combination with any editor or IDE (that’s very objective).

Some cool packages are powering our tool. The watching part is covered by the awesome Resource-watcher package. The interactivity is enabled by ReactPHP. I also want to give a shoutout to Colin O’Dell who helped fix a nasty performance problem and Christoper Pitt who wrote a nice blogpost that kickstarted the work on this package.

If you want to know more about phpunit-watcher, be sure to check it out on GitHub. This is not the first time we’ve created something inspired by Jest. Take a look at this package which brings Jest’s snapshot testing to PHPUnit. Want to see some mooarrrr packages we created previously, then check out the opensource pages on our company website.