Running WordPress PHPUnit Tests in PhpStorm

I use a virtual machine for doing local development (using Vagrant) and PhpStorm as my IDE. I write unit tests in PHPUnit and want to be able to run those tests after making changes to code. The problem is that the tests need to be run in the virtual machine, so setup isn’t as straightforward as just pointing PhpStorm to my test configuration. It’s not terribly difficult though, and the rewards are well worth it.

1. Add a Remote CLI Interpreter

In order for the command-line PHPUnit process to run inside of your Vagrant box and send results to PhpStorm, you have to give PhpStorm some information on how to connect to the Vagrant box to run commands.

  1. Ensure your Vagrant box is running.
  2. Go to Preferences > Languages & Frameworks > PHP.
  3. Click the three dots next to CLI Interpreter to add a new remote interpreter.
  4. Click the plus icon to add a new CLI interpreter.
  5. Set the name to whatever you want. I usually do not check the box for Visible only for this project because I use the same interpreter across multiple projects housed on the same Vagrant box.
  6. Under the Remote section, select Vagrant.
  7. Set the Vagrant Instance Folder to the directory that contains your Vagrantfile.
  8. Set the Vagrant Host URL to ssh://vagrant@127.0.0.1:2222.
  9. Map the PHP executable to the path of the php executable on the Vagrant box. In my case, this was /usr/bin/php.
  10. Click OK and PhpStorm should validate your settings for you.

2. Add a Run/Debug Configuration for PHPUnit

In order to run PHPUnit tests with a click of a button in PhpStorm, you have to give PhpStorm some information about what you want to run and where you want to run it. This is accomplished by creating a run/debug configuration, which can be done through the Run > Edit Configurations menu item.

  1. Click the plus icon to add a new configuration and select PHPUnit as the type.
  2. Give the configuration a name. I usually name mine Unit Tests or some such.
  3. Set the Test scope to Defined in the configuration file.
  4. Check the box for Use alternative configuration file and point it at the phpunit.xml file in your project directory.
  5. Click the three dots next to Environment Variables. If there are any environment variables defined in your bash profile in Vagrant, they won’t be available as part of the run configuration, unless you specify them here. On my system, I needed to set the following:
    WP_CORE_DIR=/var/www/wordpress-develop/src/
    WP_TESTS_DIR=/var/www/wordpress-develop/tests/phpunit/
  6. Click Apply and then close the window.
  7. In the top right, you should now be able to select your unit tests configuration from the dropdown in the debug area, then click the play icon to start the test suite.

3. Running Specific Tests

I will often iterate heavily on a single test, and I don’t want to run the entire test suite every time I make a modification to one test, so I create targeted test configurations to only affect a particular set of tests. To do this:

  1. Go to Run > Edit Configurations.
  2. Select your main unit test configuration and click the copy button.
  3. Update the name of the configuration to include the file you want to test.
  4. Change the Test scope to Class.
  5. Select the File that contains the class you want to test.
  6. Select the Class in the file that you want to test.
  7. Click OK.
  8. You should now be able to select the new configuration from the debug drop down and click the play icon to run just that test.