Tinned Fruit

Futuristic progressive enhancement talk

2012-02-03T00:00:00+00:00

Drew (The Voice) Neil and myself were invited to talk about our contrasting views on progressive enhancement at Refresh Edinburgh this week. It was my privilege to defend progressive enhancement’s honour with a talk about why it is still a relevant approach, and how it fits in to the current reality of device variety, fragmented support, and constant innovation. You can watch the video, see the slides on Speaker Deck or grab a PDF of the slides with notes (22.8Mb download).

Your mobile mileage may vary

2012-01-11T00:00:00+00:00

If 2012 is definitely, finally, absolutely going to be the year that mobile web takes off, then it seems to have made a good start, with lots of people talking about buying physical devices for testing. All this was started by Peter Paul Koch’s excellent summary on A List Apart and Stephanie Rieger’s timely reminder that mobile device emulators are no match for testing on real devices, illustrated by Mr. Obama’s magical disappearing navigation. This prompted me to ask for shopping advice on the Yahoo Mobile Web group, which in turn inspired Brad Frost to post a very handy breakdown of some suggested devices on his blog.

Brad’s list is great, but conversations on Twitter, Bagcheck lists and Stuart Robson’s newly forged Tumblr show that everyone’s test device collection is different. What is suitable for you will depend on the projects you work on and their intended audience.

Do your own research

Before you jump in and buy an arbitrarily list of devices, take some time to find out what your target audience are using. Check your own site analytics, look at the StatCounter figures for the relevant regions, and see if there is other geographically focused research available. For example, in the UK, Tecmark publish some figures about mobile web twice yearly.

As an example of regional differences, compare StatCounter’s figures for BlackBerry market share in the US (8%) and the UK (32%) for October to December 2011. You might decide that, for a UK audience, it is more important to test with BlackBerry devices than a site which is primarily aimed at the US market. On the other hand, the latest Tecmark report (PDF link) for the UK indicates that BlackBerry devices are only responsible for 3.5% of mobile web traffic, and around 0.5% of all web traffic, belying their apparent market share.

A little more digging around will give you some rough figures for penetration of individual OS versions, which is also useful in understanding which test devices will be representative. For example, here is a breakdown of BlackBerry subscribers by OS version as of August 2011. Google Analytics will give you a breakdown of OS version usage figures for Android and Windows Phone (but not other platforms), and there are some handy up-to-date global figures on the Android developer site. iOS version penetration figures are harder to come by as Apple don’t publish figures themselves, but Chitika do publish occasional iOS version penetration stats, although their methodology is not clear.

Finding out about devices

Market share and analytics will start to give you an idea of where you need to focus your testing efforts. However, it is all very well getting an idea of which OS versions and platforms are likely to be used to access your site. Unless you know the mobile device market inside out, you won’t know which phones run which exact version of OS, and at what point in the version history significant changes where made to the built-in browser.

Fortunately, much of this knowledge is available too, in various places:

DeviceAtlas has a very handy tool for filtering devices based on various properties, including OS version, form factor, and even feature support. This will allow you to see which HTC devices run Android 2.2 with a 320 x 240 screen, for example, although the data is not always fully complete and up to date.
I also find Wikipedia to be pretty detailed and as well as the usual specifications, device pages contain information about when and where devices were marketed, predecessor and successor models, model variations and other esoteric information that is hard to find elsewhere.
The device manufacturers themselves have varying degrees of info. Nokia’s developer site has a particularly good model breakdown, for example. I won’t name names, but some other manufacturers’ sites are, well, not so good.
When Can I Use and PPK’s Quirksmode both have browser capability charts so you can see which phones are likely to support which fancy new HTML5 API.

Shopping

This is one for those based in the UK.

We are fortunate enough to have an extremely fluid second-hand mobile market in the UK. There are many unlocked phones, and pay-as-you-go data-only SIMs can be obtained from providers like GiffGaff for free if you need them.

Buying second phones here is pretty easy, and not that expensive, especially when looking for older models. January is also a great time to buy as people are offloading their old phones after Christmas, so prices go down by about 10-20%.

Because of this, eBay is chock full of phones to buy, and with the new pricing trends tools is a pretty handy research tool in its own right. Hours can be lost.

There are also the dedicated second-hand shops such as I Need a Mobile, who sell phones according to a quality grade, tend to be a bit more expensive than the eBay going rate, and don’t provide chargers.

It’s worth taking a look at the high street shops, such as Carphone Warehouse, just to see if there are any special deals on newer sim-free phones, and to get an idea on pricing. Finally, there are the classified ad sites such as Preloved and GumTree, both of which have plenty of second hand listings.

Conclusion

If you want to boost your mobile and responsive web design testing process, then real devices will make a big difference, not only for catching bugs, but to gain exposure to different design approaches, input methods and form factors. It pays to spend some time researching what would make a representative collection of devices that reflects your target audience, but also appropriately samples from these variations.

Massive disclaimer

I’m new to all this myself. I recently started focusing more on mobile web development, and I have never been a huge mobile phone fanatic in the past. Until recently, my own collection was limited to an iPhone 3GS and an old Nokia 3210 that I found at the bottom of a drawer. Please, comment if you have anything to add.

Edinburgh International Book Festival mobile site

2011-09-08T00:00:00+01:00

Having seen my efforts at the Culture Hack Scotland event in May, I was approached by the nice people at the Edinburgh International Book Festival to create an official mobile application for the event, which took place last month.

The final website can be seen at m.edbookfest.co.uk.

We decided that a mobile web site would serve the Book Festival’s needs better than would native applications. Here’s why we came to that decision, and how building an interactive and responsive mobile website need not be as huge a departure from traditional web development as you might think.

Why a mobile website?

In the very first meeting with Andrew Coulton from the festival, we discussed whether it would be better to develop native applications for specific smartphones, or to create a mobile web site. The goal of the app was to provide event listings, information about the authors appearing at the events, and the opportunity to purchase books and e-books through affiliate links to Amazon and iTunes.

The decision to develop a mobile website was influenced by a number of things, not least that my own background is in developing websites. This obvious bias aside, there were still plenty of compelling reasons to choose the web approach for the festival.

No app stores

Firstly, as an application for a specific event, there was a hard deadline of the start of the festival. The last thing we wanted was to have the launch delayed while awaiting approval from app stores. Website hosting and deployment (using Heroku) were entirely under our own control and publication was not subject to approval from a third party platform provider.

This meant that two or three releases were possible during the festival to fix some bugs, with a very quick turnaround that would not have been possible with native applications.

The problem of discoverability

Many mobile web applications can suffer from a lack of discoverability. Where app stores provide a single, searchable, centralised directory for native applications, there is no single directory for mobile web applications, although such things do exist.

However, this is really only a problem for applications that have a broad and varied target audience, such as games and to do lists (and yes, fart apps).

For a mobile website, it is largely up to the site provider to promote and market their own content through appropriate channels, as is the case for any website. For the Book Festival, we knew that we would have a ready-made engaged audience – the festival-goers themselves. We would also have some marketing channels to target this audience, including the physical festival site, the existing desktop website and the festival Twitter account, each which could publicise and link to the mobile site in its own way.

So, for a specific, targeted and already engaged audience, discoverability becomes far less of an issue. Both native and web applications would have to be promoted in channels targeted to your audience in similar ways, as no global app store is able to target niche users in this way. Discovering a niche application about a specific event through all the noise of highly popular games and gimmicks is not easy.

Interactive phone features

Some smartphone features can only be accessed via native APIs that are not as yet accessible to mobile web browsers, including cameras, microphones, telephony and so on. If you are creating an app that needs to access these features, then a native app is the way to go for now until broad browser support is available.

However, many content providers will simply not have any need to use these features. As part of our decision making process, we brainstormed a number of ideas for the application and found that there were none that could not be executed via existing browser technologies.

For example, one idea that did not make it to the final site was the ability to have an author ‘sign’ your smartphone and send the signature image to an email address. This is entirely possible using the HTML5 canvas element, a cross-platform JavaScript library for touch events, and some server-side code to handle sending the email. It is important to have an understanding of how each proposed feature would be supported, even if that feature doesn’t make the first cut of the application.

Device support

The native app approach requires that the developer either create custom apps for each target platform, or uses tools such as PhoneGap to build so-called ‘hybrid’ apps - essentially native applications developed using HTML, CSS, JavaScript and a toolkit that provides access to native APIs.

However, it is platform and the ubiquity of web browsers that makes the web universal, not the technologies that are used to build it. Hybrid apps are distributed and marketed just like other native apps, and so are not intrinsically cross-platform. There is also the chance that APIs will change or new devices will emerge, bringing further problems of interoperability.

Building a website using agreed web standards and with techniques such as progressive enhancement gives access, in principal, to anyone using a phone with a web browser. The devil here is in the details of browser support and designing a responsive interface to work across a broad spectrum of devices, screen dimensions, interaction capabilities and network performance. As for any website, the devices and browsers you develop for depends on the audience being targeted. Bryan Rieger provides an excellent dissection of the challenges of cross-device mobile web development.

In the case of the Edinburgh Book Festival site, statistics suggest that UK mobile internet use is dominated by the iPhone, iPad, Android devices and Blackberries, with around 5-6% remaining for other devices, even if other statistics suggest these devices do not have as high an overall penetration as you might expect.

Libraries and frameworks

The explosion of tools, libraries and frameworks for mobile web development in recent years means that it is easier than ever to get a head start in mobile web development and minimise time spent ensuring the site works across a wide range of devices.

It is increasingly the case that many of the modern smartphones are using similar browser technologies – the WebKit rendering engine powers Mobile Safari for iOS, the Android browser, and the Blackberry browser. An experimental WebKit-based browser is even shipped with the Amazon Kindle. Many libraries and frameworks are beginning to target WebKit alone, with some superficial support for other browsers.

However, the danger here is that, depending on your target audience, you lock out users of other browsers. Other browsers are popular in other audiences, not least Opera Mini. Again, this can be largely avoided by starting with a simple design, a fully operational website, and then layering on enhanced features progressively.

Design and development

Agile methods

Throughout the design and development of the site, I worked within two-week iteration cycles, with regular deployments to a staging environment, allowing frequent reviews by stakeholders at the festival. All code was written with a test-driven approach using tools such as Cucumber, Capybara, RSpec and Jasmine BDD.

All features were planned in advance using story cards that were agreed and prioritised. This allowed us to keep in touch with what exactly would be delivered in time for the start of the festival, given a fairly rigid budget and timescale. Inevitably not all the ideas could be implemented for this year’s festival, but with any luck we’ll be adding features in future years.

The overall effect of this was that I was able to spread the work of developing the site evenly over a period of 2-3 months, with 3 hours work a day in addition to my day-to-day work. Deployment had been continuous, so there were no nerves about the final deployment the night before the festival as there would have been with a Big Launch approach.

Design - keeping it simple

Time and time again during the design and development of the site I found myself up against the constraints of designing for mobile devices. Far from being restrictive, these challenging constraints can be the fuel for innovation and creativity. For example, limited screen real estate forces a focus on supporting the primary user task at hand and the continual stripping away of unnecessary fluff.

In native applications, this has resulted in some clever interactions that make the most of multi-touch, gestures and accelerometer motions to move features off screen but retain their availability. Some of these have become almost conventional, such as pulling the screen down to refresh a timeline feed.

I was initially tempted to introduce some touch interactions to the interface, but soon realised that this would have been a mistake.

Firstly, anything beyond the simplest touch interaction is complex to implement across different devices, and the JavaScript touch libraries that are available can be rather heavy. The interactions themselves are usually not as smooth as they are for native applications.

Secondly, I expected that few people would discover them – users are consciously using a mobile-optimised website and not a native application, so it is unlikely that they would expect complex touch gestures.

Instead I aimed to create a design that would be as responsive and simple as possible based on simple single touch interactions. The key here was fast page transitions and optimised performance.

