I think we can all agree that unit testing is pretty neat.
An automated system for checking if your code changes break any functionality is almost magic, and if you aren’t sure where to get started with it, you should read my previous post Unit Testing Your Plugins.
If you’ve spent some time on Github, you’ve probably heard of TravisCI, a continuous integration service that automatically runs tests for every commit and pull request on your repository. It’s super cool, very easy to set up, and free for open source projects.
One of the best parts of TravisCI is its ability to run your tests in multiple environments. In one go, you can test your plugin on several versions of PHP and WordPress and catch edge cases you might run into in versions you don’t develop on.
Our plugin generator by default sets up a TravisCI configuration so without any work on your part you can have your plugin tested on multiple environments for every commit. The one issue with TravisCI is you can’t easily run these tests locally, so you won’t have an idea of if your tests will run properly on all environments until they are pushed to GitHub.
Enter Dockunit
Dockunit is like a offline TravisCI. It uses Docker to create local compartmentalized testing environments so you can easily run your tests on whatever setup you want. Docker is a container based system for running applications bundled with their dependencies. I’m doing a poor job of explaining it fully, but it’s really interesting and if you like virtualization and dev ops stuff you should take a look.
To run Dockunit, you will need OSX or Linux with Node and Docker installed.
First, we have to install Dockunit itself which you can do with a simple npm command:
$ npm install -g dockunit
One we’ve run that command, we need to configure our plugin to properly run its tests through dockunit. We do this in the Dockunit.json file. Here is a basic example of one that should work for most plugins that use the wp-cli scaffolded test setup:
{"containers":[{"prettyName":"PHP 5.2 FPM WordPress 4.5","image":"dockunit\/prebuilt-images:php-mysql-phpunit-5.2-fpm","beforeScripts":["service mysql start","bash bin\/install-wp-tests.sh wordpress_test root '' localhost 4.5"],"testCommand":"phpunit"},{"prettyName":"PHP 5.6 FPM WordPress 4.4","image":"dockunit\/prebuilt-images:php-mysql-phpunit-5.6-fpm","beforeScripts":["service mysql start","bash bin\/install-wp-tests.sh wordpress_test2 root '' localhost 4.4"],"testCommand":"phpunit"},{"prettyName":"PHP 7.0 WordPress 4.3","image":"dockunit\/prebuilt-images:php-mysql-phpunit-wordpress-7.0-fpm","beforeScripts":["service mysql start","bash bin\/install-wp-tests.sh wordpress_test3 root '' localhost 4.3"],"testCommand":"phpunit"}]}
This file sets up three environments for Dockunit to test your plugin in:
- PHP 5.2 with WordPress 4.5
- PHP 5.6 with WordPress 4.4
- PHP 7.0 with WordPress 4.3
Which gives you good coverage of a wide range of PHP versions and the three most recent WordPress versions. It is very simple to adjust which versions of WordPress to install for each environment, just adjust the version installed on lines 8, 17, and 26.
Now, with this file placed in the root of your plugin, we are almost set to run Dockunit. We need to make sure Docker is up and running before we run Dockunit, but there are a number of ways to do that depending on your OS. The docker site has in depth tutorials on both installation and basic usage.
Now we can simply run:
$ dockunit
…in the root of the plugin, and then all of your tests should run in all three environments. It takes a bit to get each environment set up, so that’s a good time to step away and get a drink of water or something.
And there you go, all your plugin tests running on multiple environments!
Dockunit is by default configured with any generator-plugin-wp plugin, so if you’re interested give it a try and write more tests!