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.

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:

Automating Grunt Builds in PhpStorm

I’ve started using PhpStorm for doing PHP development. So far, it’s been great. I find that I need to have significantly fewer programs and windows open, and that it automates a lot of the tasks I was doing manually.

Today, I puzzled out how to have PhpStorm invoke Grunt instead of running grunt watch in a terminal window:

  1. Navigate to Project Settings > File Watchers.
  2. Click + > Custom.
  3. Name: Grunt.
  4. Show console: Always.
  5. Deselect Immediate File Synchronization.
  6. File type: Any.
  7. Scope: Click button.
    1. Click + and add a new scope – name it Grunt Watch, click OK.
    2. Expand this window.
    3. With your scope selected, browse in the file tree and select directories that Grunt would be watching and click Include Recursively.
    4. Select files that Grunt is outputting (such as minified CSS and JS files) that you included in the previous step and click Exclude (this prevents the resulting output file from endlessly re-triggering Grunt execution).
    5. Click OK.
  8. Program: (browse to grunt executable path).
  9. Working Directory: (browse to the directory that contains the Grunt file).
  10. Click OK to create the File Watcher.
  11. Click OK to exit the Preferences dialog.