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!
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:
- 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.
- 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.xmltest/bootstrap.phptest-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:
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.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 ?
Nelio Forms
A fantastic contact plugin using the block editor. In its simplicity lies the true power of this plugin. I love it, very versatile and it worked perfectly for me.
Wajari Velasquez
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.
Leave a Reply