This post is part 34 of 37 in the series Programming by Stealth

In the previous instalment we had our first look at QUnit, an open source Unit testing framework for JavaScript by the jQuery project. In this instalment we’ll finish our exploration of QUnit with a look at a few more advanced QUnit features. We’ll be making regular use of QUnit in future JavaScript challenges.

Wrapping up our brief detour into testing a QUnit leaves us free to move back to HTML forms and more JavaScript practice in the next instalment. The aim is to slowly bring those two streams back together through a new multi-instalment project. Over the next few instalments we’ll be building up a web app that makes use of both web forms and JavaScript prototypes.

As usual, I’ve collected the code referenced in this instalment into a ZIP file which you can download here.

Solution to PBS 33 Challenge

The challenge set at the end of the previous instalment was to write a QUnit test suite for all or part of some or all of the date and time related prototypes we built together over recent instalments – specifically pbs.Date, pbs.Time and pbs.DateTime. The reason I left the assignment so open-ended is that writing complete test suites for all the feature and functions of this quite large API is a mammoth task that involves quite a bit of repetition. Writing some of the tests will definitely help cement what we learned about QUnit in your minds, but writing everything would likely be too much repetition, and just make you cranky. I figure you guys would stop when you’d had enough, and call it a day.

Unfortunately, in order to provide a complete sample solution which covers all possible sub-sets of the API you guys could choose to write your tests for, I did have to a complete test suite, and it was a lot of work, and there were times when it did make me a little cranky 😉

You’ll find my full sample test suite in the ZIP file for this instalment. It’s simply too big to copy-and-paste it all into the body of this post, but I will paste in a few snippets as illustrations throughout this instalment.

A QUnit Test Suite is a Regular Web Page

There is nothing special about a web page that happens to import the QUnit framework, it is still a web page, so that means that everything we have ever learned about HTML, CSS, and JavaScript can be incorporated into your test suites. You can declare variables if you find that a helpful thing to do. You can declare functions if you’d find that a helpful thing to do. And, you can of course use all the control structures you’ve learned about, including loops, to reduce the amount of copying-and-pasting in your test suites.

In short – you can use everything you know about JavaScript to make your test suites easier to write, and more effective.

To illustrate this larger point, I want to draw your attention to a few aspects of my sample solution.

Firstly, because there is so much to test here, it made my life easier to split my test suite into multiple files. One which defines some variables and functions I make use of thought my test suite, and that includes a few very general tests, and then a separate file for the tests for each of the three prototypes. So, four .js files in total.

If you look at my QUnit test runner (test/index.html), you’ll see how easy it is to split up your tests – create the files, then import each into the test runner with a separate <script> tag:

While writing my test suite I quickly realised that I would need similar pieces of dummy data over and over again. Rather than re-defining that dummy data each time, I chose to build a data structure to store it, which I named DUMMY_DATA.

The DUMMY_DATA variable is a plain object where the names are short abbreviations that describe the piece of sample data, and the values are themselves plain objects. These inner plain objects each contain two name-value pairs, a textual description of the piece of sample data with the name desc, and the actual piece of sample data with the name val.

For example, DUMMY_DATA.num.desc is 'a number', and DUMMY_DATA.num.val is 42. Similarly, DUMMY_DATA.str.desc is 'a generic string', and DUMMY_DATA.str.val is 'boogers!'.

Here’s a snippet of the definition of this variable:

When I had this collection of sample data built up, I soon realised that a sub-set of that data was different to the rest – when testing argument validation I needed samples of each of the basic data types in JavaScript over and over again, and, I needed to be able to quickly check that the function throws an error on all the basic types except for the one or two that the function expects.

For example, the .hours() accessor function in the pbs.Time prototype should throw an error when given any basic type except a number or the special value undefined.

To make these basic type checks easier, I created another global variable named DUMMY_BASIC_TYPES with the exact same structure as DUMMY_DATA, but with fewer entries. Because the entries needed were the same, I copied them from DUMMY_DATA, hence the definition of DUMMY_BASIC_TYPES looks like this:

