Unit Testing JavaScript methods that contain jQuery ajax calls

Objective

Unit test a JavaScript method which contains a $.ajax() call. Using QUnit.

Details

This was supposed to be a simple task, and if I didn’t have a few (now) obvious faults in my JavaScript code, it would have been completed more quickly. I have gone through several answering my own StackOverflow questions on the next day here’s the one in question for the curious ones.

I will hide behind the excuse of it being the early days of the new year and still finding my coding groove after almost two weeks on holiday…

So in this post I’ll summarise the two approaches I came out with in the end. It’s two because neither worked for me first time, and in my attempt to solve the first discovered the second. In the end resolving both. I won’t bother going into much detail about QUnit, as there are many posts out there about it; here, and here and here and official documentation here, and other interesting things to do with it.

As a quick aside we use the NuGet package NQUnit.NUnit to help us integrate QUnit into our Visual Studio projects.

Basic Approach

Solution 1 – basic way as is shown on this StackOverflow answer

// Arrange
    var options,
        jsonText = '{"id": "123", "fieldName": "fbs", "data": "fbs-text"}',

// Set up to 'capture' the ajax call (this forms the mock)
$.ajax = function (param) {
    options = param;
};

// Act - call the method which is 'under test'
/* ... */

// Call the success (or failure) method to complete the mock of handling of the 'response'
options.success(expectedData);

// Assert - verify state of system is as expected
/* ... */

Alternate Approach MockJax

Solution 2 – using the MockJax library with a great walk-through on how to use it here.

There are several advantages in using MockJax, that can be summarised as just having more control over mocking the ajax portion of the method under test, including but not limited to; timeouts, introducing latency, returning HTTP status codes.

After having included MockJax in your project, the solution 1 code gets replaced with 1 method call to $.mockjax() and looks like this.


// Arrange 
    var jsonText = '{"id": "123", "fieldName": "fbs", "data": "fbs-text"}';

// The call to mockjax replaces the need to overwrite the jQuery ajax() method
$.mockjax({
    url: '/Your/Regular/Action',
    dataType: 'json',
    contentType: 'application/json',
    responseText: jsonText
    }
});

// Act - call the method which is 'under test'
/* ... */

//perform test assert state of system is as expected
/* ... */

Demonstration

Full QUnit test code is up as a Gist.

Find a working copy of the code here in it’s simplest form: jsfiddle.net/NickJosevski/9ZZmc/4/

Advertisements

Using jQuery Templates to .appendTo() an <option> on a <select> list via .render()

I couldn’t find a good example that shows how to achieve this, so I thought I would quickly outline the process along with some “gotchas” I encountered.

First, an outline of the technology/components/elements I’m talking about:

  • Templates is the Microsoft proposed templating solution for jQuery.
  • This library can be obtained from github.
  • I want to add <options> on the <select> list.
  • I want to achieve this using the .render() method demonstrated on ScottGu‘s blog post on jQuery Templates.
  • In conjunction with using the .appendTo() method in jQuery.

The desired end result, outputting items into the select list via jQuery:
Select List

There’s actually several similar ways this can be achieved as can be seen on this StackOverflow question. I’ve put a summary of this post as an answer on that question also.

To add scope to this post, here is a quote from Scott Gu’s blog post on the purpose of the templating system.

Client-side templates enable jQuery developers to easily generate and render HTML UI on the client. Templates support a simple syntax that enables either developers or designers to declaratively specify the HTML they want to generate. Developers can then programmatically invoke the templates on the client, and pass JavaScript objects to them to make the content rendered completely data driven. These JavaScript objects can optionally be based on data retrieved from a server.

At this point I’m going forward on the assumption you now have a rough understanding of the purpose of templating so I can focus primarily on getting this to work with a <select> list.

The first step is to setup the appropriate template structure. In this scenario, it’s the <option> block with the ‘value’ and ‘text’ properties needing substitution. The syntax for the substitution variables is wrapped by the two opening curly-braces and an equal sign, it’s name then followed by 2 closing curly-braces. A note here as this is JavaScript performing the substitutions, it is in fact case sensitive.

<script id="templateOptionItem" type="text/html">
    <option value=\'{{= Value}}\'>{{= Text}}</option>
</script>

Zoom in, enhance!

Ensure you escape single quotes

Ensure you escape single quotes otherwise the templating render() action will fail.

The next step is to “fetch” your data (input data), in my real world example this comes back as JSON. But for now let’s just hard code the data array.

    function renderTest() {

        var someData = [
            { Text: "one", Value: "1" },
            { Text: "two", Value: "2" },
            { Text: "three", Value: "3"}];

        //on the template, apply the render with the data input, and then append to the html element.
        $("#templateOptionItem").render(someData).appendTo("#theSelectList");
    }

