If you are developing a WordPress plugin, it good idea to write some automated tests for it. Pound is a light weight WordPress plugin that will run tests you write for your own plugin. It’s not a framework or library and introduces no dependencies for your plugin. It just runs tests that your write for your own plugin without all the overhead of PHPUnit.
How It Works
A quick overview of how it works:
- Setup a WordPress site to use for testing
- Install and activate the Pound Unit Tests WordPress plugin
- Place the [pound] shortcode on a page of your WordPress site
- Write tests and put them in your own own plugin plugin
- Run your tests by accessing the page with the shortcode in your browser
While it’s not mandatory, it’s probably a good idea to setup a WordPress site locally that you use just for testing. Install and activate the Pound Unit Tests plugin in your test WordPress site. Then add the [pound] shortcode to a page of your WordPress site. You can add it to any page you want, the Home page, or create a page called “Tests” and have that be your dedicated test page.
Using The Shortcode
Pound has one shortcode that accepts three parameters.
[pound plugin="plugin-name" dir="tests" file="test-all.php"]
Shortcode Parameters
plugin: The name of the directory for the plugin you want to tests. For example, if you wanted to run the example tests included with Pound, you would use the name “pound” because that is the root directory for the plugin.
dir: (optional) The directory name where you are storing your tests. Use the relative path from the root directory of your plugin. If you leave the out, it is assumed that you will store your tests in a directory called tests
file: (optional) The file that holds the tests you want to run. If you leave this out, it is assumed that you will use a file called test-all.php
Running The Example Tests
There are a few trivial tests included with Pound so you can see how simple it is to write and run tests and so you can see what the output of the tests looks like. After installing and activating Pound, you can test it out by putting this shortcode on a page of your WordPress site and accessing it in your browser.
[pound plugin="pound"]
You don’t need to include either of the two optional parameters because Pound is set up in the expected, default configuration with a tests directory to hold the tests and a test-all.php file to run the tests.
Writing Your Tests
The following four steps are all you need to do to write your own tests:
- Create a class that extends the LB_Test base class
- Write a public function that starts with “test_”
- At the end if your function “check()” if something is true
- Call Your_Test_Class::run_tests()
Here is an example test class
class Test_Group_Three extends LB_Test {
public function test_age_is_greater_than_20() {
$age = 18;
$this->check($age > 20, "The age should be greater than 20 but was $age");
}
}
Test_Group_Three::run_tests();
Organizing Your Tests
There are several options for organizing your tests. I’d recommend breaking your tests into logical groups and creating test classes for those groups. You can see in the example tests included in Pound that there are three tests classes:
- class-test-group-one.php
- class-test-group-two.php
- class-test-group-three.php
All of the classes or structured like Class Test_Group_Three (shown above). At the bottom of the file, outside of the class definition, call the static method run_tests().
Then, in the test-all.php file, simply include the classes you want to run. The test-all.php file doesn’t need to be anything but a list of include statements.
Alternatively, if you have a small plugin and don’t intend to write many tests, you can write your own test class right in the test-all.php file. It’s probably a good idea to break your test in to groups and then include them in the test-all.php file. It always seems like projects grow and you go back and try to better organize your tests.
If you wanted to go a step further, you could put test classes in their own sub-directories. Then just modify the include statements in the test-all.php file accordingly.
Naming your test functions
Pound will run any function that starts with “test_” as a test function. The output will strip the “test_” prefix off, capitalize the first letter of the first word, and replace underscores with spaces. So if you name your tests like short sentences, you’ll get nice output.
For example, a name like test_age_is_great_than_20() will show up in the output as (assuming the test passes):
Passed: Age is greater than 20
Skipping Tests
Sometimes there are tests you don’t want to run every single time. You can skip individual tests or entire test groups.
To skip an individual test you can prefix the function name with an underscore.
For example, change this function name:
public function test_age_is_greater_than_20() { ... }
by adding an underscore to the front of the name:
public function _test_age_is_greater_than_20() { ... }
If you want to skip entire groups of tests, you can simply comment out certain include statements from your test-all.php file.
Setup and Tear Down
You may want to run some code before and/or after your tests to set things up or to clean up after your tests.
before_tests() is called before any tests are run in your test class
after_tests() is run after all the tests in your test class have been run
There are also hooks for before and after each individual test.
before_each_test() is called before running each test in the given test class
after_each_test() is called after running each test in the given test class
It is a good idea to clean up after yourself so each test is run with a known initial configuration. These hooks come in handy for making sure your test environment stays in the condition you expect it to be in while testing.
Assertions
PHPUnit has a very large library of assertions. Pound just has one. There is a check() function that takes two parameters.
$this->check( $condition, $message );
The first parameter is a $condition that you expect to be true. If it’s not true, then the output will include the $message content. No matter what you are checking for, it is possible to boil it down to a simple true or false condition. You can use PHP itself to get you there by counting array elements, checking class names, looking for exceptions to be thrown, comparing strings, etc. So, Pound just keeps that simple too. Check if something is true and display a message if you don’t get what you expect.
Hint: Include a variable in your $message. If you are looking for $age to be greater than 20, include the value of $age in the message. You’ll find that helpful when you look at the output and need to go back and repair failed tests.
Pound does come with a small library of helper function in the LB_Should class so you can write things like:
public function test_should_start_with_Pound() {
$haystack = 'Pound helps me write tests for my plugin';
$result = LB_Should::start_with($haystack, 'Pound');
$this->check( $result );
}
Summary
Please understand, I’m not saying that PHPUnit and/or WP-CLI are bad at all or that you shouldn’t use them. I have found Pound to be helpful for my own development and thought maybe other people might as well. It’s an easy way to start testing your plugins. If more developers can get into testing then that seems cool to me.
If there are any features you’d like to see added, just let me know. Thanks for checking it out!
Why Is It Called Pound?
I didn’t put a great deal of thought into creating a fancy name, but here are three reasons behind the name Pound for this plugin.
- It’s good to pound on stuff for a while to make sure it’s ready for use.
- It is light weight
- The abbreviation for pound is LB, which are my initials 🙂