Backbone.js Testing

Apps, suites, and examples for Backbone.js test development.

Introduction

This site provides materials and resources for developing and testing Backbone.js web applications. All of the application and test examples for the book Backbone.js Testing can be found here, grouped by chapter. We also provide a reference Backbone.js application - Notes - for creating and viewing notes, which we use throughout the examples in the book.

The core set of Backbone.js application technologies we cover includes:

We write a test infrastructure built on the following (fantastic) test libraries.

The source code for everything is available from the project's GitHub repository. If you find any errors or issues in content or code, please file a bug report and we'll fix things up in short order. For those interested in extending our testing examples or helping out, please see our contribution and development guide.

Book

Backbone.js Testing by Ryan Roemer walks through the fundamentals of test-driven development for Backbone.js applications. All of the code samples are directly used in the book - it is essentially your narrative guide to this repository.

Book Cover

A short description of the book from the Packt Publishing website:

Frontend web applications are soaring in popularity and the Backbone.js library is leading this charge with a modular, lightweight approach for organizing JavaScript web applications. At the same time, testing client-side JavaScript and Backbone.js programs remains a difficult and tedious undertaking.

Backbone.js Testing brings sensible practices and current techniques to the challenges of Backbone.js test development. The book introduces fundamental testing concepts, comprehensive test infrastructure design, and practical exercises to easily and systematically test modern JavaScript web applications.

The book progresses from Mocha test suites and Chai assertions to advanced test mocks and stubs with Sinon.JS. The requisite libraries and utilities are introduced with in-depth examples and best practices for integration with your applications. The book guides you through the test planning and implementation processes for your application models, views, routers, and other Backbone.js components.

Backbone.js Testing gives you the tools, examples, and assistance to test your Backbone.js web applications thoroughly, quickly, and with confidence.

Compatibility

The application and test samples should work for the following browser / version combinations:

See the Chai installation notes for more compatibility information. Note that the Chai should object prototype extension is not compatible with IE 9 and lower.

Notes App

Notes is a simple personal note manager, written in Backbone.js. We provide two versions - a "quick and easy" localStorage based application that works in your browser with no additional setup, and a "classic" application with a full REST backend.

The Tour

The Notes application home page lists existing notes (by creation date), and provides a form field to create a new note with a title. A filter field is available in the menu bar to limit the list of displayed notes by title.

Notes List

Clicking on the edit icon brings us to the single note view, with a simple form editor for the title and text body fields of the note. The body of a note is written using Markdown formatting.

Edit Note

Clicking on the view menu tab switches us to the viewing pane, which renders the note's Markdown and produces our displayed note.

View Note

The Notes application is written using Bootstrap's responsive libraries and should render fine on mobile devices, tablets, and pretty much anything else.

LocalStorage App

The directory "notes/app" contains the standalone application, which uses HTML5 localStorage as a backing store. Some useful links to get you started:

Server-Backed App

An alternative version of the application uses MongoDB instead of localStorage for notes data and can be found in the "notes-rest" directory. The application is served via a Node.js/Express application located in "notes-rest/server.js".

Although we don't provide an online demo application, the full application test suite is available online using Sinon.JS fake servers to fake out the requirement of having a real backend MongoDB server for the App.Collections.Notes tests. The test suite is nearly identical to the localStorage application tests for all of the other tests.

The server requires Node.js and MongoDB installations. Once you have these installed, you can change into the root of this repository and install all of the project libraries:

$ npm install

To run the sample server application, you will need two terminal windows. In the first window, start up MongoDB:

$ npm run-script mongo-start

In the second window, start up the Express server:

$ npm start

And from there you can navigate a browser to:

Note that you can control several application options by setting console environment variables:

For example:

$ export PORT=4323; npm start

runs the server on port 4323 instead of 4321 (the default).

Chapter Examples

The examples for each chapter are provided in the "chapters" directory, separated by number. We also provide a driver page for (nearly) all of the non-application tests.

Chapter 1: Setting up a Test Infrastructure

Chapter 2: Creating a Backbone.js Application Test Plan

Chapter 3: Test Assertions, Specs, and Suites

Chapter 4: Test Spies

Chapter 5: Test Stubs and Mocks

Chapter 6: Automated Web Testing

We don't introduce any new tests in Chapter 6, instead focusing on automating all of the application and chapter tests we have provided in this respository. See the next section for a discussion of test automation with PhantomJS.

Automated Tests

All of the tests for the Notes application and the chapter samples can be run in the PhantomJS headless WebKit engine. Simply install the Node.js dependencies:

$ npm install

and install PhantomJS on your development machine. Note that as of v3.0.0, mocha-phantomjs requires PhantomJS v1.9.1 or above.

From there, you can use the mocha-phantomjs binary to run any HTML test driver page from the command line, e.g.:

$ mocha-phantomjs notes/test/test.html

As a helper, the following script command will run nearly all of the Notes application and chapter unit tests:

$ npm test

We run all of these tests automatically using (the awesome) Travis CI continuous integration service. Travis watches the GitHub repository containing this project and when it detects the code has changed, launches new builds and invokes the PhantomJS tests above.

Travis even provides a convenient image status indicator, that we display below, so that we can display the always current build status of our code:

Build Status

Setting all of this up is as simple as adding a Travis configuration file ".travis.yml" as follows:

language: node_js
node_js:
  - 0.8
  - 0.10

This instructs Travis to test out the latest Node.js versions for v0.8 and v0.10. By default, Travis already has PhantomJS installed and will run npm install and npm test on any Node.js project, which conveniently sets up and invokes all of our PhantomJS tests.

Our actual ".travis.yml" file runs different commands than the default npm test to add things like style checking. But, the overall Travis configuration is essentially the same.

Additional Tools

There are many additional testing libraries and plugins specifically suited to testing Backbone.js applications beyond the core test stack we use in the application and chapter examples above.

Chai

Chai has a rich plugin ecosystem, with libraries that enhance the core Chai assertion statement library, provide more specific failure messages, and make application behavior easier to express.

Plugins that are used in some examples:

Additional plugins not used in the examples:

Libraries & Versions

All frontend libraries used in this repository for the sample apps and chapter examples are provided in the "vendor" directory.

Note that this repository has been updated since the publication of Backbone.js Testing on July 12, 2013. The enumerated versions of all third party libraries are indicated by the most current version in the repository with the published version optionally provided in parenthesis when different.

The core Backbone.js components used are:

The sample Notes application also uses:

The frontend test libraries we use are:

The test plugins include:

Notes

Published Versions and Code

The repository was tagged with git as published-1.0 for the code samples that are shipped with the book as it went to press. To check out the published version in this repository, type:

$ git checkout tags/published-1.0

This will switch all libraries, application code, and tests to the version that directly matches the book.

Mocha-PhantomJS and PhantomJS

As of v3.x.x and higher, Mocha-PhantomJS requires PhantomJS v1.9.1 or higher.

Mocha-PhantomJS and Mocha Compatibility

Mocha version 1.10.0 and 1.11.0 introduced incompatibilities with Mocha-PhantomJS. Modern versions of both libraries are now compatible, e.g., Mocha v1.12.0+ and Mocha-PhantomJS v3.1.0+.

For this historically minded, the evolution of this issue is documented in the following tickets:

Backbone.js Testing shipped with Mocha v1.9.0 and Mocha-PhantomJS v2.0.3 to avoid the issue.

Licenses

All code not otherwise specified is Copyright 2013 Ryan Roemer. Released under the MIT License.

This repository contains various libraries from other folks, and are licensed as follows:

Development

For those who would like to get under the hood, or help out with the application or test examples.

Scripts, Commands

For pretty much everything, you will need to install PhantomJS, a Node.js environment, and the development NPM dependencies:

$ npm install

From there, there are various Grunt script helpers for style checking and tests:

# Run style checks for server, client, and both.
$ ./node_modules/.bin/grunt jshint:server
$ ./node_modules/.bin/grunt jshint:client
$ ./node_modules/.bin/grunt jshint

# Run headless tests for the application, individual chapters, all chapters
# as one big test, and all of these together.
$ ./node_modules/.bin/grunt test:app
$ ./node_modules/.bin/grunt test:rest
$ ./node_modules/.bin/grunt test:chaps
$ ./node_modules/.bin/grunt test:chaps-all
$ ./node_modules/.bin/grunt test

# Run all style checks and headless tests.
$ ./node_modules/.bin/grunt check

The file "README.md" is transformed from markdown into the HTML page "index.html", and can be compiled once, or watched for changes with the following commands.

$ ./node_modules/.bin/grunt jade:docs
$ ./node_modules/.bin/grunt watch:docs

Contributions

Bugs, issues and fixes for any of the application or test code examples are most welcome. Please file a GitHub issue or pull request for any changes. Pull requests should be able to pass

$ ./node_modules/.bin/grunt check

without any errors.

History

Current

v0.0.3

v0.0.2

v0.0.1