web content accessibility at yoast

Unit testing WordPress plugins with PHPUnit in PhpStorm

Unit testing WordPress plugins with PHPUnit in PhpStorm

February 23rd, 2016 – 1 Comment

A nice way to optimize your test flow is by having PhpStorm run your unit tests for you. It can be quite some work to set this up for WordPress plugins, since they depend so heavily on WordPress. In this post, I’ll go over all the steps you’ll have to take to do this.

1) Install PHPUnit

To start unit testing your code you first have to install PHPUnit.

There are basically 3 ways to do this:

  • Download the .phar file from the phpunit.de website
  • Install via composer in the composer.json file
{ 
  "require-dev": {
    "phpunit/phpunit": "5.0.*"
  }
} 
  • Install via homebrew, when you’re using mac OSX: brew install phpunit

More elaborate installation instructions can be found on the website of PHPUnit.

In my situation and examples I’ll use PHPUnit installed with homebrew.

2) Set up tests for WordPress plugins

There are a few things you need, to write Unit Tests for WordPress plugins.

WP develop

As we’re developing a WordPress plugin, the code will be coupled to WordPress. This is not ideal for unit testing, but since WordPress has lots of global state and functions, it’s virtually impossible (or at least quite impractical) to isolate the plugin code from it. This also means we want to run our unit tests on top of WP develop. A guideline on how to setup WP develop unit tests can be found on the WordPress website.

bootstrap.php

To run PHPUnit you need to first bootstrap your environment. Since WordPress is part of our environment, we’ll also require the WP develop bootstrap.php (you can find this in the wp-develop directory). We’ll put the bootstrap.php file in a tests directory in the project root.

// disable xdebug backtrace
if ( function_exists( 'xdebug_disable' ) ) {
  xdebug_disable();
}

if ( false !== getenv( 'WP_PLUGIN_DIR' ) ) {
  define( 'WP_PLUGIN_DIR', getenv( 'WP_PLUGIN_DIR' ) );
}

if ( false !== getenv( 'WP_DEVELOP_DIR' ) ) {
  require getenv( 'WP_DEVELOP_DIR' ) . 'tests/phpunit/includes/bootstrap.php';
}

phpunit.xml

This is the configuration file where you tell PHPUnit in which directory the tests and the bootstrap.php are.

<phpunit bootstrap="tests/bootstrap.php">
  <testsuites>
    <testsuite>
      <directory prefix="test-" suffix=".php">./tests/</directory>
    </testsuite>
  </testsuites>
</phpunit>

In our situation the bootstrap file can be found under the /tests directory. The target directory where PHPUnit will look for the file will be /tests as well. According to convention, all the test files have to begin with test- and should end with .php (the extension) in order to be picked up by PHPUnit.

phpunit-filestructure

We should end up in a file structure like this.

3) Configure PhpStorm

The first thing we need to do is make sure if we’ve configured an interpreter under Preferences > Languages & Frameworks > PHP.

Don’t forget to add <code>wp-develop</code> and phpunit to your include path for some autocompletion niceness.

Choose a PHP interpreter (1) or select a PHP interpreter in your filesystem (2). Then add wp-develop and the PHPUnit framework (3) to have some autocompletion niceness.

Next we need to tell PHPStorm where it can find PHPUnit. You can do this under Preferences > Languages > PHP > PHPUnit.

Choose for the option ‘Path to phpunit.phar’ and make sure it points to the phar file you have downloaded before.

Fill in the path to phpunit.phar

We can now start configuring a testrunner. You can do this under under Run > Edit Configurations… where you’ll get a screen like this:

phpunit-setup-debug-configuration

You can configure PHPUnit in four steps.

There are four steps to take:

  1. Give the configuration a name, for example: PHP Unit.
  2. Check the option ‘defined in the configuration file’.
  3. Check ‘use alternative configuration file’ and set the path to the phpunit.xml file.
  4. Set environment variables, you can do this by clicking the ‘…’ after the input field. You’ll get the next screen:
phpunit-environment-variables

Add WP_DEVELOP_DIR as an environment variable.

You have to enter ‘WP_DEVELOP_DIR’ as name and the path to the wp-develop directory we’ve cloned before. We use the WP_DEVELOP_DIR environment variable in our bootstrap.php to require the WordPress unit test bootstrap.php.

Run tests

For this article we write an example test to show how PHPUnit works. The tests have to be put in the /tests folder.

Our example class will look something like:

class Foo_Test extends WP_UnitTestCase {

  public function test_foo_is_foo() {
    $this->assertTrue( 'foo' === 'foo' );
  }
}

We extend the WP_UnitTestCase because we are in a WordPress context. If this is not the case you can use PHPUnit_Framework_TestCase instead.

You can run the test by pressing the play icon in the run toolbar or under >Run> Run ‘PHP Unit’. PhpStorm will now open a small window in which it will run your tests:

phpunit-run-test

PhpStorm will show you a window like this when it runs tests.

Congratulations. You’ve setup PhpStorm to run your unit tests.


1 Response to Unit testing WordPress plugins with PHPUnit in PhpStorm

  1. Balak32
    By Balak32 on 3 March, 2016

    Informative article. Added into my favourites.


Check out our must read articles about Analytics