Creating a PHPUnit framework for WordPress plugins

WordPress is a great platform, we use it to streamline workflow and keep costs down. Here is a little tutorial on how to setup PHPUnit testing for WordPress plugin development. Setting up the framework can be a nuisance and I’ve found no real guide that I find applicable to my style of coding so I thought I’d stray from the usual data recovery articles and create one.

PHPUnit allows you to create automated programmable tests to check your code for bugs. It’s great when you’ve spent the entire night ripping apart a function and want to make sure it hasn’t broken a feature you wrote weeks ago.

Much of this article has been derived from the following articles and stitched in place

Download and Install the latest release of XAMPP and Subversion for Windows with the default options. Download PHPUnit 6 here (at the time of writing PHPUnit 7.0 isn’t supported by WordPress) and WP-CLI and save it in c:\xampp\php

Rename PHPUnit to phpunit.phar and wp-cli.phar to wp.phar
Next we need to do a few fixups so PHPUnit and WP-CLI will run under windows. XAMPP includes version 3 of PHPUnit which we’re going to rename.

Open up a command prompt and type the following

cd\xampp\php
ren phpunit.bat phpunit.bat.orginal
ren phpunit phpunit.orginal
echo @php "%~dp0phpunit.phar" %* > phpunit.cmd
echo @php "%~dp0wp.phar" %* > wp.cmd

Now we should have a functional copy of PHPUnit and WP-CLI, lets test

C:\xampp\php>
phpunit --version
PHPUnit 6.5.8 by Sebastian Bergmann and contributors.

C:\xampp\php>
wp --version
WP-CLI 1.5.1

The WordPress docs explain how to download the latest nightly alpha build but not the latest stable build. That’s where I diverge; I want to test against a stable build.

Next, we need to know the latest stable version of WordPress if you’re unsure visit https://develop.svn.wordpress.org/tags/ and scroll toward the bottom. As of writing its 4.9.6, so we’re going to check that version out with SVN. Go into your root project directory where you plan to store your framework (c:\xampp\htdocs in my case) and create a project called wp_framework by running the following.

cd\xampp\htdocs
svn co https://develop.svn.wordpress.org/tags/4.9.6 wp_framework

Create a WordPress database using your favorite method, here’s mine from the WordPress Installation Guide

mysql -u root -p
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 5340 to server version: 3.23.54
 
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 
mysql> CREATE DATABASE wp_framework_db;
Query OK, 1 row affected (0.00 sec)
 
mysql> GRANT ALL PRIVILEGES ON wp_framework_db.* TO "wp_framework_user"@"localhost"
  -> IDENTIFIED BY "wp_framework_password";
Query OK, 0 rows affected (0.00 sec)
  
mysql> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.01 sec)

mysql> EXIT
Bye
$

Open wp-tests-config-sample.php in the project framework directory and modify the define fields below with the information from the database you created above then save it as wp-tests-config.php. Similar to how you set up a standard WordPress site.

define( 'DB_NAME', 'wp_framework_db' );
define( 'DB_USER', 'wp_framework_user' );
define( 'DB_PASSWORD', 'wp_framework_password' );

Next lets test that PHPUnit is working, in the project directory run PHPUnit, you should see the following:

C:\xampp\htdocs\wp_framework>
phpunit
Installing...
Running as single site... To run multisite, use -c tests/phpunit/multisite.xml
Not running ajax tests. To execute these, use --group ajax.
Not running ms-files tests. To execute these, use --group ms-files.
Not running external-http tests. To execute these, use --group external-http.
PHPUnit 6.5.8 by Sebastian Bergmann and contributors.

.............................................................   61 / 8504 (  0%)
.............................................................  122 / 8504 (  1%)
.............................................................  183 / 8504 (  2%)
.............................................................  244 / 8504 (  2%)

We’re going to use WP-CLI to create a skeleton plugin for us. For our plugin to run properly we need to create a config file for the site. In the project framework directory run

C:\xampp\htdocs\wp_framework>
wp config create --dbname=wp_framework_db --dbuser=wp_framework_user --dbpass=wp_framework_password
Success: Generated 'wp-config.php' file.

Next, let’s say our plugin name is called DiscoPop, we need to create a plugin slug. This creates plugin scaffold with PHPUnit tests.

C:\xampp\htdocs\wp_framework>
wp scaffold plugin discopop

Almost done, but not quite. The scaffold code needs to be modified. If we try to run PHPUnit it will throw an error.

cd C:\xampp\htdocs\wp_framework\src\wp-content\plugins\discopop
phpunit
Could not find ...\AppData\Local\Temp/wordpress-tests-lib/includes/functions.php, have you run bin/install-wp-tests.sh ?

On a Linux system, your supposed to run a simple initialization script called install-wp-tests.sh located in the bin folder of the plugin slug however since we’re on a Windows system that script won’t run properly. Luckily we did everything in Step 2 except modify one variable.

Open tests\bootstrap.php in the DiscoPop plugin slug folder and change

$_tests_dir = getenv( 'WP_TESTS_DIR' );

to (replacing C:\xampp\htdocs\wp_framework with the path to your framework folder)

$_tests_dir = 'C:\xampp\htdocs\wp_framework\tests\phpunit';

Now lets run PHPUnit from the plugin slug folder and presto

C:\xampp\htdocs\wp_framework\src\wp-content\plugins\discopop>
phpunit

Installing...
Running as single site... To run multisite, use -c tests/phpunit/multisite.xml
Not running ajax tests. To execute these, use --group ajax.
Not running ms-files tests. To execute these, use --group ms-files.
Not running external-http tests. To execute these, use --group external-http.
PHPUnit 6.5.8 by Sebastian Bergmann and contributors.

Time: 2.44 seconds, Memory: 30.00MB

No tests executed!

Put your PHPUnit test files in the tests folder of your plugins slug. You’ll find one named sample there already, copy it and rename it to something starting with test- (but not sample) eg: test-me.php and it will run.

You can find PHPUnit coding info here:
https://phpunit.de/manual/6.5/en/writing-tests-for-phpunit.html

This article has absolutly nothing to do with Data Recovery but if you need your flash media recovered, consider us. Recover My Flash Drive has been a pioneer in flash media data recovery for over 11 years if you need your data recovered we can do it fast, securely and confidentially. We specialize in SanDisk media and have an industry best turn around time. Click here to send us a data recovery job.