Note that DUMMY_DATA.str and DUMMY_BASIC_TYPES.str both contain references to the same plain object, which contains the two name-value pairs desc and val. I.e. DUMMY_DATA.str.val and DUMMY_BASIC_TYPES.str.val are both 'boogers!'.

Next, I added a helper function that will return the list of all basic types except those passed as arguments:

So, with these data structures and this helper function in place, I was able to save myself a lot of copying and pasting. To illustrate this point, let’s look at the tests for the data validation for hours in the pbs.Time prototype.

The first thing to note is that the prototype supports two ways to get an hour value into an instance of pbs.Time, the constructor, and the .hours() accessor. The same inputs should be accepted or rejected regardless of which route is used, so it makes sense to group the assertions for both together within the one test.

The logic of this test breaks down as follows – first name sure that the basic types that should throw an error do. In other words, if anything other than a number of the special value undefined gets passed, throw an error. Once those assertions have run, you have ruled out most of the possible invalid values, but not all. All valid hours are numbers, but not all numbers are valid hours, so the test next makes sure that hours that are not whole numbers throw an error. Next, the test checks that numbers outside the range of zero to twenty three throw errors, and finally, the test makes sure that valid whole numbers do not throw errors.

I particularly want to draw your attention to the first step in this process because I implemented it by calling the helper function and then looping through the returned types, testing that each type that should throw an error does indeed do so. Here’s the test in full:

Let’s look more closely at the loop at the start of the function.

Firstly, we use the dummyBasicTypesExcept() helper function to get a list of all basic types that should result in an error being thrown, i.e. all of them except undefined and a number:

Until we know how many basic types must throw, we can’t know how many assertions to expect, hence, this function call is made before the call to a.expect(), and the calculation of the value passed to a.expect() incorporates the length of the must_throw array:

We can now loop over the values in the must_throw array to check that both the constructor and the .hours() accessor do indeed throw an Error when passed each of the basic data types they should throw an error for:

The above snippet of code produces the following output when the test suite is run:

pbs.Time Hour Validation Partial Output

You’ll find this same basic approach used to test validation through all three of the prototypes.

Testing Cloning with assert.propEqual

To avoid bizarre spooky action at a distance errors, it’s very important to test that the .clone() instance function really does return a proper clone of the instance of the prototype it was called on, and not merely a reference to the object.

A proper clone has three distinctive characteristics:

  1. The clone is not a reference to the original object – i.e. the equality operators (== and ===) do not consider the original object and its clone to be equal.
  2. The clone has the prototype of the original object.
  3. Every value stored in the clone is the same as that stored in the original object.

We know how to easily test for non-equality (assert.notEqual() or assert.notStrictEqual()), and we can use assert.ok() in conjunction with the instanceof operator to test the clone’s prototype, but we have not yet met a good assertion for testing that the attribute values match. That’s precisely what assert.propEqual() is for. The assertion expects three arguments – two objects, and a description. If all the properties in both objects have the same value, the assertion passes. You can see this assertion in use in the test for the .clone() function in the pbs.Time prototype:

Callbacks & Hooks

QUnit allows you to specify custom code that will be executed when ever various events occur during the execution of a suite of tests. There are six main functions that each take an anonymous function/callback as the only argument:

QUnit.begin(callback)
The callback passed to this function will get executed once at the beginning of the execution of the test suite.
QUnit.done(callback)
The callback passed to this function will get executed once at the end of the execution of the test suite.
QUnit.moduleStart(callback)
The callback passed to this function will get executed each time the test suite starts processing a module.
QUnit.moduleDone(callback)
The callback passed to this function will get executed each time the test suite finishes processing a module.
QUnit.testStart(callback)
The callback passed to this function will get executed before each test in the test suite.
QUnit.testDone(callback)
The callback passed to this function will get executed each time the test suite finished processing a test.

When QUnit runs the callbacks it will pass them one argument, a plain object containing relevant details. You can see each of these callbacks in action by adding the following to one of your test suites – note that this will generate a lot of alerts, and will be very annoying!

