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.
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: 🔨
- Apache Subversion
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.
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.
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? ಠ_ಠ
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.
Chances are, in the previous section, everything didn’t go as smoothly as you anticipated… But that’s OK! I got you covered, my 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
C:\Users\<username>\AppData\Local\Temp. Drop the test database as well if it was created.
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/' );
./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
<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! 😋
Did you find what you came for? Want me to cover something else? Let me know in the comments below! Share, if you liked this post! This installation caused me a lot of headaches, so I hope you benefited from my experience.