Running PHPUnit tests with VVV and PhpStorm

PhpStorm has excellent out of the box support for running unit tests using the PHPUnit testing framework. It also provides you with great code coverage statistics of your unit tests. The challenge however is getting it setup properly and actually running your WordPress unit tests.

On my local development environment, I specifically use VVV and ideally I wanted PhpStorm to run the tests from within the VVV virtual machine. Since PHP and PHPUnit are bundled with VVV, it makes sense to have PhpStorm utilise those libraries inside the virtual machine than for me to have to install the libraries independently on my Mac. I love having clear separation between my computer and development environments.

There is a downside to running your tests from inside a VVV virtual machine and that is that it can be a bit slower. This is because there is extra overhead involved with the communication over a SSH connection between your host machine and the guest/virtual machine. The virtual machine also does not have the same computing power as your host machine. The good news is that I’ve found that even though there is a slight reduction in speed, it’s fast enough that it’s not of concern to me.

Initially when I started setting up my unit tests to run inside the VVV virtual machine from PhpStorm, I ran into numerous issues. Being a really big PhpStorm fanboy and knowing that it is possible to get working in the way that I wanted it to work, I decided to persevere and eventually figured out the correct configurations to get it working.

The rest of this article is going to go through the steps that I followed to get it working so that you too can get it working on your local development environment.

The first step is to make sure that you have a VVV environment setup and have installed PhpStorm.

Setup the PHP interpreter

Once you’ve got VVV and PhpStorm up an running, we need to add a PHP Interpreter. Interpreters in PhpStorm enable PHP support within the IDE. You can have multiple interpreters setup, a good example for multiple interpreters would be different interpreters for different versions of PHP. The other thing about interpreters is they can either be local or remote. You cannot select multiple interpreters for a project.

In this article we’re going to use a remote interpreter since we’re running the tests inside the virtual machine using it’s PHP and PHPUnit installations. This is important because VVV installs PHPUnit using Composer and we need to tell PhpStorm where it is loaded from. We do this by defining the location of the Composer autoloader script in the PhpStorm/PHPUnit settings.

So on the menu bar, go to Preferences. then click Languages and Frameworks and lastly PHP. From there you will see the drop down select for Interpreter. Click the ellipses (…) and you will presented with a new dialog which lets you add/edit your existing interpreters.

Click the + button to add a new one and fill out details accordingly. Here is a screenshot of what my local VVV interpreter set up looks like.

Configure PHPUnit settings

Great, we have our interpreter but PhpStorm still doesn’t know where PHPUnit is installed or what interpreter to use when running tests. To set this up, we need to configure the PHPUnit settings in PhpStorm. Open Preferences, navigate to Languages & Frameworks, then PHP, and lastly PHPUnit. This is a per project based settings dialog.

So for the current project you’ve got open, click the little + icon in the PHPUnit settings to add a new configuration (there will already be a local configuration setup which you can ignore). Now select By Remote Interpreter.

From the new dialog that has now opened, select the remote Vagrant interpreter that you just added. And now we’re going to set up the most important piece of this tutorial. The following configuration took me a very long time to figure out and without it, your tests will not run inside PhpStorm.

We need to tell PhpStorm where to load PHPUnit from. You have 3 options, and for getting your tests to run inside VVV, the only option you need to pay attention to is Use custom autoloader. As mentioned above, VVV installs PHPUnit on the virtual machine using Composer. It is not available in the PHP include path and we don’t want to use the PHAR package.

So, all you need to do here is specify the path to the Composer autoloader. In VVV that path is:

/usr/local/src/composer/vendor/autoload.php

That’s all you need to set up in the PHPUnit settings. Here is a screenshot of my PHPUnit settings.

Create PHPUnit test runner configuration

We’re almost there now! The last step before running our tests is to set up a test runner configuration. All this configuration does is let PhpStorm know where the PHPUnit configuration file is or which directory to use so that it knows what tests to run.

On your toolbar, you should have a subsection for running and debugging. It looks like this (if you have not configured any configurations)

Click on Edit Configurations. Then, click the little + icon to add a new configuration. From there you need to select PHPUnit (not PHPUnit by HTTP).

You have numerous options here as to how you want the tests to run. Since I always use WP-Dev-Lib, my projects include a phpunit.xml file and a bootstrapped for the tests. That means I always choose to run my tests from a configuration file. Here is what one of my test runners looks like…

Note: For WP-Dev-Lib if you have not setup a WP_TESTS_DIR environment variable, you will need to specify it in the configuration as I have done above for your tests to run.

Run tests and check coverage

And that’s it! We can now run our tests and check the code coverage. To run your tests, from the Run menu on your toolbar, select your configuration and hit the little green play icon. Your tests will run inside PhpStorm and look like this:

Then lastly, to check code coverage, there is an addition icon that looks like this 

Select your configuration, click that icon and it will run code coverage stats on your code base. Here is what the code coverage window will look like:

And there you have it, PHPUnit tests running inside PhpStorm using VVV. Hope you found this article useful and got it up and running without any issues.