Framework choice

The mobile web development landscape is now well populated with JavaScript frameworks that allow for rapid development of single-page, touch-optimised web applications. I have spent some time experimenting with these, including jQuery Mobile, jqTouch and Sencha Touch.

To my mind, all three frameworks are attempting to ape the native experience too closely – and not always successfully – with some jerky animations, mis-positioned elements and some performance issues. We didn’t want to create a native app experience, but a simple mobile-optimised website with a responsive feel.

I decided therefore to develop the site without the aid of an all-encompassing framework, but instead layer on richer functionality for more capable devices as and when it was appropriate. There are now a number of small, modular JavaScript libraries that aim to fill specific needs for mobile devices that can be cherry-picked as needed. Two such examples are Zepto.js and XUI.

A website is a website is a website

We were making a mobile optimised website, so we decided it should behave much like a website, and work within the confines of a mobile web browser. The back button should work, links should behave like links and most importantly, it should continue to provide a web experience for phones without touch interactions.

At the same time, we wanted smartphones with fast JavaScript engines to enjoy a ‘single-page’ experience with Ajax loading of content to improve perceived performance. This is a classic use-case for progressive enhancement. All the links in the website point to full URLs, and so work fine without JavaScript enabled. However, for smartphones, link activations are intercepted using JavaScript and the target content is loaded with Ajax and injected into the existing page. This means that only body content is loaded and re-drawn for each page, giving the site a more responsive app-like feel.

However, the browser address bar is still updated as the user navigates around, allowing for favourites to be set, deep links to be emailed, tweeted and bookmarked. A simple but effective example of the importance of this was demonstrating during the festival by the use of deep links in tweets from the official Book Festival twitter account to link to specific day listings and events. Another feature that was explored but not implemented was the use of QR codes around the physical festival site to allow deep linking into specific event, author or book pages.

The ‘single-page’ style of navigation was achieved using a simple combination of the Zepto.js mobile-optimised JavaScript library and a modified version of Pjax - another small library that uses the HTML5 history API and Ajax to load and inject content. The back-end Ruby on Rails application is modified to respond with only the page body content when a Pjax request is made, but with the full HTML document for all other requests.

Boilerplates

Another tool that I found useful to kick start the development process was HTML5 Mobile Boilerplate. Based on the HTML5 Boilerplate, it provides HTML, CSS and JavaScript starting files with commonly used code and conventions specific to mobile-optimised sites. The golden rule is to critically evaluate everything that is provided, understand what it is for, decide whether it is necessary in the context of your own project and remove it if it is not relevant.

For example, in the case of the Book Festival site, I eventually removed the reference to Modernizr, which detects browser features and allows the developer to progressively enhance based on support for specific browser capabilities. I just wasn’t using it for anything important, and so the bandwidth savings gained from removing it trumped any minor issues that it might have helped fix.

Open source FTW

As part of the project, all source code has been released under a GNU General Public License on Github. Feel free to fork it and play around. The Book Festival are planning on opening up listings data in the future, but access can currently be requested on a case-by-case basis. See the README on Github for more information.

Thank you

This project would not have been possible without the support of the Edinburgh Festivals Innovation Lab, and in particular I would like to thank Rohan Gunatillake and Ben Werdmuller for organising Culture Hack Scotland and providing excellent motivational impetus. One of the goals of the hack day was to foster co-operation and partnerships between the cultural sector and independent developers, and I’m very glad to have been part of an example of that working successfully and producing something with a far wider output that just a fun hack.

Secondly thanks to everyone at the Edinburgh International Book Festival, and in particular Andrew Coulton, who despite being phenomenally busy in the run-up to the festival found time to provide detailed and helpful feedback and support.

Culture Hack Scotland 2011

2011-05-10T00:00:00+01:00

Last weekend I attended Culture Hack Scotland, a fantastic hack day organised by the fine people at festivalslab. The range of data available was impressive, and the quality of the work produced by those attending was phenomenal. Congratulations to Rohan Gunatillake and Ben Werdmuller for a superb event.

For my own hack, I decided to focus on the Edinburgh International Book Festival, which I thought might be neglected somewhat given the richness of the Edinburgh Fringe data available, and the fact that it didn’t have its own dedicated data sets. I wanted to produce a resource for people such as myself who seem to be afflicted by a gnawing insecurity of their own cultural viability. I greatly enjoy books, but I am by no means literary. I read plenty, but I don’t take a great interest in the authors themselves. When attending a book event, the author becomes the centre of focus, and so I wanted to produce a tool that would help attendees discover more about the creators of the books that they have been enjoying.

The result of this is BookFest, a mobile application for discovering more about the authors at The Edinburgh International Book Festival. The code is available for mockery, forkery and hackery on GitHub.

Data sources

The listings data for the Book Festival are taken from the 2010 Festival Listings API created by Ben Werdmuller specifically for Culture Hack Scotland. festivalslab are planning on having a live API for the 2011 festivals which I am very much looking forward to.

The listings API provides only event titles and descriptions and does not provide a specific field for authors, so the Google Books Search API was used to get matching books based on the event title, and a list of unique authors of these books was collated. I then removed any authors that don’t appear in the title. This works pretty well for finding the actual authors for an event.

Once I had authors, I could then query the Google Books API again for a proper bibliography. I was hoping to be able to show Google Books previews inline in the app, but there simply are not that many available.

The rest of the hack was spent adding value, and yes, gimmicks. I used the Guardian Open Platform API to pull Guardian articles relating to or written by the author, added the inevitable Twitter search, and grabbed photos of the author from the Google Image Search API. The reason for the latter feature should be clear - few people really know what a particular author actually looks like. One weakness with this approach is that a search for David Mitchell finds a lot of pictures of TV's David Mitchell, and very few of the David Mitchell that wrote Cloud Atlas and other brain-melting fiction stonkers.

My favourite feature of all is the signature facility. If you have forgotten to bring a book by the author and do not wish to buy another copy at the festival book store, you can simply ask them to scribble on your touch-enabled device. For this I used the demo of the Interact JavaScript library that consolidates mouse and touch events for different devices. Of course, this feature is ridiculous as there is really no way to get the signature where it should be - in a copy of the author’s book. For that, we will have to settle for Margaret Atwood’s LongPen device.

Technologies

The app is hosted on Heroku, and uses the Sinatra Ruby framework on the back-end. This uses the rest-client and google-book gems for making API requests. On the front end I have used jQuery Mobile, which provides a decent mobile-style UI framework and an Ajax page model to give the website a more native application feel. jQuery Mobile is still in alpha, and so some of the rendering and animation feels a little unfinished at the moment, but overall it’s useful for getting something working very quickly.

Check out BookFest at http://bookfest.heroku.com

Testing Backbone applications with Jasmine and Sinon – Part 3. Routers and Views

2011-04-26T00:00:00+01:00

Overview

This is the third and final part in a series of articles demonstrating how to test a Backbone.js application, employing the Jasmine BDD test framework and the Sinon.JS spying, stubbing and mocking library If you haven’t yet read the first or second parts, take a look now.

In this final part, we’ll be looking at some methods for unit testing Backbone routers and views. These object types both present their own unique challenges for testing, but Jasmine BDD and Sinon.JS provide the tools we need to isolate them and fake external code and system dependencies. We will be examining the following:

different approaches to testing Backbone routes
methods for testing view rendering
using DOM fixtures in your specs
using the jasmine-jquery plugin
testing view event handlers
using fake timers to manipulate timed events

Routers

Backbone.js router objects are responsible for URL hash routing within your application, and can also be used for initialisation tasks if that’s how you choose to structure your code.

When a URL route is matched in your application, Backbone calls the router method associated with the route. It also triggers a route event in the form route:[action] where action is the name of your method.

Whether you use a router method or set up event handlers to bind to the route event is up to you. I have had some success using event handlers for routes, as you can then delegate behaviour to the specific objects in the application that need to respond. Single route methods can become monolithic and difficult to test in large applications.

For this example, however, we’ll use simple route methods. Our approach will be to test two aspects of the router: firstly we’ll test the route URLs themselves to make sure a particular URL will fire a particular route method; and secondly we’ll look at directly testing router methods.

Example 1: Testing routes

Our todo application will be driven by routes. When a user navigates to the home page for the first time, we want to display their to do list. In our code, the steps required are as follows:

The AppRouter responds to the home page route (represented by an empty hash)
The home route method instantiates a TodoListView and a Todos collection (created in part 2 of this article).
The Todos collection is asked to fetch its contents from the server.
When this response is received, the TodoListView renders the list.
The rendering of each individual Todo item is delegated to new instances of a TodoView object.

That’s quite a lot of code to test. The router is responsible for the first three of these steps. Firstly we’ll look at how to test whether a router responds correctly to a particular URL. This could potentially be tricky, as the Backbone.js routing system responds to changes in the browser address field. It might be possible to directly manipulate the browser address, but Backbone 0.5 and above provides a navigate method on router objects that can be used to simulate a URL change.

Normally in an application you would instantiate a router once per page load, and run Backbone.history.start() to start Backbone’s route listening. However, Backbone will only allow you to run Backbone.history.start() once for each page load. Running it a second time will result in an error being thrown.

The simplest way around this is to wrap the call to Backbone.history.start() in a try/catch block.

Here’s a spec:

`AppRoutes.spec.js`:

describe("AppRouter routes", function() {
  beforeEach(function() {
    this.router = new AppRouter;
    this.routeSpy = sinon.spy();
    try {
      Backbone.history.start({silent:true, pushState:true});
    } catch(e) {}
    this.router.navigate("elsewhere");
  });
  
  it("fires the index route with a blank hash", function() {
    this.router.bind("route:index", this.routeSpy);
    this.router.navigate("", true);
    expect(this.routeSpy).toHaveBeenCalledOnce();
    expect(this.routeSpy).toHaveBeenCalledWith();
  });
});

The spec binds the route:index event to an anonymous Sinon.JS spy function, allowing us to track whether and how it was called. We then ensure that the URL fragment has the value we want to test, in this case, an empty value. Calling Backbone.history.start() would normally trigger an initial Backbone.js routing check. However, by passing an option hash that includes silent: true we avoid the immediate route match. Note that we are also optionally using HTML5 pushState for browsers that support it.

The example itself triggers the route matching by calling the navigate method on the router with the URL fragment as the first argument. If a truthy second argument is passed, Backbone will also call any matching route methods and trigger route events.

To ensure that the route method and event is always fired, we navigate away somewhere else silently during the setup phase, just to ensure that the URL fragments are different.

Once the routing check has been performed, we expect that our route spy has been called once, and that it has been called with no arguments, as there will be no parameters associated with the home route.

When the example is run, we get an expected error:

ReferenceError: AppRouter is not defined

Let’s fix this by creating our AppRouter. Don’t forget to include it in jasmine.yml if necessary:

`AppRouter.js`:

var AppRouter = Backbone.Router.extend();

Running the specs again produces the following error:

TypeError: Cannot call method 'navigate' of undefined

Hmm, for some reason Backbone.history is undefined, and so there is no navigate method on it. It turns out that Backbone.js creates an instance of Backbone.History (upper case ‘H’) called Backbone.history (lower case ‘h’) once a router has been created that has at least one route specified on it. This makes sense, as history management is only required if there are routes to respond to.

We can now create our route:

`AppRouter.js`:

var AppRouter = Backbone.Router.extend({

  routes: {
    "": "index"
  },
  
  index: function() {}
  
});

and our spec passes.

Now that our index route is being tested successfully, lets try the todo detail route. At some point, we’ll want to show the user details of a particular to do item. For example, some notes, tags and scheduling information might be displayed. The URL fragment for showing this detailed view would be todo/1 for a Todo with an id of 1. Let’s write a spec to test that our router handles this successfully.

`AppRoutes.spec.js`:

