First time, when I try to setup PHPUnit inside a WordPress plugin, it seems like I can not run test for this plugin. After spending more hours on it, now it seems like its so easy like create a plugin in WordPress.
I have learned many things during this process. Like how to create a plugin with WP CLI, how to setup plugin for PHPUnit test and many more things. Here I will cover about those topics.
Here is WordPress’ guide for PHPUnit test.
At first you have to setup WP CLI in you system. You can check its status from the terminal.
wp --version
WP-CLI 2.5.0
Now its time to setup other things.
Let download and setup WordPress with WP CLI.
Here is how to setup WordPress using WP CLI
After successfully setup and install you can run wp admin command from your terminal.
wp admin
It will open WordPress admin page in your browser.
Now its time create plugin. From the plugin directory of your WordPress site run below command to create plugin named sample-plugin
wp scaffold plugin sample-plugin
You need to pass a plugin slug after plugin command. It will execute and create a plugin with some basic stuff. After successfully complete the process you will get a success message like below.
wp scaffold plugin sample-plugin
Success: Created plugin files.
Success: Created test files.
Here is the list of file what is being created during this command execution.
A simple plugin boilerplate with necessary testing stuff. Like a tests directory for test, phpunit.xml
for test config file, .travis.yml
, Gruntfile.js
, bin directory
what contain bash files.
Inside package.json
file, there are a couple of npm
dependency. You need to install it by running below command from your plugin directory.
npm install / yarn
Now its time to initiate composer in your plugin. Run below command for this purpose.
composer init
You will get couple of input to place during this command execution. You can place your input there. Here is mine.
In this step you need to install PHPUnit inside your plugin. Not all version of PHPUnit are not compatible with WordPress latest version.
you can check the PHPUnit compatibility with WordPress latest version from here.
Here in my local setup I am using WordPress 5.8.1 . PHPUnit 7.5.9 version is compatible with this WordPress version. So I need to install this version of PHPUnit in my plugin. Run below command to install this version of PHPUnit.
composer require --dev phpunit/phpunit 7.5.9
After successful installation process your can check your local PHPUnit version.
Run below command from your sample-plugin
directory
.\vendor\bin\phpunit.bat --version
.\vendor\bin\phpunit.bat --version
PHPUnit 7.5.9 by Sebastian Bergmann and contributors.
You are all setup now. You can run your test from your plugin like below.
In this step you need to run a bash command to initialize the testing environment locally.
bash bin/install-wp-tests.sh wordpress_test root '' localhost latest
If you run only bash bin/install-wp-tests.sh
it will let you know what else is needed to provide to execute this command. You need to provide a database name, mysql username, password, host name and WordPress version to install.
This script actually create install a WordPress into /tmp directory with necessary tools for testing.
If you face output like below, you might have bad setup for WordPress.
If you run test now you might have error like below.
.\vendor\bin\phpunit.bat
Could not find C:\Users\thean\AppData\Local\Temp/wordpress-tests-lib/includes/functions.php, have you run bin/install-wp-tests.sh ?
Solution
For the Windows user you need to cover few more steps to run test. Here in my I open below directory
C:\Users\thean\AppData\Local\Temp\
You might have a folder named wordpress
and wordpress-tests-lib
in you Temp directory. Now delete those folders.
You have to remove --quiet
flat from your install-wp-tests.sh
file. Here is what I did
old
-----
svn export --quiet --ignore-externals https://develop.svn.wordpress.org/${WP_TESTS_TAG}/tests/phpunit/includes/ $WP_TESTS_DIR/includes
new
---
svn export --ignore-externals https://develop.svn.wordpress.org/${WP_TESTS_TAG}/tests/phpunit/includes/ $WP_TESTS_DIR/includes
In a word you have remove --quiet
flat from everywhere from install-wp-tests.sh
file. Now run below command from your terminal with the specify with WordPress version
. I specify 5.8.1
. Before run this command, make sure you delete previously created database named wordpress_test
.
bash bin\install-wp-tests.sh wordpress_test root '' localhost 5.8.1
Here is the actual output of successfully installation. Notice that it downloading the specified version of WordPress. There is more but can capture the full screen.
Now run the below command
.\vendor\bin\phpunit.bat
You might end up with the error like below
PHP Warning: require_once(/tmp/wordpress/wp-includes/PHPMailer/PHPMailer.php): failed to open stream: No such file or directory in C:\Users\thean\AppData\Local\Temp\wordpress-tests-lib\includes\mock-mailer.php on line 2
Warning: require_once(/tmp/wordpress/wp-includes/PHPMailer/PHPMailer.php): failed to open stream: No such file or directory in C:\Users\thean\AppData\Local\Temp\wordpress-tests-lib\includes\mock-mailer.php on line 2
PHP Fatal error: require_once(): Failed opening required '/tmp/wordpress/wp-includes/PHPMailer/PHPMailer.php' (include_path='C:\xampp\php\PEAR') in C:\Users\thean\AppData\Local\Temp\wordpress-tests-lib\includes\mock-mailer.php on line 2
Fatal error: require_once(): Failed opening required '/tmp/wordpress/wp-includes/PHPMailer/PHPMailer.php' (include_path='C:\xampp\php\PEAR') in C:\Users\thean\AppData\Local\Temp\wordpress-tests-lib\includes\mock-mailer.php on line 2
Now navigate your T
emp/wordpress-tests-lib/
directory and open wp-tests-config.php
with any editor. Replace the ABSPATH
constant like below.
old
----
define( 'ABSPATH', '/tmp/wordpress/' );
new
----
define( 'ABSPATH', 'C:\Users\thean\AppData\Local\Temp/wordpress/' );
Now run below command
.\vendor\bin\phpunit.bat
If will successfully run a simple test from your local plugin directory.
Finally
Your plugin is ready to test for PHPUnit test.