That last line with the .render() and .appendTo() is where the elegance lies, the set-up of reusable templates is extracted out of the actual call to map the data to the html elements. There are more features in the templating library, so check out this post for more examples.

The aim is to keep this post on the very narrow topic of just applying to a select list. So the actual implementation of the ajax-y request and response of JSON will come in a future post. The impact on the actual templating logic is trivial and limited to the what you pass to the .render() call.

Summary of the gothcas:

  • Escape your quotes (single and doubles).
  • The template must be in it’s own script block, not as a JavaScript var (string). Not sure why that is, I’m still investigating.
  • Ensure your selectors are working.
  • Ensure your output is wrapped in valid html elements, at the least a <div>.
  • Template place holders are case-sensitive.

OData, AtomPub and JSON

Continuing my mini-series of looking into OData I thought I would cover off the basic structure of AtomPub and JSON. They are both formats that OData can deliver the requested resources (a collection of entities; e.g. products or customers).

For the most part there isn’t much difference in terms of data volume returned by AtomPub vs JSON, tho AtomPub being XML, is slightly more verbose (tags and closing tags) and referencing namespaces via xmlns. A plus for AtomPub for your OData service is ability to define the datatype as you’ll see below via m:type the example being an integer Edm.Int32. Whereas the lack of such features is a plus in a different way for JSON – it’s simpler, and a language such as JavaScript interprets the values of basic types (string, int, bool, array, etc).

I’m not attempting to promote one over the other, just saying that each can serve a purpose. If you’re after posts that discuss this is a more critical fashion, have a look at this post by Joe Gregorio.

What I do aim to show is that comparing the two side by side there’s only a slight difference, and based on what you’re intending to accomplish with processing said data the choice for format is up to you. If you’re just re-purposing some data on a web interface JSON would be a suitable choice. If you’re processing the data within another service first, making use of XDocument (C#.NET) would seem suitable.

There’s also a concept of ‘Deferred Content’ for both formats and it is achieved in a similar way through links. The objective being to conserve resources in processing and transmission by not transmitting the entire element tree on a request. In the comparisons below where there is a link to another URI that is content that has not been returned, the most obvious example is image data i.e. links to jpeg resrouces. OData has a URI command option called $expand that can force the inline return of the element data (this concept is called eager-loading). Have a look at my introductory post about the OData query options.

NOTE: In the examples that follow the returned result data is from the NetFlix OData service, I have stripped out some of the xmlns, and shortened/modified the urls in particular omitting http:// just so it fits better (less line wrapping).

So let us compare…

AtomPub
Yes that stuff that’s makes up web feeds.

Example from the NetFlix OData feed access via URL http://odata.netflix.com/Catalog/Titles

Atom Feed

<?xml version="1.0" encoding="iso-8859-1" standalone="yes"?>
<feed allThatOtherNameSpaceStuff="">
  <title type="text">Titles</title>
  <id>http://odata.netflix.com/Catalog/Titles/</id>
  <entry m:etag="abced">
    <id>http://odata.netflix.com/Catalog/Titles('movieName')</id>
    <title type="text">FullMovieTitle</title>
    <summary type="html">Your everyday regular movie</summary>
    <allTheOtherTags type="text">...</allTheOtherTags>
    <m:properties xmlns:m="severalNameSpaces">
      <d:Id>movieName</d:Id>
      <d:Synopsis>Your everyday regular movie</d:Synopsis>
      <d:Runtime m:type="Edm.Int32">3600</d:Runtime>
      <d:BoxArt m:type="NetflixModel.BoxArt">
          <d:SmallUrl>http://c.dn/boxshots/m1bx.jpg</d:SmallUrl>
      </d:BoxArt>
    </m:properties>
  </entry>
</feed>

JSON
Yes that simple text used in JavaScript.

Example from the NetFlix OData feed access via URL http://odata.netflix.com/Catalog/Titles?$format=JSON

Javascript Object Notation

{ 
  "d" : 
  { 
    "results": [ { 
      "__metadata": { 
        "uri": "o.ntf.lx/Ctlog/Titles('movieName')", 
        "etag": "abcdef", 
        "type": "NetflixModel.Title", 
        "edit_media": "o.ntf.lx/Ctlog/Titles('mvName')/$value", 
        "media_src": "c.dn/boxshots/large/mnbx.jpg", 
        "content_type": "image/jpeg", 
      },
      "Id": "movieName", 
      "Synopsis": "Your everyday regular movie"
      "Runtime": 3600
      "BoxArt": { 
        "__metadata": { 
            "type": "NetflixModel.BoxArt" }, 
            "SmallUrl": "http://c.dn/boxshots/m1bx.jpg"
        }
    } ]
  }
}