We’ve been talking a bunch about unit tests lately, starting with the basics, and then moving up to adding tests to a plugin, so you could see it in practice. We’ve also covered how to use Github Actions to deploy your site automatically to your host. Today, we’re going to take pieces from both of these concepts and combine them, so that we’re running our tests automatically with Github actions when we push new code to the repository.
WP Testing Tools
The easiest way I’ve found to get started is with WP Testing Tools from Valu Digital. The team at Valu Digital has provided a fairly easy way to get your tests up and running on Github Actions. We’re only going to cover how to use their base template to start from scratch with your plugin development so that you can run tests. Adding their test setup to an existing plugin takes a bit more work.
Add WP Testing Tools Setup to an Existing Plugin
To start, clone the repository onto your local computer.
git@github.com:valu-digital/wp-testing-tools.git your-plugin-name
Next, we need to grab the plugins folder from inside the repository as that will be the base for our plugin. Migrate that folder to where you want your new plugin and rename it to match the plugin name you want to use.
Dealing with Composer
This testing setup requires Composer, which you don’t need to be intimately familiar with today. I’ll cover Composer in detail in a future post. For now, you’ll need to run composer install to install the required dependencies for WP Testing Tools.
Unfortunately, I’ve found that the repository is missing some required Composer packages so we’ll need to make sure these are also installed with the following commands.
composer require codeception/module-rest --dev
composer require codeception/module-phpbrowser --dev
composer require codeception/module-db --dev
composer require codeception/module-asserts --dev
composer install
Wait, I got memory errors with Composer. Help! It probably doesn’t matter and you shouldn’t get them in Github Actions so you can ignore it for now.
Now we have the proper tools installed, you can push to Github and you’ll see that the unit tests run without issue. This plugin still isn’t ready for us to build on though so let’s get to renaming the other strings in it and make it our own.
Setting Up Plugin Files
We can start by renaming the plugin header information found in plugin.php. Name it whatever suits your plugin and make the author yourself. We’ll also need to change the namespace and class entries so that we’ve named them properly for our project. I’m changing the namespace to my company name and using PluginBase as my class name for this tutorial. You can see my working renamed file below. I’ve also cleaned up the comments to make it easier to read.
<?php
/**
* Plugin Name: Nexcess - Github Actions Unit Tests
* Plugin URI: https://nexcess.net
* Description: Plugin base that runs unit tests with Github Actions
* Author: Curtis McHale
* Version: 0.1.0
*
* @package example
*/
if (!\class_exists('\Sfndesign\PluginBase')) {
require_once __DIR__ . '/vendor/autoload.php';
}
\Sfndesign\PluginBase::init();
Now in composer.json, we have a few things to change around as well. Make sure that you’re listed as the author of the plugin and change the links to Github Issues and Source to match your repository. You’ll also need to change the namespace of your plugin under the autoload entry. I’m using my company name so mine says Sfndesign. You can see my changed composer.json file below.
{
"name": "sfndesign/pluginbase",
"description": "Actions Plugin",
"type": "wordpress-plugin",
"license": "GPL-2.0-or-later",
"authors": [
{
"name": "Curtis McHale",
"email": "curtis@curtismchale.ca",
"role": "developer"
}
],
"require-dev": {
"valu/wp-testing-tools": "^0.4.0",
"lucatume/wp-browser": "~2.2",
"codeception/module-rest": "^1.2",
"codeception/module-phpbrowser": "^1.0",
"codeception/module-db": "^1.0",
"codeception/module-asserts": "^1.3"
},
"autoload": {
"psr-4": {
"Sfndesign\\": "src/"
}
},
"scripts": {
"wp-install": "wp-install --full --env-file .env --wp-composer-file composer.wp-install.json",
"wpunit": "codecept run wpunit",
"functional": "codecept run functional",
"test": [
"@wpunit",
"@functional"
]
},
"config": {
"optimize-autoloader": true
},
"support": {
"issues": "https://github.com/example/example/issues",
"source": "https://github.com/example/example"
}
}
Now we need to change the name of the Example.php file found in the src directory. I’m going to call it PluginBase.php to stick with the format we’ve been using. Next, open that file and change the namespace to Sfndesign and the class name to PluginBase. You can see the adjusted file below.
namespace Sfndesign;
class PluginBase {
public static function init() {
define( 'EXAMPLE', 'initialized' );
add_action('the_title', function () {
return 'EXAMPLE TITLE MOD';
});
}
}
Now that we’ve made these adjustments we need to run composer update again so that Composer registers the new autoload paths that are needed with our renamed files.
Finally, to make sure the whole thing is working well, I find it easier to change their initial test found in tests/ExampleTest.php to something that will return true no matter what. You can see this code below.
public function testInit()
{
$this->assertTrue(true);
}
Now that we’re set up, you can initialize your plugin as a git repository and then push it to Github. Once you’ve done this you should see an action running under the Actions tab for your repository and everything will come back green because your unit test has been run.
Throughout the last few posts, we’ve written tests and used Github Actions to automate parts of our process. Now, it’s up to you to use these tools in your client projects. You won’t write tests later, so make sure you start your projects with tests from the beginning. If you want to go even deeper with testing there is an excellent course by Fränk Klein that explains Unit Testing in WordPress. It’s already on my list to go over so that I can get better at my testing practices.