it("fires the todo detail route", function() {
  this.router.bind('route:todo', this.routeSpy);
  this.router.navigate("todo/1", true);
  expect(this.routeSpy).toHaveBeenCalledOnce();
  expect(this.routeSpy).toHaveBeenCalledWith("1");
});

This spec is very similar to the one for the home route, but we are now binding a spy to the route:todo event and testing that the routeSpy is called with the id parameter from the URL.

This fails with the following messages:

Expected Function to have been called once.
Expected Function to have been called with '1'.

This is exactly what we were expecting. Now let’s create the route:

`AppRouter.js`:

var AppRouter = Backbone.Router.extend({

  routes: {
    "": "index",
    "todo/:id": "todo"
  },
  
  index: function() {},
  todo: function(id) {}
  
});

And again, we’re green. Simply by adding the route to the hash and creating an empty callback ensures that the route:todo event is fired when the URL hash matches.

We could enhance these specs by ensuring that only numerical values are valid for the id, and we could also check that our route methods are actually called by wrapping them with a Sinon.JS spy.

Now that we have some routes, we need to test that our route methods are behaving as they should be.

Example 2: Testing router methods

Once we have tested that the correct routes are actually being fired, we can test route methods simply by calling them. To test our index method, we need to ensure that it instantiates a TodoListView and a Todos collection in the correct way. We’ll need to create fake objects for both.

`AppRouter.spec.js`:

describe("AppRouter", function() {

  beforeEach(function() {
    this.router = new AppRouter();
    this.collection = new Backbone.Collection();
    this.todoListViewStub = sinon.stub(window, "TodoListView")
      .returns(new Backbone.View());
    this.todosCollectionStub = sinon.stub(window, "Todos")
      .returns(this.collection);
  });
  
  afterEach(function() {
    window.TodoListView.restore();
    window.Todos.restore();
  });

});

First we create our router instance for testing. We then create a bare Backbone.js Collection object to act as the Todos collection that will be returned when we stub out its constructor function. Finally, we create Sinon.JS stubs for both the TodoListView constructor and the Todos collection constructor, returning a new Backbone.js View and our bare collection respectively.

Now to write the specs:

`AppRouter.spec.js`:

describe("Index handler", function() {

  describe("when no Todo list exists", function() {
      
    beforeEach(function() {
      this.router.index();
    });
    
    it("creates a Todo list collection", function() {
      expect(this.todosCollectionStub)
        .toHaveBeenCalledOnce();
      expect(this.todosCollectionStub)  
        .toHaveBeenCalledWithExactly();
    });
    
    it("creates a Todo list view", function() {
      expect(this.todoListViewStub)
        .toHaveBeenCalledOnce();
      expect(this.todoListViewStub)
        .toHaveBeenCalledWith({
          collection: this.collection
        });
    });
    
  });
  
});

Before each spec, we call our index method for testing.

In the first spec we check that the Todos collection constructor has been called exactly once, and that it was called with no arguments.

In the second spec, we check that the TodoListView constructor was also called once, and that it was called with a hash object containing our stubbed collection instance. In this way we are testing that the application is linking the TodoListView with its data source, the Todos collection.

When these specs run, we get four failures:

creates a Todo list collection
  Expected Function to have been called once.
  Expected Function to have been called with exactly.

creates a Todo list view
  Expected Function to have been called once
  Expected Function to have been called with ...

So, let’s write the code to make these pass:

`AppRouter.js`:

var AppRouter = Backbone.Router.extend({
  
  ...
  
  index: function() {
    this.todos = new Todos();
    this.todosView = new TodoListView({
      collection: this.todos
    });
  }
  
});

Simple. We now need to test that collection’s data is fetched when the index route is run. This is done by simply calling the Todos collection’s fetch method. Let’s write another spec.

First, we need to stub the collection’s fetch method so that it performs no action, but allows us to spy on it. We add the following line to our beforeEach method just after creating this.collection:

`AppRouter.spec.js`:

describe("AppRouter", function() {
    
  beforeEach(function() {
    ...
    this.collection = new Backbone.Collection();
    this.fetchStub = sinon.stub(this.collection, "fetch")
      .returns(null);
    ...
  });
  
  ...
  
});

We can then add our new spec after the previous two:

it("fetches the Todo list from the server", function() {
  expect(this.fetchStub).toHaveBeenCalledOnce();
  expect(this.fetchStub).toHaveBeenCalledWith();
});

This fails as expected:

fetches the Todo list from the server
  Expected Function to have been called once.
  Expected Function to have been called with.

And making the spec pass is simple:

`AppRouter.js`:

var AppRouter = Backbone.Router.extend({
  
  ...
  
  index: function() {
    this.todos = new Todos();
    this.todosView = new TodoListView({
      collection: this.todos
    });
    this.todos.fetch();
  }
  
});

Our examples so far have been simple. You can see that routers can easily create a lot of other objects, and then call methods on those objects in order to get things rolling in your application.

If you are instantiating your initial application objects like this in your routers, then you’ll be creating a lot of stubs and mocks in your router specs. This is a matter of application design. For simple applications it is probably not a big issue, but this approach soon gets unwieldy.

An alternative approach is to instantiate any initial Backbone.js objects in an overall application initialisation method that is run when the page is first loaded, for example in a DOM ready handler. The router would also be instantiated and Backbone.js’s history object initialised at this point. The primary application objects that you have created (usually the views) can then bind and unbind to the built-in Backbone.js route events as required within their own code. In this way you are effectively delegating responsibility to the individual application objects so they are in charge of their own destiny. The outcome of this is code that is easier to test, and easier to maintain. If your specs become unwieldy, long and difficult to set up, then this is often a code smell suggesting that you should probably simplify or refactor your code.

Looking back to the top of example 1, we can see that we have now tested the first three steps required to render our to do list. The last two steps are the responsibility of two views: the TodoListView and the TodoView. Let’s take a look at testing views, then.

Views

Because our app uses jQuery for DOM manipulation, it makes some sense to use jQuery to test the rendered elements that our views will produce. Fortunately there is a Jasmine BDD jQuery plugin specifically for this purpose. The plugin provides two key features: firstly there are a number of Jasmine matchers to test jQuery wrapped sets and elements and secondly, it provides the ability to create temporary HTML fixtures for your specs to use.

To use the plugin, just include the jasmine-jquery.js file in your jasmine.yml or SpecRunner.html.

Example 1: Creating the root element

In our first view example, we’ll create a simple spec to check that our TodoListView has created the expected element when it is initialised. Backbone.js views will create an empty DOM element as soon as they are initialised, but this element will not be attached to the visible DOM. This allows a view to be constructed without unduly affecting rendering performance.

Our spec is pretty simple:

`TodoListView.spec.js`:

describe("TodoListView", function() {
  
  beforeEach(function() {
    this.view = new TodoListView();
  });
  
  describe("Instantiation", function() {
    
    it("should create a list element", function() {
      expect(this.view.el.nodeName).toEqual("UL");
    });
    
  });
  
});

Running this spec produces the following failure:

Expected 'DIV' to equal 'UL'.

We can fix this easily in our TodoListView.js by specifying the built-in Backbone.js tagName property for the view:

`TodoListView.js`:

var TodoListView = Backbone.View.extend({
  tagName: "ul"
});

Let’s also check that the element has the right class:

`TodoListView.spec.js`:

it("should have a class of 'todos'", function() {
  expect($(this.view.el)).toHaveClass('todos');
});

This uses the toHaveClass matcher created by the jasmine-jquery plugin which operates on jQuery objects. If we had not used the plugin, the expectation would have looked something like this:

expect($(this.view.el).hasClass('todos')).toBeTruthy();

which would produce a failure output like this:

Expected false to be truthy.

This is not very helpful for debugging purposes. Using the jasmine-jquery matcher produces this failure:

Expected '<ul></ul>' to have class 'todos'.

Again, we can easily fix this with a simple className property on the view object.

`TodoListView.js`:

var TodoListView = Backbone.View.extend({
  tagName: "ul",
  className: "todos"
});

Let’s move on to testing the actual rendering of our to do list content.

Example 2: Rendering

When we ask our to do list to render, it will create a task entry for each instance of a Todo model in the Todos collection. Each one of these tasks is a view instance with a reference to the model that will be rendered.

So, when the TodoListView’s render() method is called, we want to test that a TodoView is instantiated for each model in the associated collection.

Once again, because we are not currently testing the TodoView object, we will stub it with a basic Backbone.js view. As discussed in part 2 of this series, I find that this is by far the easiest way to isolate a Backbone.js object from other Backbone.js objects in your specs without resorting to mocking and stubbing the whole Backbone.js interface.

We create a basic Backbone.js view to stand in for the TodoView, and then stub the TodoView constructor function, returning our basic Backbone.js view instead of a real TodoView instance.

We then create a simple Backbone.js collection with three models, and associate the TodoList view instance with this collection. When the view’s render() method is called, the expected behaviour is then to call the TodoView constructor once for each model in the collection.

`TodoListView.spec.js`:

describe("TodoListView", function() {
  
  beforeEach(function() {
    this.view = new TodoListView();
  });
  
  ...

  describe("Rendering", function() {
    
    beforeEach(function() {
      this.todoView = new Backbone.View();
      this.todoViewStub = sinon.stub(window, "TodoView")
        .returns(this.todoView);
      this.todo1 = new Backbone.Model({id:1});
      this.todo2 = new Backbone.Model({id:2});
      this.todo3 = new Backbone.Model({id:3});
      this.view.collection = new Backbone.Collection([
        this.todo1,
        this.todo2,
        this.todo3
      ]);
      this.view.render();
    });
    
    afterEach(function() {
      window.TodoView.restore();
    });
    
    it("should create a Todo view for each todo item", function() {
      expect(this.todoViewStub)
        .toHaveBeenCalledThrice();
      expect(this.todoViewStub)
        .toHaveBeenCalledWith({model:this.todo1});
      expect(this.todoViewStub)
        .toHaveBeenCalledWith({model:this.todo2});
      expect(this.todoViewStub)
        .toHaveBeenCalledWith({model:this.todo3});
    });
    
  });
  
});

Running this spec results in 3 errors:

TypeError: Attempted to wrap undefined property TodoView as function
TypeError: Cannot read property 'calledThrice' of undefined
TypeError: Cannot call method 'restore' of undefined

This is telling us that we need to create a TodoView object.

`TodoView.js`:

var TodoView = Backbone.View.extend();

Now, when we re-run the specs, we get this failure:

Expected Function to have been called thrice.

and three of these:

Expected Function to have been called with {..}

Those are the proper failures. Let’s fix it by writing the code we need.

var TodoListView = Backbone.View.extend({

  ...

  render: function() {
    this.collection.each(this.addTodo);
  },
  
  addTodo: function(todo) {
    var view = new TodoView({model: todo});
  }
  
});

Great. This passes, and we are now creating three TodoViews. However, nothing will be rendered in the page. We need to make sure each TodoView’s render() method is called.

Firstly, we need to spy on the fake TodoView’s render() method. We set this up in our beforeEach function:

`TodoListView.spec.js`:

beforeEach(function() {
  this.todoView = new Backbone.View();
  this.todoRenderSpy = sinon.spy(this.todoView, "render");
  ...
});

and then the spec itself:

it("should render each Todo view", function() {
  expect(this.todoView.render).toHaveBeenCalledThrice();
});

The failure that results from running this spec can be fixed with the following one line change added to the render() method in TodosView.js:

`TodoView.js`:

var todoEl = view.render().el;

However, we still need to append the rendered todo to our list. This is done with jQuery. We can either stub the jQuery append method, or we can physically check that an element has been appended. To write a spec for this we first need to create a simple stubbed render method on the TodoView stub object that creates a DOM element and returns itself, like so:

`TodoView.spec.js`:

beforeEach(function() {
  this.todoView = new Backbone.View();
  this.todoView.render = function() {
    this.el = document.createElement('li');
    return this;
  };
  this.todoRenderSpy = sinon.spy(this.todoView, "render");
  this.todoViewStub = sinon.stub(window, "TodoView")
    .returns(this.todoView);
  ...
});

and we can now write a spec to check that one of these elements has been appended for each model:

it("appends the todo to the todo list", function() {
  expect($(this.view.el).children().length).toEqual(3);
});

This produces the following failure as expected:

Expected 0 to equal 3.

Lets’ fix that in TodosView.js:

`TodosView.js`:

addTodo: function(todo) {
  var view = new TodoView({model: todo});
  var todoEl = view.render().el;
  $(this.el).append(todoEl);
}

Running the specs produces the same failure as before. What happened? This is a common gotcha when first starting out with Backbone.js. Because the addTodo() method is called as a callback from within an underscore.js each() iterator, the scope for addTodo is not the TodoListView instance, but the todo model instance that is the target of the iteration cycle. Because of this, there is no el property on this, and the append fails.

Fortunately underscore.js provides a convenience function to fix the scope for a method named bindAll(). In a Backbone.js application it is best called within the initialize() method. It takes the intended scope as the first argument, and one or more methods on the current scope that are to have their scope set:

initialize: function() {
  _.bindAll(this, "addTodo");
},

This sets the scope for the addTodo() method to be the TodosView instance rather than the scope it was actually called with.

Now the jQuery append is being called on the correct object, and the spec passes.

Example 3: Rendering HTML

So far our views have not actually rendered anything. Our TodoListView simply delegates the actual rendering of markup to the individual TodoView objects below it. Let’s test that these TodoView elements are rendered as expected.

We’ll start by just using some string manipulation to create HTML markup to be rendered using jQuery’s html() method.

We will create two specs initially. The first will check that the view’s render() method returns the view instance. This is necessary for chaining, and something that we have already expected in the specs for TodoListView. The second spec will check that the produced HTML is exactly as expected based on the properties of the model instance that is associated with our TodoView.

Our beforeEach function for these specs simply creates a sample model, and then instantiates a TodoView and associates it with the model.

`TodoView.spec.js`:

describe("TodoView", function() {

  beforeEach(function() {
    this.model = new Backbone.Model({
      id: 1,
      title: "My Todo",
      priority: 2,
      done: false
    });
    this.view = new TodoView({model:this.model});
  });

  describe("Rendering", function() {
    
    it("returns the view object", function() {
      expect(this.view.render()).toEqual(this.view);
    });
    
    it("produces the correct HTML", function() {
      this.view.render();
      expect(this.view.el.innerHTML)
        .toEqual('<a href="#todo/1"><h2>My Todo</h2></a>');
    });
    
  });
  
});

When these specs are run, only the second one fails. The first spec that tests that the TodoView instance is returned from render() passes because Backbone.js does this by default, and we haven’t overwritten the render method with our own version yet.

The second spec fails with the following message:

Expected '' to equal '<a href="#todo/1"><h2>My Todo</h2></a>'.

By default, the render() method creates no markup. Let’s write a simple replacement for render():

`TodoView.js`:

render: function() {
  var template = '<a href="#todo/{{id}}"><h2>{{title}}</h2></a>';
  var output = template
    .replace("{{id}}", this.model.id)
    .replace("{{title}}", this.model.get('title'));
  $(this.el).html(output);
  return this;
}

This simply specifies a string template and replaces some fields marked with double curly braces with their respective values from the associated model. Because we are returning the TodoView instance from the method, the first spec also passes.

It hardly needs saying that using an HTML string to test against like this is fraught with problems. It is extremely brittle. If you were to change one tiny thing about your template, including white space, your spec would fail, even thought the rendered output would be the same. It will also become time consuming to maintain as your template becomes more complex.

It is far better to test your rendered output using jQuery to select and inspect attribute and text values, element counts and so on.

Let’s write specs that check some key aspects of the expected output. Again, we are using the custom matchers added by the jasmine-jquery plugin:

`TodoView.spec.js`:

describe("Template", function() {
  
  beforeEach(function() {
    this.view.render();
  });
  
  it("has the correct URL", function() {
    expect($(this.view.el).find('a'))
      .toHaveAttr('href', '#todo/1');
  });

  it("has the correct title text", function() {
    expect($(this.view.el).find('h2'))
      .toHaveText('My Todo');
  });
  
});

Now is a good time to take a look at fixture elements. So far, we have been setting jQuery expectations against the view’s el property. This is absolutely fine in many circumstances, and may actually be preferable a lot of the time. However, at times you will need to actually render some markup into the document. The best way to handle this within your specs is to use fixtures, a feature provided by the jasmine-jquery plugin. Let’s re-write that last spec to use fixtures:

`TodoView.spec.js`:

describe("TodoView", function() {
  
  beforeEach(function() {
 	...
    setFixtures('<ul class="todos"></ul>');
  });
  
  ...
  
  describe("Template", function() {
      
    beforeEach(function() {
      $('.todos').append(this.view.render().el);
    });
      
    it("has the correct URL", function() {
      expect($('.todos').find('a'))
        .toHaveAttr('href', '#todo/1');
    });

    it("has the correct title text", function() {
      expect($('.todos').find('h2'))
        .toHaveText('My Todo');
    });
      
  });
  
});

We are now appending the rendered todo item into the fixture, and setting expectations against the fixture rather than the view’s el property. One reason you might need to do this is when a Backbone.js view is set up against a pre-existing DOM element. You would need to provide the fixture and test that the el property is picking up the correct element when the view is instantiated.

Example 4: Rendering with a template library

We can now start to make the template a little more complex by including some conditional logic. When a todo item is marked as done, we want to provide some visual feedback to the user in the form of a different background colour, or perhaps by striking through the title. We’ll do this by attaching a class to the anchor.

Let’s write a spec to test that this happens.

`TodoView.spec.js`:

describe("When todo is done", function() {
  
  beforeEach(function() {
    this.model.set({done: true}, {silent: true});
    $('.todos').append(this.view.render().el);
  });
  
  it("has a done class", function() {
    expect($('.todos a:first-child'))
      .toHaveClass("done");
  });
  
});

This fails, as expected, with the following message:

Expected '<a href="#todo/1"><h2>My Todo</h2></a>' 
to have class 'done'.

We could fix this in our existing render method like so:

`TodoView.js`:

render: function() {
  var template = '<a href="#todo/{{id}}">' +
    '<h2>{{title}}</h2></a>';
  var output = template
    .replace("{{id}}", this.model.id)
    .replace("{{title}}", this.model.get('title'));
  $(this.el).html(output);
  if (this.model.get('done')) {
    this.$("a").addClass("done");
  }
  return this;
}

However, you can see that this will get cumbersome quickly. The more logic we have here, the more complexity we introduce. This is where a template library can come in handy. There are many available, and exploring the options is beyond the scope of this article. For this example we’ll use Handlebars.js.

We’ll need to add handlebars.js to jasmine.yml or SpecRunner.html. We should be able to rewrite our render code and get the existing specs passing without changing very much.

Here’s our new TodoView object, modified to use handlebars.js:

`TodoView.js`:

var TodoView = Backbone.View.extend({
  
  tagName: "li",
  
  initialize: function(options) {
    this.template = Handlebars.compile(options.template || "");
  },
  
  render: function() {
    $(this.el).html(this.template(this.model.toJSON()));
    return this;
  }
  
});

The initialize method compiles a Handlebars template provided as a string in the instantiation. Another way to reference a template would be by placing it in the page HTML and obtaining it via its id attribute, which is a common approach with Handlebars. In a real application, it would be preferable to use the latter approach, and have your specs load the real template in for testing. One way to do this if your project uses Ruby is to use the Evergreen gem to handle template loading for you.

For our purposes, we’ll continue to use the string injection approach. We add a new directory named templates to the spec directory, and add a new file named todo-template.js which looks like this:

`todo-template.js`:

beforeEach(function() {
  this.templates = _.extend(this.templates || {}, {
    todo: '<a href="#todo/{{id}}">' +
            '<h2>{{title}}</h2>' +
          '</a>'
  });
});

This simply creates or extends a templates object in the Jasmine scope for each test and adds a todo property containing the Handlebars template we want to use.

We’ll need to add the templates folder reference to jasmine.yml or SpecRunner.html, and also update our existing specs slighly to provide the template when instantiating the TodoView object:

`TodoView.spec.js`:

describe("TodoView", function() {

  beforeEach(function() {
	...
    this.view = new TodoView({
      model: this.model,
      template: this.templates.todo
    });
  });
  
  ...
  
});

All of the existing specs continue to pass with our new templating system in place, so we can now enhance the template with some logic for the done status:

`todo-template.js`:

beforeEach(function() {
  this.templates = _.extend(this.templates || {}, {
    todo: '<a href="#todo/{{id}}"{{#if done}} class="done"{{/if}}>' +
            '<h2>{{title}}</h2>' +
          '</a>'
  });
});

And that spec now passes as well.

Example 4: Events

Backbone.js views also allow the declaration of DOM events to be listened for and executed upon. The API to do this is simple: a hash of key/value pairs where the key is a string containing the event to be bound to and the selector to be used, and the value is the name of the method to use as the callback when the event is triggered.

For our Todo app, we will provide a small edit icon for each to do item, which when clicked will replace the title text with an editable input field. Let’s write a spec that checks for this behaviour:

`TodoView.spec.js`:

describe("TodoView", function() {

  ...
  
  describe("Edit state", function() {
    
    describe("When edit button handler fired", function() {
      
      beforeEach(function() {
        $('ul.todos').append(this.view.render().el);
        this.li = $('ul.todos li:first');
        this.li.find('a.edit').trigger('click');
      });
      
      it("shows the edit input field", function() {
        expect(this.li.find('input.edit'))
          .toBeVisible();
        expect(this.li.find('h2'))
          .not.toBeVisible();
      });
      
    });
    
  });
  
});

This spec runs and fails with the following messages:

Expected '' to be visible.
Expected '<h2>My Todo</h2>' not to be visible.

To fix this, we first need to create the edit link and input field in our template:

`todo-template.js`:

beforeEach(function() {
  this.templates = _.extend(this.templates || {}, {
    todo: '<a href="#todo/{{id}}"{{#if done}} class="done"{{/if}}>' +
            '<h2>{{title}}</h2>' +
            '<input class="edit" type="text" ' +
            'value="{{title}}" style="display:none"/>' + 
          '</a>' +
          '<a href="#" class="edit">Edit</a>'
  });
});

Then we add the events hash with our click event linked to an event handler:

`TodoView.js`:

var TodoView = Backbone.View.extend({

  ...
  
  initialize: function(options) {
    _.bindAll(this, "edit");
    this.template = Handlebars.compile(options.template || "");
  },
  
  events: {
    "click a.edit": "edit"
  },

  edit: function() {
    this.$('h2').hide();
    this.$('input.edit').show();
  }
  
});

Don’t forget to add a _.bindAll call to set the scope of the edit callback. Our specs are all green again, and we can move on.

Example 5: Animations and timing

Suppose that one of your esteemed designer colleagues deems that when the user clicks the edit icon, the title text should fade out and the input field should fade in over the course of half a second. Of course, you would think that this is unnecessary fluff in the user interface, but you are overruled and you must carry out the instruction to the full or be dismissed immediately.

When it comes to actually carrying out the designer’s instructions, the code could not be easier. We simply amend the edit method to use jQuery’s fadeIn and fadeOut methods:

edit: function() {
  this.$('h2').fadeOut(500);
  this.$('h2').fadeIn(500);
}

Great! All is well until you run the specs and are greeted with the following failure message:

Expected '<h2 style="opacity: 1; ">My Todo</h2>' 
not to be visible.

The spec is checking the visible state of the title heading immediately after the render() method is called. We need to wait for half a second before we check the state to give the animation time to complete.

One way around this is to use Jasmine’s built-in support for asynchronous specs. The existing spec could be re-written like this:

`TodoView.spec.js`:

describe("When edit button handler fired", function() {
  
  beforeEach(function() {
    $('ul.todos').append(this.view.render().el);
    this.li = $('ul.todos li:first');
    this.li.find('a.edit').trigger('click');
  });
  
  it("shows the edit input field", function() {
    waits(510);
    runs(function() {
      expect(this.li.find('input.edit'))
        .toBeVisible();
      expect(this.li.find('h2'))
        .not.toBeVisible();          
    })
  });
  
});

With this approach, we’re waiting for 510 milliseconds between the click event and the expectations, which are wrapped in a runs() call to make them run after the wait has completed.

That’s not so bad, and the spec passes now. However, write more than a few of these asynchronous timed specs and you’ll end up with a very slow-running spec suite. Our spec suite has gone from 0.15 seconds to 0.65 seconds just because of one spec.

To eliminate this delay we can use the fake timing abilities of Sinon.JS. Instead of actually waiting for half a second to pass, Sinon.JS allows us to fake the passing of time itself. Unfortunately it doesn’t actually manipulate the space/time continuum, which would have been very neat programming indeed, but simply mucks about with JavaScript’s native time-keeping methods such as setTimeout and setInterval.

We can re-write our spec to use Sinon.JS’s fake timers as follows:

`TodoView.spec.js`:

describe("When edit button handler fired", function() {
  
  beforeEach(function() {
    this.clock = sinon.useFakeTimers();
    $('ul.todos').append(this.view.render().el);
    this.li = $('ul.todos li:first');
    this.li.find('a.edit').trigger('click');
  });
  
  afterEach(function() {
    this.clock.restore();
  });
  
  it("shows the edit input field", function() {
    this.clock.tick(600);
    expect(this.li.find('input.edit'))
      .toBeVisible();
    expect(this.li.find('h2'))
      .not.toBeVisible();
  });
  
});

Fake timers are initialised by calling sinon.useFakeTimers() in the beforeEach method. We must restore the native timer functions to their original state after our specs, so we create an afterEach function which does this. Finally, the spec itself is responsible for moving the clock forward by a specified number of milliseconds before we run our expectations.

Now when our specs pass, they pass in around 0.15 seconds again. Even though our application is now using animations, it has had minimal effect on our specs. This is most definitely a Good Thing, as it gives designers and developers the flexibility to tweak interface characteristics such as animations without being unduly held back by the test suite.

The use of fake timers is not limited to animations, of course. They can be used wherever timing is important in your application. For example, you may have a regular polling request that updates some information every minute. Instead of letting a spec run for a full minute, or artificially changing the polling interval in your spec, you can forward the timer by a minute and test that another request has been made to the server.

Summary

Testing user interface behaviours and interactions can sometimes be daunting, and test suites quite often end up being slow-running or incomplete because of the unique challenges the UI of web applications present. Although some of the techniques here are specific to Backbone.js, many apply to jQuery and other rich web application interfaces in general.

Throughout this series of articles, we have concentrated on writing unit tests where individual JavaScript objects are tested in isolation. Your test suite should also include some integration tests where objects are tested in combination with each other, and functional tests where an actual running application is tested using an automated browser driver such as Selenium or Web Driver. There are a pretty large number of frameworks, libraries and drivers that satisfy this need, but they can be difficult to set up, bug-prone and a challenge to debug. For this reason, the unit test suite is essential to catch as many problems as possible as early as possible, and to write test cases when bugs are discovered.

I hope that this series of articles has given you some useful techniques to start testing your Backbone.js applications, and not to be daunted by the apparent complexity that that may present at first. Like any seemingly complex task, testing is simply a matter of breaking the task down into smaller, more manageable units, and using a toolset to make this process faster and more efficient. Happy testing!

Testing Backbone applications with Jasmine and Sinon – Part 2. Models and Collections

2011-03-25T00:00:00+00:00

Overview

This is the second in a series of articles demonstrating how to test a Backbone.js application, employing the Jasmine BDD test framework and the Sinon.JS spying, stubbing and mocking library. If you haven’t yet read the first part, take a look now.

In this part, we’ll look at some examples for testing Backbone models and collections. Along the way, we’ll be introducing techniques that help to keep your Jasmine specs fast, clean and effective, including:

how to isolate each of your Backbone objects for testing
using Sinon’s fake server feature to mock server responses to Ajax requests
using spies to verify event bindings and callbacks

Introducing the example application

What web application tutorial would be complete without an example To Do list application? I wouldn’t want to buck the trend, so for the purposes of the examples here, that’s what we’ll use.

We’re going to create a Todo Backbone model, with a title, priority rating and done status. We’ll then create a Backbone collection of these Todo models called Todos. As we do, we’ll be writing Jasmine specs to test their behaviour.

In the third part of this series, we’ll create router and view objects to handle URL routing and HTML rendering respectively.

Setting up the sample application

The sample application can be found on GitHub. Follow the README there for instructions on setting up and running the specs.

Feel free to fork it, clone it and play around with it. It is a Rails application, but the Rails part of it is pretty minimal as it just serves JSON responses to the Backbone application. In fact, if you run the application, nothing much happens, although you should be able to use the rails scaffolding at /todos to create Todo models and then fetch them using /todos.json.

Running the spec suite

To run your Jasmine specs, you can either run rake jasmine:ci to use Selenium to run through the spec suite or run rake jasmine to start the Jasmine server. The output in the Terminal will tell you what URL the server is running on. Navigating to that URL in a browser will run the spec suite.

Backbone Models

Backbone models can vary dramatically from simple to complex, depending on the requirements of your application. Here we’ll be focusing on some common model tasks – instantiation, default values, URLs and validation.

Example 1: Basic instantiation

Normally, it would not really be necessary to test a simple behaviour such as model instantiation unless you are doing something fancy in your own code. It is easy to get carried away and start testing every little thing just because you can, but you should always ensure that you focus testing on your own code, and avoid directly testing dependencies.

When you write an application using Backbone, you’ll inevitably have some closely coupled code, so it can be difficult to know what to test and what to create fakes for. After all, your application objects are mostly extended Backbone objects. A good rule of thumb is to only directly test the extended Backbone object that you are currently focusing on. Where an object depends on the methods of another object, fake only the APIs that you need to on that related object.

This is a subject that is really best explained by example, so let’s press on with a simple spec for creating (instantiating) a new model. Yes, we’ll be writing the specs first, watching them fail hideously, and then writing the code to make them pass in the red-green-refactor tradition of TDD and BDD.

In a Rails project using the Jasmine gem, new Jasmine spec files are created in the spec/javascripts folder. However, they can be created wherever you like for your project, as long as the file is referenced by your Jasmine spec runner.

`Todo.spec.js`:

describe('Todo model', function() {

  describe('when instantiated', function() {
    
    it('should exhibit attributes', function() {
      var todo = new Todo({
        title: 'Rake leaves'
      });
      expect(todo.get('title'))
        .toEqual('Rake leaves');
    });
    
  });
  
});

Running this spec produces the following output:

ReferenceError: Todo is not defined in ... Todo.spec.js (line 6)

So, we need to create Todo.js. In Rails, this goes somewhere in public/javascripts. I like to create separate folders for models, collections, routers, views and helpers in my Backbone applications to keep things well organised.

`Todo.js`:

var Todo = Backbone.Model.extend();

which produces the following when the spec is re-run:

Finished in 0.03458 seconds
1 example, 0 failures

Yep, all that was needed was to extend the standard Backbone.Model object. The attribute handling is done by Backbone. This is why it could be argued that this spec is unnecessary, but it does at least check that your model is available and named correctly!

Now, onto something slightly more useful.

Example 2: Default values

Backbone allows you to set default values for your models if they are not specified when instantiated. We are going to do this with our Todo priority values. If the user doesn’t set a priority, it will be assumed to have a value of 3 (possible values are 1, 2 and 3).

We need to write another spec. As we are creating a Todo instance for each example, we can move this process into a Jasmine beforeEach function for the sake of efficiency:

`Todo.spec.js`:

beforeEach(function() {
  this.todo = new Todo({
    title: 'Rake leaves'
  });
});

This doesn’t have a priority attribute, so we can now write the spec after the previous one:

it('should set the priority to default', function() {
  expect(this.todo.get('priority')).toEqual(3);
});

When run, the output is:

Expected undefined to equal 3.

Now, to write the (very simple) code:

`Todo.js`

var Todo = Backbone.Model.extend({
  defaults: {
    'priority': 3
  }
});

Example 3: URL

Related to default values are validations. In Backbone.js, a model is validated when the save() or set() methods are called to change attribute values.

However, Backbone will throw an exception if you try to save a model without a url property defined, so let’s look at that first.

Backbone models don’t strictly need to have a url property set, provided that they are a member of a collection that does have a url. A model’s url is its parent collection’s url plus the model id. If it doesn’t yet have an id attribute, it is a ‘new’ model, and so the url is the same as the collection’s by default. In our application, and later in this article, we’ll create a Todos collection, which will have a url of /todos. So, a Todo model with an id of 5 will have the url /todos/5.

This pattern follows RESTful conventions as implemented in Rails 3, but the URL of a model or collection can be set to any string value, or can use a function to generate it each time it is needed.

Because our model’s URL depends on the collection that it belongs to, we’ll need to provide something that can provide this url property. We haven’t yet written the Todos collection, and even if we had, we wouldn’t want to use it as we wouldn’t then be testing the Todo model in isolation.

There are a number of ways to handle this. For this example, we simply need a single property on the foreign object. The simplest approach is to manually stub the url property. We then simply associate our Todo model with our stubbed collection:

`Todo.spec.js`:

it("should set the URL to the collection URL", function() {
  var collection = {
    url: "/collection"
  };
  this.todo.collection = collection;
  expect(this.todo.url()).toEqual("/collection");
});

This spec passes without any work required on our part, as Backbone.js is automatically delegating to the collection to retrieve the url.

This approach is fine if your stub is a simple object or property value. If you are stubbing methods and you need to inspect how the method was called, then you should consider using a Sinon spy, stub or mock. We’ll get to those later.

We should write another example for when the model’s id is set. We’ll move the collection stubbing into a beforeEach function so it is used by both examples without duplication.

`Todo.spec.js`:

describe("url", function() {
  beforeEach(function() {
    var collection = {
      url: "/collection"
    };
    this.todo.collection = collection;
  });

  describe("when no id is set", function() {
    it("should return the collection URL", function() {
      expect(this.todo.url()).toEqual("/collection");
    });
  });

  describe("when id is set", function() {
    it("should return the collection URL and id", function() {
      this.todo.id = 1;
      expect(this.todo.url()).toEqual("/collection/1");
    });
  });
});

Again, this new spec passes first time without any coding required. The example above also demonstrates using nested describe blocks to break up specs by context. This is a common approach in other BDD frameworks such as RSpec. Usually, you would use a beforeEach function in each context block to set up the conditions described.

Example 4: Validation

Now that we have a valid URL defined for the model (even if it is mostly coming from the collection), we can write some validation specs.

The Backbone validate method is not intended to be called directly, but is something that is called when the model’s set() or save() methods are called. Testing it indirectly in this way means that we can’t just do a simple input-output test. But, in the tradition of BDD we are testing our code’s behaviour and not its inner workings.

When we implement our Todo’s view object, the chances are that we’ll want to display something when a model fails validation, so that the user can correct it. To do this, the view binds to the model’s error event, and acts on it. We can do the same thing in our test, so we are also ensuring that the event is fired when we expect. When we bind an event, we pass in a callback function to be run when the event fires. We can use an anonymous spy function as the callback:

var eventSpy = sinon.spy();
this.todo.bind("error", eventSpy);

The spy will record how it is called so that we can later set our expectations against it in a spec. Let’s write one that tests that the model is not saved and an error is thrown when the title is empty. Don’t forget that we still have our Todo model created in a top-level beforeEach function.

`Todo.spec.js`:

it("should not save when title is empty", function() {
  var eventSpy = sinon.spy();
  this.todo.bind("error", eventSpy);
  this.todo.save({"title": ""});
  expect(this.eventSpy.calledOnce).toBeTruthy();
  expect(this.eventSpy.calledWith(
    this.todo, 
    "cannot have an empty title"
  )).toBeTruthy();
});

The expectations are checking that the spy callback was called exactly once, and when it was called, it was called with the Todo model instance and the expected validation failure message. When we run this spec, it fails as expected and Jasmine outputs the following message (twice):

Expected false to be truthy.

Hmm. Although both failures are accompanied by a stack trace and line numbers, the messages themselves are not very helpful. This is because there are no built in Jasmine matchers for setting expectations on Sinon fake objects, so we are forced to use toBeTruthy. Fortunately there is a Jasmine-Sinon plugin which provides these custom matchers. Once included in the project, and referenced from jasmine.yml or SpecRunner.html, you can re-write your Sinon expectations like this:

expect(this.eventSpy).toHaveBeenCalledOnce();
expect(this.eventSpy).toHaveBeenCalledWith(
  this.todo,
  "cannot have an empty title"
);

This spec will now produce these failure messages:

Expected Function to have been called once.
Expected Function to have been called with ...

That’s better. Now to write the validate method to make this spec pass.

`Todo.js`:

var Todo = Backbone.Model.extend({
  ...
  validate: function(attrs) {
    if (!attrs.title) {
      return "cannot have an empty title";
    }
  }
});

When we run the specs again we’re all green.

At this point we would probably want to test that saving a model results in the expected behaviour from our Todo model. However, we will leave server interactions for later.

Now, on to testing collections.

Collections

For our Todo application, we need to create a Backbone.js collection of Todo models. This collection object will be responsible for loading the current todos from the server, as well as standard list behaviour such as ordering and filtering.

Firstly, let’s test that we can add models to the collection.

Example 1: Adding models

When adding models to a collection, Backbone.js will automatically create model instances of the type specified by your collection. For example:

var Zoo = Backbone.Collection.extend({
  model: Animal
});
var edinburghZoo = new Zoo([
  {name:"Panda"},
  {name:"Penguin"}
]);

The two object literals passed into the collection constructor will be used to create new Animal model instances.

In our case, the Todos collection will reference our Todo model prototype, but as we are writing unit specs, we want to isolate the Todos collection, and fake the Todo model. A good way to think of it is to pretend that we haven’t yet created the Todo model and that the Todos collection is the first thing in the application to be authored.

In the model examples, we used a simple handcrafted stub of the collection’s url property, because that is all that was required on the collection API. In this case, the collection actually instantiates new models itself, so we’ll have to stub the model’s constructor function. This is done by creating a Sinon.JS stub as follows:

this.todoStub = sinon.stub(window, "Todo");

This looks a little strange, but you’re simply saying “create a stub of the Todo method on the window object”. Because window.Todo is a constructor function, this is entirely valid.

Whenever we stub a permanent object, we need to restore it back to it’s original state at the end of each spec, usually in an afterEach function:

this.todoStub.restore();

or simply:

Todo.restore();

The next part of creating a stub is to alter what the constructor returns. We could manually craft an object literal to look like a Backbone model, but that would be time consuming and tedious. Instead, we’ll use a bare Backbone.Model constructor. This will give us a real backbone model, but not one of our Todo models.

beforeEach(function() {
  this.todoStub = sinon.stub(window, "Todo");
  this.model = new Backbone.Model({
    id: 5, 
    title: "Foo"
  });
  this.todoStub.returns(this.model);
});

We might expect that this would ensure that our Todos collection always instantiates a stubbed Todo model. However, the reference to the Todo model in the collection has already been set up, so we actually need to reset the model property of the Todos collection by calling:

this.todos.model = Todo

Now when our Todos collection instantiates a new Todo model, it will always return the bare Backbone.js model instance we have created.

We can now write our spec for adding new model literals:

`Todos.spec.js`:

describe("when instantiated with model literal", function() {
  beforeEach(function() {
    this.todoStub = sinon.stub(window, "Todo");
    this.model = new Backbone.Model({
      id: 5, 
      title: "Foo"
    });
    this.todoStub.returns(this.model);
    this.todos = new Todos();
    this.todos.model = Todo; // reset model relationship to use stub
    this.todos.add({
      id: 5, 
      title: "Foo"
    });
  });
    
  afterEach(function() {
    this.todoStub.restore();
  });

  it("should add a model", function() {
    expect(this.todos.length).toEqual(1);
  });
    
  it("should find a model by id", function() {
    expect(this.todos.get(5).get("id")).toEqual(5);
  });
});

We haven’t yet created our Todos collection, so when we run these specs, we get the following error:

ReferenceError: Todos is not defined in .../Todos.spec.js

So we create our Todos collection.

`Todos.js`:

var Todos = Backbone.Collection.extend({
    model: Todo
});

And we have a green spec runner again.

Once again, adding models is something quite simple that you may not end up testing in your own suites, but the technique of stubbing Backbone object constructors is something you’ll need to use time and again.

Example 2: Ordering

If you provide a comparator method in a Backbone.js collection, any models in that collection will be ordered according to the string or integer that is returned from the comparator. In our case, let’s assume we would like to order by priority, so our comparator will simply return the priority attribute, and Backbone.js will do the rest for us.

We can write a spec for this quite easily, but we’ll need to create a few models to add to the collection. Let’s do this in a top-level beforeEach method so that we can have access to the models when needed:

`Todos.spec.js`:

beforeEach(function() {
  this.todo1 = new Backbone.Model({
    id: 1,
    title: 'Todo 1',
    priority: 3
  });
  this.todo2 = new Backbone.Model({
    id: 2,
    title: 'Todo 2',
    priority: 2
  });
  this.todo3 = new Backbone.Model({
    id: 3,
    title: 'Todo 3',
    priority: 1
  });
});

Let’s write the spec to test our ordering method:

it("should order models by priority", function() {
  this.todos.add([this.todo1, this.todo2, this.todo3]);
  expect(this.todos.at(0)).toBe(this.todo3);
  expect(this.todos.at(1)).toBe(this.todo2);
  expect(this.todos.at(2)).toBe(this.todo1);
});

When running this spec, Jasmine outputs:

should order models by priority by default

followed by a long expectation output. Here is the comparator method which we add to Todos.js to make the spec pass.

`Todos.js`:

var Todos = Backbone.Collection.extend({
  model: Todo,
  comparator: function(todo) {
    return todo.get("priority");
  }
});

This example demonstrates that a Backbone collection will take any Backbone model you provide. It does not have to be of the type specified in the collection prototype. The collection does not instantiate any models itself here because it is provided with predefined models. So, again, we’re not depending on our Todo model for this spec to work.

Example 3: Fetching models

Now for a real challenge: how do we unit test the behaviour of an application when it interacts with a server? These tests are often written either as functional tests using fixture data or by using asynchronous unit tests, using real server responses. This is fine, but functional tests can be slow, difficult to set up, require an application to be running on a web server, and depend upon you having all dependencies available.

Fortunately, Sinon.JS circumvents these problems by providing the ability to fake server responses. This means your complex asynchronous server interaction code can be tested in a rapid unit testing environment. This is a boon for the web developer who may not have control over the whole system. You can set how you expect the server to respond to your request, and test that your code handles it. You can also test edge cases, error responses, offline handling and other lunacy, all in your unit tests.

We’ll write two specs to test that fetching a Todos collection results in the correct Todo models being created on the collection. It is important to test the end points of your application where it interacts with other parts of the system. If we are confident that we are making the request to the back-end correctly then integration will be far less bug-prone and problematic.

Before we write our specs, we’ll need to set up our fake server. A fake server is essentially a stub as it replaces the behaviour of a real server, and includes spying features to record the requests that were made. We do this in a beforeEach function:

beforeEach(function() {
  this.server = sinon.fakeServer.create();
  this.todos = new Todos();
});

We also need to restore normality once each spec has run in an afterEach function:

afterEach(function() {
  this.server.restore();
});

Now that we have a fake server object, we can set expectations against it and write our first spec. This will check that the request to the server is correct. We won’t ask the server to respond – we’ll simply check the request it received.

`Todos.spec.js`:

it("should make the correct request", function() {
  this.todos.fetch();
  expect(this.server.requests.length)
    .toEqual(1);
  expect(this.server.requests[0].method)
    .toEqual("GET");
  expect(this.server.requests[0].url)
    .toEqual("/todos");
});

When we run this test, Jasmine catches a Backbone.js error:

Error: A 'url' property or function must be specified in ...backbone-min.js

This is easy to fix, we just add a url property to our Todos collection:

`Todos.js`:

var Todos = Backbone.Collection.extend({
  url: "/todos",
  ...
});

The second spec checks that when the server responds, the collection creates models representing the JSON returned. For this we’ll need to have our fake server respond with some JSON data. We expand our beforeEach function to include this:

beforeEach(function() {
  this.server = sinon.fakeServer.create();
  this.server.respondWith(
    "GET",
    "/todos",
    [
      200,
      {"Content-Type": "application/json"},
      '{"response":"json response here"}'
    ]
  );
});

There’s quite a bit to take in here, but it’s not a as complex as it looks. The fake server’s respondWith method takes three arguments here. The first and second are the HTTP request method and URL to respond to. The final argument is an array representing the response that is returned, which itself has three values: the HTTP response code, an object literal of response headers, and a string containing the response body.

In the above example I have created a very simple JSON response string. However, real JSON responses are often long and complex structures, and we don’t really want those defined in our specs. For this reason we can create fixtures which can be kept in a separate file and shared between specs as needed. The fixtures can be created as JavaScript native literals and converted to JSON strings when the response is formulated.

A fixture file might look something like this:

`fixtures.js`:

beforeEach(function() {
  
  this.fixtures = {
    
    Todos: {
      valid: { // response starts here
        "status": "OK",
        "version": "1.0",
        "response": {
          "todos": [
            {
              "id": 1,
              "title": "Destroy Alderaan"
            },
            {
              "id": 2,
              "title": "Close exhaust port"
            }
          ]
        }
      } 
    }
    
  };
  
});

We use a beforeEach function so that the fixture is recreated for each spec (in case an unscrupulous developer modifies it). We then create a group of Todos fixtures, with one ‘valid’ response. In this way we can create similar fixtures for error responses and all sorts of other scenarios. The fixture can then be accessed from within a spec with this.fixtures.Todos.valid.

Using the built-in JSON parser in modern browsers, and including Doug Crockford’s JSON library to polyfill older browsers, we can convert this fixture into a JSON response body in our respondWith method:

`Todos.spec.js`:

beforeEach(function() {
  this.fixture = this.fixtures.Todos.valid;
  this.server = sinon.fakeServer.create();
  this.server.respondWith(
    "GET",
    "/todos",
    [
      200,
      {"Content-Type": "application/json"},
      JSON.stringify(this.fixture)
    ]
  );
});

That is still a little long, and if you use a lot of fakeServer responses, it will start to take up a lot of space. Most of the time when testing your Backbone.js application, you will want to provide a valid response with a 200 response code, an application/json content-type and a JSON body. Let’s write a little helper convenience method, which we can place in a separate file and include in our spec suite.

`spec-helpers.js`:

beforeEach(function() {

  this.validResponse = function(responseText) {
    return [
      200,
      {"Content-Type": "application/json"},
      JSON.stringify(responseText)
    ];
  };

});

Like the fixture data, we put spec helper methods in a beforeEach function and assign the method to the current scope which is shared across all specs. Our respondWith call can now be re-written to:

`Todos.spec.js`:

this.server.respondWith(
  "GET",
  "/todos",
  this.validResponse(this.fixture)
);

For the purposes of our spec, we’ll need to discover the format that the response will take. If you are in control of the back-end then this is easy, and you can ensure that the response is straightforward to handle on the client. However, it is often the case that the server response is not your responsibility, for example if another team member is developing it, or the source is an external API. In these cases you will often need to do some parsing of the JSON response before models are created.

You can see in our fixture above that the array of Todo items are accessible from within the response JSON at response.todos. To point Backbone.js in the right direction we need to write a parse() method on the Todos collection. This is called whenever data is retrieved from the server, is passed a response argument, and it must return the array of models representing the collection.

Our spec for the parse method will use the fakeServer to respond with the JSON fixture above, and we’ll check that models have been created as expected.

`Todos.spec.js`:

it("should parse todos from the response", function() {
  this.todos.fetch();
  this.server.respond();
  expect(this.todos.length)
    .toEqual(this.fixture.response.todos.length);
  expect(this.todos.get(1).get('title'))
    .toEqual(this.fixture.response.todos[0].title);
});

We only check one model, but you could enumerate over the fixture and check each model very easily. By inserting this.server.respond() at the appropriate point in the spec, we are telling the fakeServer to respond with our pre-canned fixture. Note that we have not needed to write an asynchronous test here, despite the fact we are testing asynchronous callbacks.

When this is run, Jasmine fails the spec with this message:

Expected 1 to equal 4

We are only getting 1 model because Backbone is assuming that the top level object in the JSON response is a model to be defined within the collection. Let’s fix that:

`Todos.js`:

var Todos = Backbone.Collection.extend({
  ...
  parse: function(res) {
    return res.response.todos;
  },
  ...
});

Now the collection is receiving an array of model-like object literals, and the spec passes.

The same approach can be used for faking all the standard CRUD operations you might find in a modern web application. For example, to test that your application is correctly saving new models to the server, you would set up a fakeServer that expects a POST request to the /todos URL, and then call the model’s save() method in a spec.

Summary

That concludes our look at testing Backbone.js models and collections. Next time we’ll look at Backbone.js routers and in particular, views, which represent a particular challenge for unit testing.

Using SquidMan to snoop iOS HTTP requests

2011-03-10T00:00:00+00:00

If you need to inspect HTTP requests made by iPhone or iPad applications, a simple approach is to use SquidMan on your Mac.

The basic approach is as follows:

Run SquidMan on your Mac
Change the proxy settings on your iOS device to point to the SquidMan server
Start tailing the Squid logs on your Mac
Use the application you want to inspect
Watch as requests appear in the log
Save the logs if needed

In order for this to work, you’ll need a Mac and your iPhone or iPad to be connected to the same wireless network.

Install and run SquidMan

SquidMan is a simple GUI front-end for the Squid caching proxy server. Download the latest version and install it as you would any other OS X application.

When you first run SquidMan, the Preferences panel will be displayed. You only need to do two little tasks in here.

Firstly, take a note of the HTTP port number that Squid uses. You may need to change this port if you’re already using it somewhere else on your system.

Secondly, you’ll need to provide proxy services for your iOS device. To do this follow these steps:

On your iPad or iPhone, launch the Settings application and select the Wi-Fi section.
Under the Choose a Network… section you should see your wireless network listed. Touch the blue arrow to the right of the entry.
If the DHCP tab is selected, you’ll see an IP address listed. Make a note of this.
Back in the SquidMan preferences, choose the Clients tab.
Click the New button to add a host
Enter the IP address you noted from the iOS device settings and click Save.

Close the preferences pane and click the Start Squid button to get going. SquidMan should inform you that Squid is now running.

Change iPhone or iPad proxy settings

You first need to make a note of your Mac’s IP address on the wireless network.

Open the Network panel under System Preferences
Open either the Ethernet or AirPort section depending on how your Mac connects to the network.
The IP address should be listed there. For the sake of example, we’ll use 192.168.0.102.

You should have an IP address and a port for the proxy server. You can now tell your iPhone or iPad to use this proxy server when it accesses the internet using your wireless network.

Back on your iPhone or iPad with your Wi-Fi settings page still open you should see an HTTP Proxy section.
Select the Manual tab. You should now see form fields for the Server and Port.
Enter the IP address of your Mac into the Server field
Enter the SquidMan port value you noted earlier into the Port field
Exit the Settings application

At this point you can check that internet access is still working by launching Mobile Safari. If you are getting access denied messages, you need to make sure that Squid is set up to provide access to each device.

Tail Squid logs

There are two ways you can inspect Squid logs: from within SquidMan, or through the Terminal.

In SquidMan

Simply open the SquidMan | Tools menu option or hit [COMMAND]-T.
Click the Access Log button. You’ll need to click this again to manually refresh the logs.

The example below shows a sample log from the BBC News app. They appear to have code-named the project ‘Moira’, most likely as a dedication to newsreader Moira Stewart…

In Terminal

You can easily tail the Squid request logs to see what requests are being made through the proxy as soon as they are made.

To do this, open a Terminal window and run the following:

$ tail -200f ~/Library/Logs/squid/squid-access.log

Whilst the logs will not give you more than the basic details of the request and response, it is enough in most cases to see what is going on behind the scenes of a typical iOS application.

Testing Backbone applications with Jasmine and Sinon – Part 1

2011-03-03T00:00:00+00:00

Overview

This is the first in a series of articles demonstrating how to test a Backbone.js application, employing the Jasmine BDD test framework and the Sinon.JS spying, stubbing and mocking library.

In this part, we’ll take a brief look at Backbone, and then move on to an introduction to some of the features of Jasmine and Sinon.JS. Along the way we’ll look at why these tools are a such good fit for testing Backbone applications.

If you have never written any JavaScript tests before, you might like to take a look at Christian Johansen’s recent series of articles over at scriptjunkie.

Backbone everywhere

In the last few months, Backbone.js has received a fair bit of exposure, with a number of tutorials and one or two high profile implementations.

Backbone’s popularity is understandable. It provides a fairly minimal model-view-controller (MVC) structure to help organise all that complex code, but leaves other choices up to the developer. Unlike rich JavaScript UI frameworks such as Cappuccino, it does not provide UI widgets or themes, but leaves the choice of DOM library up to the developer. Backbone has specific support for jQuery or Zepto if you include them, but it does not preclude the use of other libraries.

Backbone’s MVC structure lends itself very nicely to bottom-up unit testing. The separation of concerns into models, collections, views and routers means that the behaviour of each ‘class’ (unit) can be tested in isolation, eliminating many bugs up front, and making debugging far simpler.

This should be very familiar to anyone who has spent any time testing applications developed with MVC frameworks such as Rails or Django. There are a number of mature libraries, tools and approaches designed for unit testing these applications. You’ll need to write JavaScript tests to ensure that your front-end application code is of as high a quality as your server-side code.

About Jasmine BDD

Jasmine is a behaviour-driven development (BDD) testing framework for JavaScript, which has been developed with more than a passing nod to the Ruby library RSpec. As with RSpec, Jasmine allows you to write ‘specs’ (not tests) representing a single example of behaviour that you would like your code to exhibit.

BDD emphasises shared language amongst developers and stakeholders. The ethos of BDD, and the way that specs are written in RSpec and Jasmine encourage developers to focus on testing the external behaviour of their code, rather than its internal details, with specs that are couched in terms of this shared language. This encourages the developer to always consider the beneficial value of the feature being developed, and focus on delivering it.

If you’re interested in learning more about BDD, then take a look at Dan North’s original BDD article, or even at the RSpec Book which has chapters dedicated to the subject, and is more of a BDD bible than an RSpec how-to.

Specs

So, let’s dig in and take a look at what Jasmine specs look like. Here is a rather simplistic example of a spec for a Backbone model using Jasmine:

it("should expose an attribute", function() {
  var episode = new Backbone.Model({
    title: "Hollywood - Part 2"
  });
  expect(episode.get("title"))
    .toEqual("Hollywood - Part 2");
});

A spec is simply a description of the expected behaviour, the code that will result in that behaviour, and one or more expectations that test the behaviour.

Individual specs should be short and only test one aspect of behaviour. If you find yourself writing a number of different expectations or a spec becomes quite long, then consider breaking it out into other specs. Grouping your specs with suites and using shared set up and teardown functions can help with this.

Suites

Specs are grouped into Suites, which are defined using the describe() function. For example, all the specs for the Episode model could be grouped into a suite as follows:

describe("Episode model", function() {
  it("should expose an attribute", function() {
  ...
  });
  it("should validate on save", function() {
  ...
  });
});

Suites can also be nested, which is great when you have a lot of specs, as you can organise them into sets of discrete chunks. I like to use a describe block to wrap specs relating to a particular starting context. This better retains the conversational style of the specs. For example:

describe("Episode model", function() {
  describe("when creating a new episode", function() {
    it("should expose the title attribute", function() {
      ...
    });
    it("should have a default parental rating", function() {
      ...
    });
  });
});

beforeEach() and afterEach()

As in traditional xUnit style testing frameworks, you can optionally specify code to run before and after each test. This is great for ensuring consistent conditions for each test, and for setting up variables and objects to be used in your specs.

The example below uses beforeEach() to create a model instance that will be used in each spec.

describe("Episode", function() {
  
  beforeEach(function() {
    this.episode = new Backbone.Model({
      title: "Hollywood - Part 2"
    });
  });
  
  it("should expose an attribute", function() {
    expect(this.episode.get("title"))
      .toEqual("Hollywood - Part 2");
  });
    
  it("should validate on save", function() {
    ...
  });
    
});

You can provide a beforeEach() and an afterEach() method for each nested describe that you have in your specs, allowing you to have both general and specific setup and teardown methods tailored for each suite of specs. As you’ll see in the other parts of this article, this is very handy indeed for reducing repetition and controlling the exact conditions for each spec.

The spec runner

This structure results in specs that are pretty easy for other developers to read and interpret directly, largely because of the description for each spec and the format of the expectation matchers.

Jasmine also provides a simple spec runner, which is simply an HTML page with a script that will run all the specs you provide. The following shows the output from a suite of specs with a single spec failure:

We’ll be introducing some other helpful features of Jasmine in the other parts of this article as we need them, including creating fixtures, working with jQuery and creating your own custom expectation matchers. Now, onto Sinon.JS.

Sinon.JS

Sinon.JS is a library that provides fake objects – spies, stubs and mocks – for testing your JavaScript code. If you don’t know what these are, then you aren’t alone. The use of these constructs in testing JavaScript code is not something that has really caught on just yet. However, if you are developing a rich, complex application such as you might using Backbone, then fake objects are a very useful part of the testing toolset.

Christian Johansen, the creator of Sinon.JS, explains why you would want to use fakes in another scriptjunkie article. In JavaScript applications, these reasons boil down to:

Performance - real DOM manipulation, reliance on timed behaviour and network activity slows tests down
Isolation - unit tests should focus on as small a piece of functionality as possible, and be de-coupled from unreliable or slow dependencies

The use of fake objects is a fundamental part of embracing test-driven and behaviour-driven development. They essentially allow code to be tested in isolation from its dependencies. Any APIs or modules that your code under test depends upon can be faked to respond in the way you need for your test. You can also inspect the faked methods to see exactly how they were called during the course of a test.

Sinon.JS allows you to provide fakes for almost anything. You can fake parts of your own application, specific behaviours within jQuery, the XmlHttpRequest API itself, or you can even fake JavaScript’s timer methods to allow for rapid testing code that has timing dependencies, such as animations and timeouts.

Sinon.JS provides three types of fake object: spies, stubs and mocks.

Spies

Spies are functions that keep track of how and often they were called, and what values were returned. This is phenomenally useful in asynchronous and event-driven applications as you can send a spy function off to keep track of what’s going on inside your methods, even if those methods are anonymous or closed off from direct inspection.

Spies can be ‘anonymous’ or can spy on existing functions.

