Running WordPress PHPUnit Tests in PhpStorm

Update 2019-01-02: Added details on configuring the include_path to point to PHPUnit.

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@
  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. You may need to add PHPUnit explicitly to the include_path. In my case, I needed to click on the folder next to Configuration Options, add a configuration directive for include_path, and set the value to .:/usr/local/lib/php:/usr/local/src/composer/vendor/phpunit/phpunit.
  11. 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:
  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.

Bringing Back the Blog

May was a big month for changes. Kelsey and I celebrated our eighth wedding anniversary, I graduated with a PhD in Science and Technology Studies from Rensselaer Polytechnic Institute (RPI), I left my job at Fingerpaint, where I had been working for over four years, and I started a new job as a Principal Software Developer with Alley Interactive, working remotely.

Being done with PhD studies and eliminating my commute has left me with a bit more time in my schedule, so I figured I would try to start blogging on a semi-regular basis. We’ll see how it goes!

WordPress: Maintaining Active Nav Status with Custom Post Types

Scenario: You have a custom post type archive page, and you want to be able to add some custom content to the archive without hardcoding it in the template. This is easy enough – you can create a page with the same name and slug, and set your templates to pull in the data from the page on the archive listing page by performing a query based on the post type slug.

However, it introduces a problem with the active state on the WordPress nav. You can create a custom nav item to point to the slug of the archive for your post type, but WP will see the nav item as referencing a page, even though you specified the item as custom.

In order to fix this behavior, you will need to filter the wp_get_nav_menu_items function to tell WP that the nav item is custom if it references a post type, which will force WP to match based on the URL and restore the active state to the nav: