Origami Book, by Jessica C

In the first post in this series about unit testing in WordPress we talked about the importance of testing our code automatically before every release, as well as the different types of tests you can run. If you haven’t read it already, go ahead and do it right away—it’s light and easy, and it’ll give you the basics you need to understand the upcoming posts on this subject.

Software testing is a broad concept—not only because of the numerous types of test you can run (unit tests, integration tests, acceptance tests…), but also because of all the different tools and frameworks you can use. Since we’re WordPress developers, we’ll just focus on how to test our WordPress plugins and themes.

As you may already know, WordPress is implemented in PHP (along with some JavaScript) and, therefore, so are our own plugins and themes. The preferred framework for testing PHP code is PHPUnit so… let’s dive in and learn how to use PHPUnit to test our PHP components!

¡Vamos a por todas! (fuente)
Time to get some fun! (source)

What is PHPUnit?

A test has three simple steps: setup the environment, act upon it, and check whether the results match your expectations or not. When we’re interested in testing our code, it’s quite clear that we need a tool or framework that allows us to define a set of tests, runs them all following those three steps, and warns us if something is amiss. As I’ve already mentioned, the framework we’ll be using for this task is PHPUnit. We could spend some time talking about it and all its features… but if you’re anything like me, you’d rather see an example, right?

In my previous post I presented a super simple function that returned the VAT value of any given price. It looked similar to this one:

I also explained how a unit test would “look like” if written in plain English. It was something like this: “hey function, if I give you the number 1000, what do I get? I’m hoping for 210” or “hey function, if I give you the string 1.000€, what do I get? I’m also hoping for 210“. To create such tests in PHPUnit you’d simply need to write the following class:

which has two simple methods (testVatOfIntegerIsCorrect and testVatOfStringIsCorrect) that implement the tests programmatically. Pretty straightforward, isn’t it?

Now, what if you were to run those tests? What would happen? The first test should work—our function multiplies the input value (1000) by 0.21 and returns the exact value we were expecting: 210. The second function, on the other hand, would probably fail. Its input value is a string ('1.000€') and, as such, multiplying it by 0.21 doesn’t make much sense! Keep reading to discover what actually happens with the previous setup ?

Setting Up a PHPUnit Environment to Test Your WordPress Plugin/Theme

Congratulations! You now know how a PHPUnit test looks like. We could probably end the post here but… wait, how the heck do we test stuff in WordPress? Well, we first need to install and configure a couple of tools. Pippinsplugins has a wonderful post where he explains how to setup the environment. Essentially, you need to:

  1. Install PHPUnit. If you want to write and run PHPUnit tests, you need PHPUnit, don’t you? Just follow the instructions detailed in their Github repo.
  2. Install WP-CLI. Since we’re interested in testing WordPress components, we need a tool to quickly setup WordPress installations. As you can imagine, doing so from the command line is much faster than browsing pages with your web browser. WP-CLI (WordPress-Command Line Interface) is the right tool for this job. If you’re using VVV in your development projects, WP-CLI is already there; if you aren’t, install it following the instructions from their website.

Once they’re installed, setting up the environment is as easy as running the following commands. First, access the root directory of your WordPress installation:

cd vagrant-local/www/wordpress-default/

and run this command:

wp scaffold plugin-tests plugin-name

where plugin-name is the name of the plugin you want to test. For instance, ours would be nelio-content.

If you now check the plugin’s directory, you’ll see there are new files and directories:

  • bin/
    • install-wp-tests.sh
  • phpunit.xml
  • test/
    • bootstrap.php
    • test-sample.php
  • .travis.yml

all of which are related to PHPUnit.

Finally, run the following command:

bash bin/install-wp-tests.sh wordpress_test root password localhost latest

where wordpress_test is the name of a new database (where you test data will be saved), root is your database username, password is its password, and localhost is the name of your database server (all these information can be found in your WordPress’ wp-config.php file). This will create a new database so that your tests don’t interfere with your actual WordPress installation.

Once the process is over, run phpunit and you’ll see that everything’s working fine:

PHPUnit Test Example
Right after setup, this is what you’ll get if you run PHPUnit. Image by pippinsplugins.

A Note for Vagrant-VVV Users

If you’re using VVV, the previous commands won’t work. I had trouble figuring out why, but the reason’s actually quite stupid—you need to run them inside your virtual box. To access it, just run:

vagrant ssh

Within the virtual box, WordPress can be found at:

cd /srv/www/wordpress-default/

Go in there and apply the steps we shared above. That’s it!

Oh! And remember: every time you want to run your tests, you’ll have to access the virtual machine—if you don’t, your tests won’t work (if any of you, guys, knows how to run them from the host, let me know in the comments!).

Our First Simple Test

Let’s see how to apply all we’ve seen so far, shall we? To make your life easier, I’ve prepared and shared this simple plugin; add it in your WordPress installation using the following commands:

cd /srv/www/wordpress-default/wp-content/plugins
git clone https://github.com/davilera/nelio-vat-example.git

and setup the environment as we’ve just seen:

cd /srv/www/wordpress-default
wp scaffold plugin-tests nelio-vat-example
cd /srv/www/wordpress-default/wp-content/plugins
bash bin/install-wp-tests.sh wordpress_vat_example root root localhost latest

Once everything’s ready, delete test-sample.php from tests/ and create a new file named test-vat-function.php. Edit this file and add the VatFunctionTest we discussed above. After that, go back to the directory and run the test using phpunit:

Failed test in PHPUnit.
Failed test in PHPUnit.

Oops! What did just happen? There are FAILURES! As scaring as this might look like, it’s actually completely normal that this happened. Our class defined two different tests and one of those was trying to verify that string arguments are also accepted by our tested function neliovat_get_vat. As anticipated, multiplying the string 1.000€ and 0.21 is not returning the expected result… ?

So here comes your homework: rewrite neliovat_get_iva so that both tests pass! Next week I’ll share the solution, but give it a try ?

Summing Up

Today we’ve seen what’s PHPUnit and how we can use it to test our WordPress plugins and themes. Essentially, PHPUnit is a tool for creating, running, and verifying our PHP code using unit tests written (also) in PHP. We’ve also learned how to setup the testing environment. It’s not the most complicated task in the world, but it takes a while until you have everything up and running.

I hope you liked the post! See you soon with the next one!

Featured Image by Jessica C.

11 responses to “Introduction to Unit Testing in WordPress – PHPUnit”

  1. Kira Avatar

    Nice tutorial for testing WordPress code. It would have been great if there was a mini tutorial on how to install PHPUnit (like in this article: https://www.cloudways.com/blog/getting-started-with-unit-testing-php/ ).

    1. David Aguilera Avatar

      Thanks for your kind words and for sharing the article 🙂

  2. Russell Fair Avatar
    Russell Fair

    Hi thank you for this. I was running phpunit while doing a new plugin dev project. I was attempting to use a new function (get_registerd_settings) which shipped in 4.7.0. My phpunit install was out dated and was using 4.5.3 – I couldn’t for the life of me figure out why the function didn’t exist. I realized that I needed to re-run the install script after deleting /tmp/wordpress. This tutorial helped me find my way!

    1. David Aguilera Avatar

      Thanks for sharing your experience, Russel! That’s a pretty common error 😉

  3. Ilibilibom Avatar

    Thanks great tutorials !!

  4. Collins Agbonghama Avatar
    Collins Agbonghama

    One of the easy to follow tutorials on WordPress unit testing. Thanks you David for writing this.

    1. David Aguilera Avatar

      Thanks! You’re welcome 🙂

  5. Tarek Avatar

    Thanks David, That was very helpful.

    1. David Aguilera Avatar

      Thanks, Tarek; I’m glad to know it helped 🙂

  6. Ben Attenborough Avatar

    I ran into a problem (but have a solution). I’m using php 7.1.13, but you can only use phpunit 6 with that version (for reasons, see https://www.drupal.org/project/drupal/issues/2927806). So you might need to either install phpunit 6 globally with something like (on a mac):

    curl https://phar.phpunit.de/phpunit-6.phar -L -o phpunit.phar
    chmod +x phpunit.phar
    mv phpunit.phar /usr/local/bin/phpunit

    OR use phpunit 6 locally by installing it as a composer dependency

    1. David Aguilera Avatar

      Thanks! An alternative solution is to run PHPUnit in a virtual machine (such as the one provided by varying vagrant vagrants), even though it’s way slower than running it directly on your machine.

Leave a Reply

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

I have read and agree to the Nelio Software Privacy Policy

Your personal data will be located on SiteGround and will be treated by Nelio Software with the sole purpose of publishing this comment here. The legitimation is carried out through your express consent. Contact us to access, rectify, limit, or delete your data.