Unit testing WordPress plugins with PHPUnit in PhpStorm

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

[code lang=”javascript”]
{
"require-dev": {
"phpunit/phpunit": "5.0.*"
}
}
[/code]

• 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.

[code lang=”php”]
// 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’;
}
[/code]

phpunit.xml

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

[code lang=”html”]
<phpunit bootstrap="tests/bootstrap.php">
<testsuites>
<testsuite>
<directory prefix="test-" suffix=".php">./tests/</directory>
</testsuite>
</testsuites>
</phpunit>
[/code]

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.

3) Configure PhpStorm

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

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

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

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:

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:

[code lang=”php”]
class Foo_Test extends WP_UnitTestCase {

public function test_foo_is_foo() {
$this->assertTrue( ‘foo’ === ‘foo’ );
}
}
[/code]

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:

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