If you decide that you need to make unit tests on your plugin, it is because it’s quite complex and it’s probably a mix of PHP and JavaScript code. If you think that testing just your PHP code is enough, you are definitely on the wrong path. The JavaScript code can be as complex as the PHP counterpart, and as likely to have bugs in it.
When I started studying the problem of making unit tests on JavaScript I found a number of frameworks available, and I soon got confused. What should I do? What is the best framework? As it turns out, there isn’t really a ‘best testing framework of the realm’, you should just choose one and stick with it. My choice has been determined by the documentation that I’ve found online that could help me understand how to configure it. Probably JavaScript unit testing isn’t a sexy topic because finding articles and guides online has been hard. Luckily for me, less than a month ago Tim Evko has written a fantastic guide on SitePoint where he explains how to install Jasmine and Karma both locally and on Travis CI. Unfortunately, the part related to Travis CI is only partially usable for our scope but I will explain this in the next article of this series.
Starting from the SitePoint guide I’ve been able to expand further my configuration, and I could also run QUnit as alternative to Jasmine. The two libraries are alternative, meaning that you cannot mix testing functions written in either of them and run them together. You must choose one, which is not bad. After all, I wouldn’t advise you to learn both testing libraries since they are meant to do the same things, and they use different syntax.
Installing Node.js
Node.js is the cornerstone of our testing suite. The reason why Node.js is fundamental is that JavaScript is a frontend language, and runs inside the browser. However, here we are going to run our tests on the server side, where we don’t have any browser. Node.js is a JavaScript library born to execute JavaScript on the server side, so this will allow us to run our tests. If you want to know more about its history you can read the Wikipedia page dedicated to Node.js.
To install Node.js you can visit their website and follow the instruction related to your platform. I haven’t had any issues in my Ubuntu Linux and Windows installations.
Once the installation of Node.js is finished you must run the command npm init from inside your plugin’s top directory. This command will create the node_module folder and the file package.json that configure all the dependencies. The command is smart enough to add the node_module folder to the .gitignore file, so you won’t push your testing libraries to Github.
Once Node.js is installed you are ready to install Karma and Jasmine.
Installing Karma and Jasmine
Karma is what allows us to run the testing framework of our choice. To install Karma run the following command
npm install karma --save-dev
The command doesn’t change whether you use the Windows terminal or Linux. After this you need to install the Karma modules needed to execute our testing scripts.
npm install karma-jasmine karma-firefox-launcher --save-dev
Before configuring Karma we must still install a package, or you won’t be able to launch Karma commands from the command line
npm install -g karma-cli
We are almost ready. The final step is to configure Karma to use the modules that we just installed
karma init my.conf.js
This screenshot shows a simple settings that works for me.
If you haven’t created your tests directory yet for JavaScript, now it’s time to do it. My suggestion is to create a separate directory for JavaScript tests, like the one that you can see in the screenshot above.
To test if my Karma configuration works I’ve created a very simple testing file with two assertions. One succeeds and one fails.
describe("A suite", function() {
it("contains spec with an expectation", function() {
expect(true).toBe(true);
});
});
describe("A second suite", function() {
it("contains spec with an expectation", function() {
expect(false).toBe(true);
});
});
Once you’ve put this file in your tests folder, run the following command to start the tests
karma start my.conf.js --single-run
That’s it, it’s as simple as that.
Installing QUnit as Alternative to Jasmine
Qunit is a JavaScript unit testing framework developed and used by the JQuery project. It’s the unit testing framework chosen by the WordPress team to run the tests on the WordPress core.
Installing QUnit is not different as installing Jasmine. You don’t need to remove Jasmine if you want to use QUnit, you can just install it as an additional module, and then instruct Karma to use it instead of Jasmine
npm install karma-qunit --save-dev
This is the basic test that I’ve used to test QUnit
QUnit.test("basic test", function( assert ) {
assert.equal(1, 1, '1 === 1');
});
QUnit.test("failing test", function( assert ) {
assert.equal(1, 0, '1 === 0');
});
You can also use the Mocha testing framework. However, I think that you’ve understood the process, so I’ll leave that to you if you want.
In the next article I will put it all together and make our tests run on Travis
Other Articles in This Series
Unit Tests in WordPress: an Introduction
So, what do you think ?