An anonymous spy is just an empty function with spying features that can be sent off to record how it was used. Like a real spy being sent behind enemy lines with a microphone attached to it’s chest, the method under test is none the wiser. Here is an example of a spy testing a simple Backbone custom event binding:

it("should fire a callback when 'foo' is triggered", function() {
  // Create an anonymous spy
  var spy = sinon.spy();
  
  // Create a new Backbone 'Episode' model
  var episode = new Episode({
    title: "Hollywood - Part 2"
  });
  
  // Call the anonymous spy method when 'foo' is triggered
  episode.bind('foo', spy); 
  
  // Trigger the foo event
  episode.trigger('foo'); 
  
  // Expect that the spy was called at least once
  expect(spy.called).toBeTruthy(); 
});

This will pass if the spy was called one or more times, no matter how it was called or what the arguments were. However, Sinon provides a number of methods that allow you to be as strict as you like about the number of invocations, and indeed what each invocation looked like, and what the spy returned.

Spying behaviour can also be attached to an existing method. Hilariously, I like to call these ‘moles’. This is useful to check that some piece of functionality is calling another part of the code as expected. For example, you may want to check that a model’s save method makes the correct jQuery $.ajax call:

it("should make the correct server request", function() {
  
  var episode = new Backbone.Model({
    title: "Hollywood - Part 2",
    url: "/episodes/1"
  });
  
  // Spy on jQuery's ajax method
  var spy = sinon.spy(jQuery, 'ajax');
  
  // Save the model
  episode.save();
  
  // Spy was called
  expect(spy).toHaveBeenCalled();
  // Check url property of first argument
  expect(spy.getCall(0).args[0].url)
    .toEqual("/episodes/1");
  
  // Restore jQuery.ajax to normal
  jQuery.ajax.restore();
});

Stubs and Mocks

Stubs and mocks in Sinon implement all the features of spies, but with some added features. Stubs allow you to replace the existing behaviour of a particular method with whatever you like. This is great for emulating exceptions and error scenarios from external dependencies so you can test that your code will respond appropriately. It also allows you to start development when other dependencies are not yet in place.

Mocks provide all this, but instead mock an entire API and set built-in expectations on how they will be utilised. Like spies they track how they have been used, and like stubs they respond in a pre-programmed manner according to the needs of the test. However, unlike a spy, the expectations for their behaviour is pre-programmed, and a single verification step at the end will fail if any of these individual expectations are not met.

We’ll explore stubs and mocks as they needed in the other parts of this article.

Fake Ajax and fake servers

Sinon is not limited to spying on and stubbing plain functions and methods. It also provides shortcuts for faking Ajax responses. This means you can test your code in complete isolation from your JSON data source, and don’t depend on a running a web application in order to run your spec suites. Furthermore, you can test that your application responds appropriately when it strays from the happy path, including invalid JSON and various HTTP response codes.

Here’s a simple example of a spec for a Backbone model’s fetch method that uses a fake server to respond to Ajax requests:

describe("Episode model", function() {
  beforeEach(function() {
    this.server = sinon.fakeServer.create();
  });
    
  afterEach(function() {
    this.server.restore();
  });

  it("should fire the change event", function() {
    var callback = sinon.spy();
    
    // Set how the fake server will respond
    // This reads: a GET request for /episode/123 
    // will return a 200 response of type 
    // application/json with the given JSON response body
    this.server.respondWith("GET", "/episode/123",
      [200, {"Content-Type": "application/json"},
      '{"id":123,"title":"Hollywood - Part 2"}']);

    var episode = new Episode({id: 123});
    
    // Bind to the change event on the model
    episode.bind('change', callback);
    
    // makes an ajax request to the server
    episode.fetch(); 
    
    // Fake server responds to the request
    this.server.respond(); 
        
    // Expect that the spy was called with the new model
    expect(callback.called).toBeTruthy();
    expect(callback.getCall(0).args[0].attributes)
      .toEqual({
        id: 123,
        title: "Hollywood - Part 2"
      });
    
  });

});

This spec can be made to pass with this simple Backbone model:

var Episode = Backbone.Model.extend({
  url: function() {
    return "/episode/" + this.id;
  }
});

There is more to Sinon that we haven’t covered here. In particular, fake timers are very useful for testing time-dependent functionality such as animations without slowing down your tests. Check out the full documentation.

Summary

In the bleeding-edge world of Backbone applications, complex asynchronous and interdependent behaviours can cause any developer a major headache. Backbone helps developers to structure their code into small, self-contained models, collections, views and routers. But this is really only half the battle. Without well-tested code there will be a greater number of undetected bugs, and those that are discovered will be harder to track down. Other team members may unintentionally break your code, or simply misunderstand its purpose.

In the second part of this article, we will move on to actually testing some Backbone models and over time we’ll build up a simple working application with a suite of specs to go with it.

Git config shortcuts for GitHub

2011-02-18T00:00:00+00:00

Sam Elliott has posted some neat Git config tricks that allow some nice shortcuts for GitHub and Heroku:

This allows you to use shortcuts for cloning repositories:

$ git clone github:lenary/guides.git

and gists:

$ git clone gist:806037

I’m off to put these in my .gitconfig now.

Jasmine matchers for Sinon.JS

2011-02-14T00:00:00+00:00

I have written a small plugin for the Jasmine BDD JavaScript testing framework to allow for better integration with the Sinon.JS spying, stubbing and mocking library.

Using Sinon.JS with Jasmine means you end up writing slightly unhelpful expectations. Here is a simple spec involving a Sinon spy:

expect(spy.calledWith('foo')).toBeTruthy();

The jasmine-sinon plugin creates custom matchers for Jasmine, so that you can do this instead:

expect(spy).toHaveBeenCalledWith('foo');

This means that your specs read better, but you also get better failure output from the Jasmine spec runner. Instead of:

Expected false to be truthy.

the output is:

Expected Function to have been called with 'foo'.

The plugin is at version 0.1, and needs some further testing. It is also missing any exception matchers. Please fork at will.

Jasmine-sinon plugin on Github.

Why web professionals should avoid professionalism

2011-02-03T00:00:00+00:00

Clay Shirky's book Here Comes Everybody is over two years old now. So of course I am just reading it now - in fits and spurts - to make sure that my hastily formed opinions are as out of date as possible.

Shirky talks about professionalism in journalism in Chapter 3 (Everyone is a Media Outlet), arguing that traditional structures such as formal education, training and organisational membership designed to maintain professional standards are the very things that suppress innovation and progression:

"... the professional outlook can become a disadvantage, preventing the very people who have the most at stake – the professionals themselves – from understanding major changes to the structure of their profession."
—Clay Shirky

This sentence expressed for me why I am thankful for belonging to a relatively informally structured profession, compared to say, architecture or law. Those traditional professions use traditional means to protect their reputation and standards. When hiring or talking about their own professional effectiveness, most web professionals that you care to talk to will generally eschew formal qualifications, organisational membership and so on, in favour of a loose set of evidence-based norms - or in other words, cool shit you've made.

When was the last time you heard someone mention their masters degree in Interactive New Media Interweb Technologies when giving a talk, or when introducing themselves at an unconference? No, it's all "Oh, you're that bloke that wrote flibFlab.js - I use that every day!"

In our profession, new talent can gain recognition within a very short space of time, merely by designing or coding wickedorsum stuff and putting it on Dribbble, GitHub or HackerNews. With more companies apparently hiring based on someone's public output of work (even algorithmically) rather than their work history, the traditional barriers of experience, education (to a certain degree) and Not Knowing the Right Person have broken down. This is why it is easier to find good people on GitHub than on LinkedIn, and why recruitment consultants plague the latter and not the former.

All this is pretty self-evident. But my main point is this: in a rapidly moving profession with informal and shifting norms and standards, the old guard better keep moving along or they'll find they've been shown up rather easily by those with more talent, audacity and, to be fair, time on their hands. In more traditional professional professions, simply having the job you've got and maintaining a baseline of suitable behaviour and quality is enough to keep you exactly where you are, whilst fostering just the right amount of status anxiety to keep you sharp. How dull.

As the costs of building and shipping stuff falls, us old giffers that have been doing this stuff since 1995 should find ourselves losing more of our excuses for not shedding our pride and actually producing some real stuff of our own. Hence this blog, and hence some other stuff I want to get out there that I'm working on, and trying to fit around raising a family and getting some sleep. It's either this or kick myself upstairs into a moribund management career tinged with regret. I enjoy learning and hacking around too much for that.

In short then, make fun stuff and keep on trucking, old man.

Tinned Fruit

Futuristic progressive enhancement talk

Your mobile mileage may vary

Do your own research

Finding out about devices

Shopping

Conclusion

Massive disclaimer

Edinburgh International Book Festival mobile site

Why a mobile website?

No app stores

The problem of discoverability

Interactive phone features

Device support

Libraries and frameworks

Design and development

Agile methods

Design - keeping it simple

Framework choice

A website is a website is a website

Boilerplates

Open source FTW

Thank you

Culture Hack Scotland 2011

Data sources

Technologies

Testing Backbone applications with Jasmine and Sinon – Part 3. Routers and Views

Overview

Routers

Example 1: Testing routes

AppRoutes.spec.js:

AppRouter.js:

AppRouter.js:

AppRoutes.spec.js:

AppRouter.js:

Example 2: Testing router methods

AppRouter.spec.js:

AppRouter.spec.js:

AppRouter.js:

AppRouter.spec.js:

AppRouter.js:

Views

Example 1: Creating the root element

TodoListView.spec.js:

TodoListView.js:

TodoListView.spec.js:

TodoListView.js:

Example 2: Rendering

TodoListView.spec.js:

TodoView.js:

TodoListView.spec.js:

TodoView.js:

TodoView.spec.js:

TodosView.js:

Example 3: Rendering HTML

TodoView.spec.js:

TodoView.js:

TodoView.spec.js:

TodoView.spec.js:

Example 4: Rendering with a template library

TodoView.spec.js:

TodoView.js:

TodoView.js:

todo-template.js:

TodoView.spec.js:

todo-template.js:

Example 4: Events

TodoView.spec.js:

todo-template.js:

TodoView.js:

Example 5: Animations and timing

TodoView.spec.js:

TodoView.spec.js:

Summary

Testing Backbone applications with Jasmine and Sinon – Part 2. Models and Collections

Overview

Introducing the example application

Setting up the sample application

Running the spec suite

Backbone Models

`AppRoutes.spec.js`:

`AppRouter.js`:

`AppRouter.js`:

`AppRoutes.spec.js`:

`AppRouter.js`:

`AppRouter.spec.js`:

`AppRouter.spec.js`:

`AppRouter.js`:

`AppRouter.spec.js`:

`AppRouter.js`:

`TodoListView.spec.js`:

`TodoListView.js`:

`TodoListView.spec.js`:

`TodoListView.js`:

`TodoListView.spec.js`:

`TodoView.js`:

`TodoListView.spec.js`:

`TodoView.js`:

`TodoView.spec.js`:

`TodosView.js`:

`TodoView.spec.js`:

`TodoView.js`:

`TodoView.spec.js`:

`TodoView.spec.js`:

`TodoView.spec.js`:

`TodoView.js`:

`TodoView.js`:

`todo-template.js`:

`TodoView.spec.js`:

`todo-template.js`:

`TodoView.spec.js`:

`todo-template.js`:

`TodoView.js`:

`TodoView.spec.js`:

`TodoView.spec.js`:

`Todo.spec.js`:

`Todo.js`:

`Todo.spec.js`:

`Todo.js`

`Todo.spec.js`:

`Todo.spec.js`:

`Todo.spec.js`:

`Todo.js`:

`Todos.spec.js`:

`Todos.js`:

`Todos.spec.js`:

`Todos.js`:

`Todos.spec.js`:

`Todos.js`:

`fixtures.js`:

`Todos.spec.js`:

`spec-helpers.js`:

`Todos.spec.js`:

`Todos.spec.js`:

`Todos.js`: