Unit testing in WordPress has come a long way with the help of WP-CLI, but it can still be a bit frustrating to set up correctly. These two tutorials were a great help to me when getting started:
Pippin Williamson’s Unit Tests for WordPress Plugins
Tom McFarlin’s How To Perform Unit Testing with Pressmatic
But even with these great references I was having a rough time getting unit tests to run in my DesktopServer WordPress installations. What I didn’t realize is that you have to use the DS-CLI plugin in order to use the correct instances of MySQL, Apache, and PHP. One nice thing about DS-CLI is that it already comes bundled with WP-CLI, and PHPUnit, so you don’t have to handle the installation yourself.
So, here is how you set up your unit tests in DesktopServer:
- Open the DS-CLI and CD to your project’s plugin directory.
- Recommended: backup your database using the command
wp db export
. - Run
wp scaffold plugin-tests name-of-your-plugin-folder
- CD into your plugin’s root directory and run
bash bin/install-wp-tests.sh wordpress_test root '' localhost latest
. Among other things, with this command we are creating a new database called “wordpress_test”. You can call the database whatever you like, just do not try to connect to your actual project database because it will be overwritten. This is why we made a database backup in step 2. - Open up the /tests/bootstrap.php file in your plugin folder (this was created in step 3) and ensure the plugin file name on line 20 is correct. Change the file name if it’s not correct and save the file.
- CD to the plugin folder (still using DS-CLI) and run the command
phpunit
. - If all goes well you will see a success message for 1 test and 1 assertion.
Common sources of error are:
- Using the terminal rather than DS-CLI.
- The /test/bootstrap.php file is attempting to load a plugin file that does not exist.
- /tmp/wordpress-tests-lib does not exist. Fix: run
rm -rf /tmp/wordpress-tests-lib; bash bin/install-wp-tests.sh wordpress_test root '' localhost latest
to remove relic files and reinstall the necessary WordPress test files.
Alain Schlesser says
Hey Tim,
I just wanted to chime in to make an import distinction. What you describe above is using the “WordPress Core Unit Tests” framework in your own plugin to run tests. However, these are meant to “unit test” WordPress Core. If you use them in your plugin, you are not “unit testing” your own plugin. A “unit test” is done in isolation. What you are rather doing is an “integration test” or “functional test”.
Proper unit tests for your plugin would not need a database, or WordPress, or access to the web server. They would just need PHP to be compiled and run. For a very good introduction to proper unit testing with WordPress, I can recommend a blog post from Thorsten Frommen: https://tfrommen.de/an-introduction-to-unit-testing-for-wordpress/
Cheers,
Alain
Tim Jensen says
Thanks for pointing out that distinction, Alain. I guess my intention here was to help plugin developers get set up to do at least some kind of testing, because the vast majority do not (so I’m told). Even though testing plugins with
WP_UnitTestCase
is not strictly “unit testing”, I still think there is some value to it. At the very least it is a step in the right direction that hopefully will lead plugin developers to do proper unit testing in the future. Myself included.Alain Schlesser says
Yes, absolutely. Every kind of testing is preferable to no testing at all. I didn’t want to imply that this type of testing was bad in any way. Also, in a lot of cases, real unit tests might not easily be possible, if the code was not specifically designed to support them.
So, don’t mind my “pursuit of precision”, and test away! 😉