In general, these callbacks are most useful when integrating QUnit with some kind of logging system. However, they do have other uses, so its good to know they exist.

In fact, my sample solution makes use of one of these callback functions – QUnit.testStart(). The two helper variables DUMMY_DATA and DUMMY_BASIC_TYPES are both defined in the global scope, but they are created without any contents:

The dummy data is defined, or rather re-defined, before every test because the values for both of these variables are set within the anonymous function passed to QUnit.testStart():

The reason for re-defining these variables before every test is to help ensure atomicity – if the code under test messes with an object passed as an argument, then all tests that run after that test will be working with altered data. By re-defining the variables after each test, we can be sure they are clean. Basically, we’re protecting ourselves from weird spooky action at a distance bugs.

As useful as these global callbacks are, note that the same code gets executed before every test, and before every module, you are not defining per-module actions.

The second argument to QUnit.module, the so-called hooks object, allows you to specify module-specific callbacks. The following four hook names are supported:

before
Executed once during each run of the test suite when processing of the module starts.
after
Executed once during each run of the test suite when processing of the module ends.
beforeEach
Executed before each test within the module.
afterEach
Executed after each test within the module.

Using the following as the second argument to QUnit.module() somewhere within your test suite will illustrate when these hooks get executed, again, this code will generate a lot of alerts and be very annoying!

Just a reminder that so far, in all our sample code, we’ve been passing an empty object ({}) as the second argument in all our calls to QUnit.module(). From now on you can pass as an object that defines as many or as few of the four possible hooks as you require – it’s not a case that you have to pass all the hooks or none of them, it’s fine to only pass one, or two, or three.

Note that QUnit ensures that the special this variable accessible within each of these four hooks is the same this variable that’s available within each test within the module, so, if you set this.x to some value within the before or beforeEach hooks, then you can access that variable from within any test within the module. This mechanism allows you to define some standard pieces of data which you can use in each of a set of related tests.

My sample test suite contains a number of examples of the use of these hooks, including the one below which shows the use of the before hook in a module containing the tests for the string generation functions in the pbs.Time prototype:

Notice that we declare four pbs.Time objects and save them into the special this variable within the before hook. We then use those four pbs.Time objects in the assertions within each of the four tests, accessing the objects via that special this variable. If the tests were to alter the objects, we should define them in the beforeEach hook instead of the before hook.

Using the Fixture to Test DOM-Manipulating Code

So far, we’ve been testing JavaScript code that doesn’t interact with the browser in any way. In other words, the code we’ve tested so far doesn’t interact with the DOM. QUnit can of course be used to test code that does interact with the DOM because it was created by the jQuery people to test jQuery, which is all about DOM manipulation!

The key to testing code that interacts with the DOM is the QUnit *fixture*. Every QUnit test runner page must contain an HTML element with the ID qunit-fixture. This is where you should add the HTML that the code you’re testing will interact with. What QUnit promises is that each time a new test starts, the fixture will have been restored to its original state. So, think if the fixture as a little sandbox that gets put back exactly as it was when the page loaded between each test finishing and the next one starting. Your tests can mess around with it as much as they want, but nothing they do will have any effect on future tests, because QUnit will have restored the fixture to its original state after ever test finishes.

Let’s illustrate the concept with a practical example – let’s make a start at writing some tests for the bartificer.linkToolkit API we developed earlier in the series.

You can find a copy of the code in this instalment’s ZIP file, or, you can download a copy from the API’s GitHub page. The code for the API is contained in the file bartificer.linkToolkit.js in the lib folder. We’ll add our test suite in a new folder which we’ll name test, which will contain two files – our QUnit test runner (index.html), and our QUnit tests (test.js).

We’ll start with a blank test.js, and a basic index.html that imports the API to be tested, the QUnit framework, and our currently empty test suite:

A key feature of this API is that it tries to classify links as being local or external. For our tests to work reliably we need to know where the test suite is running. The only solution I could come up with to address this requirement was to simply decree that the test suite must always be run from localhost.

To make this decree obvious, let’s start our test.js file with a callback that will be executed before the test suite runs that will complain if the test runner is running on any domain other than localhost:

