Unit Testing WordPress Plugins

 

WordPressIf 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:

  1. Setup a WordPress site to use for testing
  2. Install and activate the Pound Unit Tests WordPress plugin
  3. Place the [pound] shortcode on a page of your WordPress site
  4. Write tests and put them in your own own plugin plugin
  5. Run your tests by accessing the page with the shortcode in your browser

Pound unit testing output

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.

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.

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:

  1. Create a class that extends the LB_Test base class
  2. Write a public function that starts with “test_”
  3. At the end if your function “check()” if something is true
  4. Call Your_Test_Class::run_tests()

Here is an example test class

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:

by adding an underscore to the front of the name:

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.

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:

 

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.

  1. It’s good to pound on stuff for a while to make sure it’s ready for use.
  2. It is light weight
  3. The abbreviation for pound is LB, which are my initials 🙂

Download Pound

  Download the plugin from the official WordPress repository.  

Leave a Reply

Your email address will not be published. Required fields are marked *