How To Install PHPUnit for WordPress on Windows

Unit testing is an indispensable tool for any developer, regardless of the language they use. The same goes for WordPress plugin development. However, I'm not here to regurgitate its importance, benefits and bla bla bla... I would like to talk to you about a more pressing issue instead: getting the damn thing set up on Windows! The fact that Windows isn't a Unix based system can sometimes make even the simplest of tasks a nightmare. Likewise, attempting to install PHPUnit for WordPress on Windows was no exception. Fortunately for you, I'm about to share my super-duper installation guide, so you don't have to suffer through the same thing as I did. 🤪

Please note that this installation was performed on Windows 10. You may try it out on another version, but I can't guarantee it will work.

Requirements

No one should come to a battle unprepared and you shouldn't either. In order to pull this whole thing off, you will need the following tools: 🔨

• Composer
• Apache Subversion
• WP-CLI

I'm going to assume you already have Composer installed, as any good PHP developer should have. If not... 🤨 you better download it before I whoop your ass. As for the other two, let me show you how it's done!

Installing Apache Subversion

WordPress uses a source version control system called Apache Subversion and you're going to need it to set up the test environment of your plugin. If you've already got it installed, color me impressed. You're a real tech wizard 🧙‍♂️, bruh! If not, follow these simple steps.

First off, download Apache Subversion command line tools. Next, extract the contents of the zip file into a folder called apache-svn and place it into the directory C:\Program Files. Now, open your control panel and head over to System and Security\System and click on "Advanced system settings" on the left-hand side. You should be greeted by the following window:

In the "Advanced" tab, click on "Environment Variables". This will prompt you another window where you will select "Path" in the "System variables" section and click "Edit...".

Almost there, buddy! Hang on... In the "Edit environment variable" window, create a new variable by clicking on "New". Then give it the following name: C:\Program Files\apache-svn\bin. There you go! Mission complete.

Installing WP-CLI

Looking at the subheading, you'd think this step is simple, right? Well, whatever you're thinking, wrong! Hint: it's not... 😬 If you're using a server setup like XAMPP, WAMP or whatnot, I recommend checking out this awesome blog post by Anh Tran. He'll guide you through getting WP-CLI installed on your Windows machine.

On the other hand, if you're a Laragon user like me, there's a super brief tutorial on the Laragon forum on how to install it.

Setting up plugin unit tests

At the time of this writing, WordPress is not yet compatible with PHPUnit's latest version 8.x, but version 7.x instead. So don't go downloading version 8, only to complain that nothing works (like I did), ya hear me? ಠ_ಠ

Installing PHPUnit

To install PHPUnit, cd to the root of your plugin directory and run the following command:

$ composer require --dev phpunit/phpunit:7.*

This will install the latest version of the 7.x release tree. 🌲 Then verify it's properly installed with the command

$ ./vendor/bin/phpunit --version

Please note that it's not considered good practice to install PHPUnit globally. Instead, PHPUnit should be managed as a project-local dependency. Although, there's nothing stopping you from you doing otherwise... 😐

Creating the plugin test files

Alright, still in your plugin directory? Great! This time we're going to use WP-CLI to create the plugin test files.

$ wp scaffold plugin-tests <insert-plugin-name>

By default, the following files are generated: 📁

• phpunit.xml.dist - the configuration file for PHPUnit
• .travis.yml - the configuration file for Travis CI
• bin/install-wp-tests.sh - configures the WordPress test suite and a test database
• tests/bootstrap.php - the file that makes the current plugin active when running the test suite
• tests/test-sample.php - a sample file containing the actual tests
• .phpcs.xml.dist - a collection of PHP_CodeSniffer rules

Creating a test database

Next, we are going to use the previously generated bin/install-wp-tests.sh file to create a test database.

$ bin/install-wp-tests.sh wordpress_db_test root '' localhost latest

Here's what you need to know about the command above. To start off, wordpress_db_test will be the name of your test database. You may name it however you like... well, except after the names that already exist. 😆 Furthermore, and in most cases, the default database user tends to be called root and has no password, hence root ''. You may need to change this if it isn't the case for you.

Now... if everything went well, run ./vendor/bin/phpunit in your plugin directory. This will execute any PHPUnit tests.

The problems

Chances are, in the previous section, everything didn't go as smoothly as you anticipated... But that's OK! I got you covered, mi hombre. 😏

Oh Laragon, what are thou doing?

If you're a Laragon user, you'll want to pay close attention to this section. If not... wait! You may find a golden nugget or two to solve your problems. 😀

Whenever I attempted to create the test database through the Cmder console emulator, Laragon would use Git Bash in the background to execute the install-wp-tests.sh file. As a result, the execution would fail because Git Bash couldn't recognize the command mysqladmin. Solution? Add it to the PATH environment variables. ➕

Remember when you added Apache Subversion to the PATH environment variables? 🤓 You're going to want to do the same, but specify C:\laragon\bin\mysql\mysql-5.7.24-winx64\bin as the path instead (or wherever your mysqladmin.exe executable is located).

Furthermore, I recommend that you use Git Bash instead of Cmder to create the test database, as the latter still appears to not execute it properly. Just remember to restart Git Bash after adding a new environment variable. And while we're at it, before rerunning the command for the test database, make sure to delete the folders wordpress and wordpress-test-lib in C:\Users\<username>\AppData\Local\Temp. Drop the test database as well if it was created.

require_once(...) errors

Warning: require_once(/tmp/wordpress//wp-includes/class-phpmailer.php): failed to open stream: No such file or directory in C:\Users\dilshan\AppData\Local\Temp\wordpress-tests-lib\includes\mock-mailer.php on line 2

Fatal error: require_once(): Failed opening required '/tmp/wordpress//wp-includes/class-phpmailer.php' (include_path='.;C:/laragon/etc/php/pear') in C:\Users\dilshan\AppData\Local\Temp\wordpress-tests-lib\includes\mock-mailer.php on line 2

If you've got an error ❌ similar to that above, you can fix it by doing the following change. In C:\Users\<username>\AppData\Local\Temp\wordpress-tests-lib\wp-tests-config.php, on line 7, replace the relative path of /tmp/wordpress/ with an absolute path: C:/Users/<username>/AppData/Local/Temp/wordpress/. After making the change, it should look like below.

define( 'ABSPATH', 'C:/Users/dilshan/AppData/Local/Temp/wordpress/' );

Run ./vendor/bin/phpunit and... it wor- oh no! A warning. 😨

Fortunately, this is only a warning, which I (think I) fixed by adding the attribute name="..." to <testsuite> in the phpunit.xml.dist file. But at this stage, I'm happy to have finally installed PHPUnit for my WordPress plugin, and I hope you are too! 😋