You can verify that this callback works as expected by opening the HTML file directly in a browser so its URL starts with file:// and has no current domain. Then copy the test suite into your local web server’s document root, and access the file via a URL that starts with http://localhost/ – you should get an alert when you open the file directly, but not when you access the file via localhost.

The next thing we should add to our test suite is a simple test to make sure the namespace exists:

The most critical function within the API is bartificer.linkToolkit.isLocalUrl() – this function should correctly identify which URLs lead to a page on the same site as the current page, and which don’t. Since this function doesn’t interact with the DOM, we already know everything we need to implement some tests for it:

Notice that to save a lot of typing, and to make the code more readable, I created a local variable named isLocalUrl to store a reference to the function bartificer.linkToolkit.isLocalUrl. This means that the following two lines of code are effectively identical:

I made heavy use of the documentation for the function when designing these tests. In general, documentation describes how a given function or prototype should behave, so it makes a great reference when implementing test suites. You can find the documentation for bartificer.linkToolkit.isLocalUrl() on GitHub.

Next, let’s try write some tests for the bartificer.linkToolkit.noopenerFix() function (also documented on GitHub).

This function searches some or all of an HTML document for links to URLs that are not local that have a target of _blank, but who’s rel attribute doesn’t contain noopener, and adds noopener to the rel attribute. In other words, the function alters the DOM (by adding new rel attributes or altering the values of existing ones).

This means that, for the first time in our exploration of QUnit, we need to make use of the so-called fixture.

What should be put into our fixture? That decision is very much driven by what the code being tested does – in this case, our API is all about links, so we should create a nice selection of links with various attributes – some relative links, some absolute links to localhost, some to other sites, some with a target attribute specified, some without, some with a rel attribute specified, some without, and so on. We also need to give the links IDs so we can easily address them individually from within our tests.

In reality you’ll probably find that you continue to tweak your fixture as you write your tests. Below is the fixture I ended up with at the end of the process:

Given this fixture, here are my tests for the bartificer.linkToolkit.noopenerFix() function:

Remember that the fixture gets reset after every test, not after every assertion, so, each test starts by calling the function under test on the fixture. Again, the structure of my tests was very much dictated by the documentation for the function. First, I test the function without any options specified to check that its default behaviour is as expected, then I test each option listed in the documentation in turn, defining a separate test for each.

Also notice the use of jQuery within the various assertions to determine whether or not the DOM was altered as required.

The ZIP file for this assignment contains the test suite for this API up to this point.

Assignment

We’ve just just finished writing the tests for the isLocalUrl() and noopenerFix() functions. Either starting from scratch, or, using the code in this instalment’s ZIP file as a starting point, write tests for some more of the functions in the bartificer.linkToolkit API. I would suggest starting with the function markExternal().

Final Thoughts (And Two Book Recommendations)

We’ve now learned all we need to learn about QUnit, and we’re ready to return our focus to HTML forms and continuing to practice our JavaScript skills.

In the next instalment we’ll learn about HTML text input fields, and, we’ll make a start on a new, and I think fun and exciting, web app – we’re going to implement a seminal piece of computer science history – Conway’s Game of Life!

It’s going to take us quite a few instalments to build up this web app, but when complete our web app will contain both HTML forms and JavaScript APIs, unifying the two parallel tracks we’ve been on for some time now.

You don’t need to understand the historical or scientific context for Conway’s Game of Life to continue with the series. But, I think you’ll get a lot more out of the finished web app if you do. To that end, I want to recommend two books which together will provide a full and detailed context for the game of life:

  1. Chaos: Making a New Science, by James Gleick
  2. Complexity: The Emerging Science at the Edge of Order and Chaos by M. Mitchell Waldrop

These two books are by different authors, but they compliment each other perfectly, both having a similar narrative style where you learn about the science by following the researchers on their journeys of discovery – you get to see real people go from huh – that’s odd’ to I wonder what would happen if … through to aha!. Complexity picks up the story at pretty much the exact point in the story where Chaos finishes.