This is a big one that is a placeholder for a lot of practices. The Agile approach is mainly a response to the “waterfall” model of software application development that occurs using a serialized process of discrete stages. For example, first the specification is written, then coders code, then testers test, then the application is deployed, and then we go back to updating the specification for new features. Each step in the process happens serially and in isolation. So, while the specification is written, the coders and testers wait. While the coders code, the testers wait, while the testers test, everyone waits, and so on.

Agile development tries to be more flexible and allow each stage to occur in parallel. Software that works is the top priority. Instead of waiting around for large chunks of time for the previous step to be perfect before handoff, each team iterates over shorter cycles, so things are always happening. Big chunks of work get broken down into smaller chunks that can be more easily estimated. Agile seeks to break down the walls between each group in the development cycle so that they work together and therefore reduce the time between deliverables. Collaboration with customers helps to define the final deliverable.

Note that the use of Agile methods does not necessarily mean your application is completed faster or with higher quality. Agile’s biggest strength is the way it deals with changes. In the waterfall model, any change would require running through the entire process all over again. Agile’s shorter cycles allow changes to be more easily incorporated into the final product. You might be using Agile already if you hear the words fail fast, release often, backlog, standup, or any phrase with the word continuous. Most modern development utilizes Agile to some extent. Figure 1-2 shows the canonical chart of the Agile development process.

There is a lot going on in Figure 1-2, but the basic idea is that quick iteration and constant interaction will accelerate the delivery of quality software.

Agile itself does not mandate how software is written; rather, it recommends several methodologies that fit well with the Agile philosophy. For example, “user stories” are plain sentences by “users” about what features they need from the application. These stories are ideally fed back into the product as feature requests for the application. A user is anyone who uses your application or API, from someone sitting at home to a developer in another group who can contribute to help define the feature set of the final application. Pair programming is another development methodology often associated with Agile. In its purest form, pair programming is two programmers sitting at the same desk, staring at the same monitor, with one keyboard and mouse, writing software together. While one programmer is typing, the other is actively debugging and thinking about the code. Two minds are typically better than one, so issues are found and resolved more quickly than if the two programmers were working in isolation.

Figure 1-2. The Agile development process (courtesy of Dbenson and VersionOne, Inc.)

Test-driven development (TDD) is a recommended practice of Agile software development. TDD wants you to write your tests first, before you write any code. These tests provide the expectations to which your code must conform. After you write tests that fail (as there initially is no code to make the tests work), you then start writing code that makes your tests pass. As your tests stay one step ahead of your development, you will never have any code that is not covered by a test. That is the theory, at least. In reality, what tends to happen is developers start to go down this path and initial tests are written, but the code soon overtakes the tests. Hey, at least you got some tests out of the bargain!

TDD clearly works best when you are starting a new project or module. It is also most successful if only unit tests are required. Writing full integration tests before any code exists is daunting! TDD also provides a great reason/excuse to rewrite existing legacy code. If a developer’s choice is “write a bunch of tests for already existing code” or “write your own new code starting with tests,” most likely the developer will choose the latter option. Of course, developers do not always have a choice; just do not expect happy faces and high fives from them if writing tests for an already existing codebase is the path chosen to move forward.

Regardless, TDD is not a bad thing; in fact, it can be a very good thing. TDD is great at beginnings, whether an entire application or a single module—everyone is excited to write new code, and if the “cost” of writing that new code is writing tests first, so be it. And as there is no code at the beginning, the “cost” of writing tests is minimal.

An interesting study in 2005 on Canadian undergraduates found that TDD made programmers more productive because they wrote more tests. While that is debatable, what is more interesting is that the researchers “also observed that the minimum quality increased linearly with the number of programmer tests, independent of the development strategy employed.”^[2] It is good to know that the number of tests is proportional to higher code quality. The conclusion one could draw is that any methodology that gets developers to write more tests before, during, or after coding is a very good thing.

Behavior-driven development (BDD) builds on TDD to provide developers and non-developers a common language to describe correct application and module behavior. The common language is just your everyday language. For example, instead of writing a test called testEmptyCart, you would provide a description that defines the behavior of the module under test, such as “the shopping cart should not allow you to check out if it is empty.” Using a common language to define tests or expectations allows anyone to more easily understand what is being tested, as well as helping to define what the tests and expectations should be.

BDD utilizes Agile user stories to define tests against the code. The user stories can then be directly translated into tests. The user stories typically must follow a specific template of the form: As a [someone] I want to [something] so that [result].

Each blank is filled in appropriately, as in a Yahoo! Mail user I want to attach a picture to my email so that my recipients can see it. This user story can then be translated into a set of feature requirements and tests for the Yahoo! Mail product.

BDD is great for formalized feedback from people not on your team (technical or not), to help you understand how your system should operate. The user stories can usually be directly translated into tests—and anything that promotes focused testing (and more of it) is a very good thing!

This book is intended to neither advocate nor explicate any development methodology, and by that measure I think it succeeds admirably. Waterfall, spiral, Agile, and other methodologies are all well and good, but none necessarily leads to testable code, let alone testable JavaScript. Similarly, TDD, BDD, and other forms of development also do not necessarily lead to testable JavaScript. What does lead to testable JavaScript? A commitment to writing clear, loosely coupled, and well-commented code that you know will be maintained by someone else will lead to testable JavaScript. Writing, reading, and maintaining testable JavaScript does not require test-driven, behavior-driven, or any other “-driven” development practices. However, following any practice that emphasizes tests along with code is a good thing. The most important thing to internalize is that the code you write does not exist in a vacuum. Any code you write professionally will be looked at, compiled, debugged, and finally used by not only yourself, but hopefully someone else too. In the end, you are writing code for other people to maintain, study, and use.

“Writing software is the hardest thing people do,” says Douglas Crockford, which means it is extremely important that software be as human-friendly as possible. Testable code is easier to test, which means it is easier to maintain, which means it is easier for people (yourself included) to understand it, which makes it easier to maintain, which in turn makes it easier to test.

We have gone in a circle, but it is a virtuous circle. There is no Platonic ideal of perfect code; testability, maintainability, and understandability are interlocked, and there are lots of opinions about what these things are and how to get there with software. However, finding and fixing bugs is much simpler with testable, maintainable, and understandable code. And you as a programmer will spend at least half of your time finding and fixing bugs, either in your code or in someone else’s, so be nice to yourself and try to make that time as pleasant as possible.

x = x + 1;

So “what” exactly is “testable” code? What does “maintainable” code look like? What kind of code is “understandable” code? Let us dig a bit deeper into those questions. We will see numerous examples of “what” all of this looks like throughout this book.

Understanding the “why” and the “what” leads us to the “how.” This book is primarily concerned with how you can write, test, and maintain testable, maintainable, and understandable code. Clearly, testing and maintaining code that is already testable, maintainable, and understandable will make your job easier. Starting with this solid foundation will make you much more productive, and productive people are happy people, and happy people are productive people! It’s one of those virtuous circles again. I like virtuous circles.

Unit tests are a developer’s first line of defense. Not only do unit tests force you, the developer, to understand your code, but they also help you to document and debug your code. Beyond unit testing, integration testing helps to ensure that everything is working together as planned—especially client-side JavaScript, which runs on many different browsers on an increasing number of platforms (desktops, tablets, and phones). Finally, performance testing and load testing help to ensure that your application is performing to specification. Each step up the testing ladder exercises your code at different levels of abstraction. Each test type finds bugs in different usage scenarios. Fully testing code requires tests at all levels of abstraction. And still you will have bugs in production; there is no magic bullet.

Regardless of the number of tests you conduct, debugging is a fact of life for software developers. Fortunately, JavaScript has some very nice tools that are constantly improving to help. Leveraging these tools will help make your debugging life easier, which is nice, as you will probably spend much more time debugging your code than writing it.

Whether you are debugging locally or remotely, many powerful tools are available for step-by-step debugging and resource management.

Content coupling, the tightest form of coupling, involves actually calling methods or functions on the external object or directly changing its state by editing a property of the external object. Any one of the following examples is a type of content coupling with the external object O:

O.property = 'blah'; // Changing O's state directly

// Changing O's internals
O.method = function() { /* something else */ };

// Changing all Os!
O.prototype.method = function() { /* switcheroo */ };

All of these statements content-couple this object to O. This kind of coupling scores a 5.

Slightly lower on the coupling spectrum is common coupling. Your object is commonly coupled to another object if both objects share a global variable:

var Global = 'global';
Function A() { Global = 'A'; };
Function B() { Global = 'B'; };

Here objects A and B are commonly coupled. This scores a 4.

Next up is control coupling, a slightly looser form of coupling than common coupling. This type of coupling controls how the external object acts based on a flag or parameter setting. For example, creating a singleton abstract factory at the beginning of your code and passing in an env flag telling it how to act is a form of control coupling:

var absFactory = new AbstractFactory({ env: 'TEST' });

This scores a big fat 3.

Stamp coupling is passing a record to an external object that only uses part of the record, like so:

// This object is stamp coupled to O
O.makeBread( { type: wheat, size: 99, name: 'foo' } );

// Elsewhere within the definition of O:
O.prototype.makeBread = function(args) {
    return new Bread(args.type, args.size);
}

Here we pass a record to the makeBread function, but that function only uses two of the three properties within the record. This is stamp coupling. Stamp coupling scores a 2.

The loosest coupling of them all is data coupling. This type of coupling occurs when objects pass messages to one another, with no transfer of control to the external object. We will investigate this much further in Chapter 3. Data coupling scores a measly 1.

The last form of coupling (and my personal favorite), with absolutely zero coupling whatsoever between two objects, is the famed “no coupling.” No coupling scores a perfect 0.

While not formally a part of the coupling jargon, the act of instantiating a nonsingleton global object is also a very tight form of coupling, closer to content coupling than common coupling. Using new or Object.create creates a one-way, tightly coupled relationship between the objects. What the creator does with that object determines whether the relationship goes both ways.

Instantiating an object makes your code responsible for that object’s life cycle. Specifically, it has just been created by your code, and your code must now also be responsible for destroying it. While it may fall out of scope when the enclosing function ends or closes, any resources and dependencies the object requires can still be using memory—or even be executing. Instantiating an object foists responsibilities on the creator of which you must be aware. Certainly, the fewer objects your code instantiates, the clearer your conscience will be. Minimizing object instantiations minimizes code complexity; this is a nice target to aim for. If you find that you are creating a lot of objects, it is time to step back and rethink your architecture.

It is interesting to note the type and amount of testing required to test the various levels of coupled code. Not too surprisingly, the more tightly coupled the code is, the more resources are required to test it. Let’s go through the levels.

Content-coupled code is difficult to test because unit testing wants to test code in isolation, but by definition content-coupled code is tightly coupled with at least one other object external to it. You need the entire set of unit-testing tricks here to try to test this code; typically you must use both mocked objects and stubs to replicate the environment within which this code expects to run. Due to the tight coupling, integration testing is also necessary to ensure that the objects work together correctly.

Commonly coupled code is easier to unit-test as the shared global variable can be easily mocked or stubbed out and examined to ensure that the object under test is reading, writing, and responding to that variable correctly.

Control-coupled code requires mocking out the controlled external object and verifying it is controlled correctly, which is easy enough to accomplish using a mock object.

Stamp-coupled code is easily unit-tested by mocking out the external object and verifying the passed parameter was correct.

Data-coupled code and noncoupled code are very easily tested through unit testing. Very little or nothing needs to be mocked or stubbed out, and the method can be tested directly.

Minimize coupling, and your testing will be easier.

YUIDoc is a Node.js package available via npm. Installation is easy:

% npm -g install yuidocjs

The yuidoc executable is now available to transform all of your beloved comments into pretty HTML. In this section, I will discuss version 0.3.28, the latest version available at the time of this writing.

YUIDoc comments follow the Javadoc convention of starting with /** and ending with */. In fact, you can run YUIDoc on any language whose block comment tokens are /* and */.

YUIDoc provides seven primary tags. Each comment block must contain one and only one of these primary tags; the exhaustive list of tags is available here.

Ideally, you should be able to write unit tests using only the function or method YUIDoc.

Generating YUIDoc from the yuidoc command-line tool is simple. YUIDoc, however, wants to work with directories, so unlike with JSDoc (discussed next), you are not able to generate one JavaScript file’s worth of documentation. But unless you are debugging the YUIDoc in your code, that is rarely done anyway.

A typical command line looks like this:

% yuidoc -o yuidoc -c src/yuidoc.json src

where yuidoc is the name of the output directory where all the HTML will go and src is the root of your JavaScript files to recurse over to generate the documentation. The yuidoc.doc configuration file can just be an empty JSON object for our purposes:

% cat src/yuidoc.json
{}

Here is a JavaScript file with YUIDoc notation:

/**
 * Provides some mathematical functions
 *
 * @class Math
 **/

/**
 * This function accepts two operands, 'a' and 'b' and returns
 * their sum (or concatenation if they are strings)
 *
 * @method sum
 * @param {Number or String} a first operand
 * @param {Number or String} b second operand
 * @return {Number or String} The 'summed' value
 */
exports.sum = function(a, b) { return a + b };

/**
 * This function accepts two operands, 'a' and 'b' and returns
 * their product
 *
 * @method product
 * @param {Number} a first operand
 * @param {Number} b second operand
 * @return {Number} The product
 */
exports.mult = function(a, b) { return a * b };

Running this JavaScript through YUIDoc generates a page similar to Figure 2-2.

Figure 2-2. Generated HTML from YUIDoc directives

This looks just like the API documentation for YUI3. I think YUIDoc generates nicer templates (with searching!) and its tag library is more JavaScript-friendly than that of JSDoc. Of course, feel free to play with both and decide which one works best for your project.

Similar to YUIDoc is JSDoc. It utilizes a similar but larger set of tags.

Google’s Closure Compiler leverages JSDoc tags when minifying, optimizing, and compiling your code, which is nice as you can kill two birds with one stone.

JSDoc is a little goofy to get set up. It is a Java program that relies on the locations of its JAR file and a set of template files. After downloading and unzipping the package, it is easiest to set two environment variables, JSDOCDIR and JSDOCTEMPLATEDIR. JSDOCDIR is set to be the directory where jsrun.jar exists, which is in the jsdoc-toolkit directory after the bundle has been unzipped. For starters—and maybe forever, unless you want to create your own HTML templates for JSDoc to use—JSDOCTEMPLATEDIR should point to $JSDOCDIR/templates/jsdoc to use the default templates provided by JSDoc.

Once you have set those two environment variables, you can use the jsrun.sh shell script provided by the distribution, located in $JSDOCDIR. So, your command line to JSDoc a file looks like this:

% /bin/sh $JSDOCDIR/jsrun.sh -d=<output dir> <JavaScript file>

This will generate a set of HTML files and place them into <output dir>. In this JSDoc-friendly JavaScript file, note the subtle differences between the JSDoc tags and the YUIDoc tags shown earlier:

/**
 * This function accepts two operands, 'a' and 'b' and returns
 * their sum (or concatenation if they are strings)
 *
 * @name sum
 * @function
 * @param {Number or String} a first operand
 * @param {Number or String} b second operand
 * @returns {Number or String} The 'summed' value
 */
exports.sum = function(a, b) { return a + b };

/**
 * This function accepts two operands, 'a' and 'b' and returns
 * their product
 *
 * @name product
 * @function
 * @param {Number} a first operand
 * @param {Number} b second operand
 * @returns {Number} The product
 */
exports.mult = function(a, b) { return a * b };

When run through JSDoc, like so:

/bin/sh $JSDOCDIR/jsrun.sh -d=jsdoc mySum.js

the code will output several HTML files into the jsdoc directory. The most interesting of the HTML looks like Figure 2-3.

Figure 2-3. HTML generated by jsdoc directives

It’s very cute, but the tags are the HTML output and are not as zesty as in YUIDoc. Your mileage will vary.

According to the product website, “Docco is a quick-and-dirty, hundred-line-long, literate-programming-style documentation generator”—quite a mouthful indeed. Docco is the parent of a family of programs that all do the same thing: pull out Markdown-styled comments from your source code and HTML-ize the comments in the left column matched with the syntax-highlighted code in the right column. This is best understood with an example; for instance, the Docco website is generated by Docco.

Rocco is a Docco clone written in Ruby that, strangely enough, does a smarter job of formatting JavaScript code than Docco (which is written in CoffeeScript). The Rocco website is (surprisingly) generated by Rocco.

The biggest hurdle to using Rocco is installing Ruby to run it if Ruby is not already available. The next dependency is Pygments, a syntax highlighting utility written in Python. Rocco will attempt to use the Pygments web service if it is not installed locally, but it is doubtful that you’ll want your code shipped across the wire to be syntax-highlighted using the Pygments web service. Pygments depends on Python, so once Python is installed Pygments can be installed like so:

% sudo easy_install Pygments

Rocco also needs a Markdown parser; take rdiscount for a spin:

% sudo gem install rdiscount

Finally, install Rocco:

% sudo gem install rocco

Now simply run Rocco on your code:

% rocco myJavascript.js

By default, a file of the same name but with an .html extension will be created in the current directory (you can change this with the -o option to specify another directory where the HTML file should be saved).

All comments are stripped from the source and placed on the left side of the resultant web page, lined up with the code it relates to on the right side of the generated HTML.

So, this basic JavaScript:

/**
 * This function accepts two operands, 'a' and 'b' and returns their
 * sum (or concatenation if they are strings)
 */
exports.sum = function(a, b) { return a + b };

/**
 * This function accepts two operands, 'a' and 'b' and
 * returns their product
 */
exports.mult = function(a, b) { return a * b };

generates the HTML page shown in Figure 2-4.

Figure 2-4. Generated HTML from Rocco directives

Pretty snazzy! Beyond YUIDoc or JSDoc, Rocco and friends provide a different view of your code.

So, the game is to have pieces join the hub and start firing, listening for, and responding to events. Instead of making method calls (which requires a local instantiation of an object, coupling, fan-out, and local mocking and stubbing), throw an event and (possibly) wait for the response (if you need one).

A hub can run wherever you like on the server side. Clients can connect to it and fire and subscribe to events.

Typically, browser-based clients fire events and server-based clients consume them, but of course any client can fire and consume events.

This architecture plays to JavaScript’s functional strengths and encourages small bits of tightly focused code with minimal dependencies. Using events instead of method calls greatly increases testability and maintainability by encouraging developers to write smaller chunks of code with minimal dependencies. Anything external to a module is provided as a service instead of being wrapped within a dependency. The only function calls should be to the hub or to methods local to the object or module.

Let’s take a look at some canonical login logic. Here is the standard Ajax-based login using the YUI framework:

YUI().add('login', function(Y) {
    Y.one('#submitButton').on('click', logIn);
    function logIn(e) {
        var username = Y.one('#username').get('value')
            , password = Y.one('#password').get('value')
            , cfg = {
                data: JSON.stringify(
                    {username: username, password: password })
            , method: 'POST'
            , on: {
                complete: function(tid, resp, args) {
                    if (resp.status === 200) {
                        var response = JSON.parse(resp.responseText);
                        if (response.loginOk) {
                            userLoggedIn(username);
                        } else {
                            failedLogin(username);
                        }
                    } else {
                        networkError(resp);
                    }
                }
            }
        }
        , request = Y.io('/login', cfg)
        ;
    }
}, '1.0', { requires: [ 'node', 'io-base' ] });

At 27 lines of code, that login isn’t too bad. Here is the equivalent using event-based programming (using the YUI Event Hub module):

YUI().add('login', function(Y) {
    Y.one('#submitButton').on('click', logIn);
    function logIn(e) {
        var username = Y.one('#username').get('value')
            , password = Y.one('#password').get('value')
        ;
        eventHub.fire('logIn'
          , { username: username, password: password }
          , function(err, resp) {
            if (!err) {
                if (resp.loginOk) {
                    userLoggedIn(username);
                } else {
                    failedLogin(username);
                }
            } else {
                networkError(err);
            }
        });
    }

}, '1.0', { requires: [ 'node', 'EventHub' ] });

This code is only 18 lines long, representing a whopping 33% code savings. But in addition to fewer lines of code, testing is simplified. To illustrate this, let’s conduct a unit test of the standard Ajax version and compare it to a unit test of the event-hub-based version. (We will discuss unit tests in detail in Chapter 4, so don’t get too bogged down in the syntax if you are not familiar with YUI Test. We’ll start with the Ajax version, beginning with the setup:

YUI().use('test', 'console', 'node-event-simulate'
  , 'login', function(Y) {

    // Factory for mocking Y.io
    var getFakeIO = function(args) {
        return function(url, config) {
            Y.Assert.areEqual(url, args.url);
            Y.Assert.areEqual(config.data, args.data);
            Y.Assert.areEqual(config.method, args.method);
            Y.Assert.isFunction(config.on.complete);
            config.on.complete(1, args.responseArg);
        };
    }
    , realIO = Y.io;

This is standard boilerplate YUI code that loads the external modules our tests depend on, including our login module, which we will be testing. The code also includes the factory for creating a mocked Y.io instance, which is YUI’s veneer over XMLHttpRequest. This object will ensure that the correct values are passed to it. Finally, we keep a reference to the real Y.io instance so that it can be restored for other tests.

Here is the test itself:

    var testCase = new Y.Test.Case({
        name: "test ajax login"
        , tearDown: function() {
            Y.io = realIO;
        }
        , testLogin : function () {
            var username = 'mark'
                , password = 'rox'
            ;

            Y.io = getFakeIO({
                url: '/login'
                , data: JSON.stringify({
                    username: username
                    , password: password
                })
                , method: 'POST'
                , responseArg: {
                    status: 200
                    , responseText: JSON.stringify({ loginOk: true })
                }
            });

            userLoggedIn = function(user) {
                Y.Assert.areEqual(user, username); };
            failedLogin  = function() {
                Y.Assert.fail('login should have succeeded!'); };
            networkError = function() {
                Y.Assert.fail('login should have succeeded!'); };

            Y.one('#username').set('value', username);
            Y.one('#password').set('value', password);
            Y.one('#submitButton').simulate('click');
        }
    });

The preceding code is testing a successful login attempt. We set up our fake Y.io object and mock the possible resultant functions our login module calls to ensure that the correct one is used. Then we set up the HTML elements with known values so that clicking Submit will start the whole thing off. One thing to note is the teardown function that restores Y.io to its original value. The mocking of Y.io is a bit clunky (although not horribly so), as Ajax only deals with strings and we need to keep track of the HTTP status from the server. For completeness, here is the rest of the test module, which is all boilerplate:

    var suite = new Y.Test.Suite('login');
    suite.add(testCase);

    Y.Test.Runner.add(suite);

    //Initialize the console
    new Y.Console({
        newestOnTop: false
    }).render('#log');

    Y.Test.Runner.run();
});

Let’s now look at a unit test for the event-based code. Here is the beginning portion:

YUI().use('test', 'console', 'node-event-simulate'
    , 'login', function(Y) {

    // Factory for mocking EH
    var getFakeEH = function(args) {
        return {
            fire: function(event, eventArgs, cb) {
                Y.Assert.areEqual(event, args.event);
                Y.Assert.areEqual(JSON.stringify(eventArgs),
                                   JSON.stringify(args.data));
                Y.Assert.isFunction(cb);
                cb(args.err, args.responseArg);
            }
        };
    };
});

Here we see the same boilerplate at the top and a similar factor for mocking out the event handler itself. Although this code is slightly cleaner, some unfortunate ugliness crops up when comparing the two objects for equality, as YUI does not provide a standard object comparator method.

Here is the actual test:

    var testCase = new Y.Test.Case({
        name: "test eh login"
        , testLogin : function () {
            var username = 'mark'
                , password = 'rox'
            ;

            eventHub = getFakeEH({
                event: 'logIn'
                , data: {
                    username: username
                    , password: password
                }
                , responseArg: { loginOk: true }
            });

            userLoggedIn = function(user) {
                Y.Assert.areEqual(user, username); };
            failedLogin  = function() {
                Y.Assert.fail('login should have succeeded!'); };
            networkError = function() {
                Y.Assert.fail('login should have succeeded!'); };

            Y.one('#username').set('value', username);
            Y.one('#password').set('value', password);
            Y.one('#submitButton').simulate('click');
        }
    });

This is very similar to the previous code. We get a mocked version of the event hub, prime the HTML elements, and click the Submit button to start it off. The exact same post-test boilerplate code present from the previous Ajax test is also necessary here to complete the example (refer back to that code if you want to see it again!).

This example illustrates that the base code and the test code are smaller for the event-based example, while providing more semantic usage and more functionality. For example, the event-based code handles cross-domain (secure or not) communication without any changes. There is no need for JSONP, Flash, hidden iframes, or other tricks, which add complexity to both the code and the tests. Serialization and deserialization are handled transparently. Errors passed as objects, not as HTTP status codes, are buried within the response object. Endpoints are abstracted away from URLs to arbitrary strings. And finally (and perhaps most importantly), this kind of event-based architecture completely frees us from the tyranny of instantiating and maintaining tightly coupled pointers to external objects.

The test code for Ajax requests really grows when using more of the features of XMLHttpRequest and Y.io, such as the success and failure callbacks, which also need to be mocked. There are more complex usages that require more testing complexity.

There are three possible responses to a thrown event: no response, a generic response, or a specific response. Using events for message passing is simplest when no reply is necessary. In a typical event system, sending events is easy but getting replies is problematic. You could set up a listener for a specific event directly tied to the event that was just fired. This approach is similar to giving each event a unique ID; you could then listen for a specifically named event containing the request ID to get the response. But that sure is ugly, which is why eventing has typically been relegated to “one-way” communication, with logging, UI actions, and notifications (typically signifying that something is now “ready”) being the most common event use cases. However, two-way asynchronous communication is possible using callbacks, which handle generic and specific responses. Let’s look at some examples.

Obviously, if no response is necessary, we can simply throw the event and move on:

eventHub.fire('LOG', { level: 'debug', message: 'This is cool' });

If a specific response to the thrown event is not necessary and a more generic response is sufficient, the remote listener can throw the generic event in response. For example, if a new user registers a generic USER_REGISTERED event, a generic response may be the only “reply” that is necessary:

// somewhere on server
eventHub.on('REGISTER_USER', function(obj) {
    // stick obj.name into user DB
    eventHub.fire('USER_REGISTERED', { name: obj.name });
});

// somewhere global
eventHub.on('USER_REGISTERED', function(user) {
    console.log(user.name + ' registered!');
});

// somewhere specific
eventHub.fire('REGISTER_USER', { name: 'mark' });

In this example, the REGISTER_USER event handler is sitting on a server writing to a database. After registering the user by adding him to the database, the handler throws another event, the USER_REGISTERED event. Another listener listens for this event. That other listener then handles the application’s logic after the user has been registered—by updating the UI, for example. Of course, there can be multiple listeners for each event, so perhaps one USER_REGISTERED event can update an admin panel, another can update the specific user’s UI, and yet another can send an email to an administrator with the new user’s information.

Finally, in some cases a specific response sent directly back to the event thrower is required. This is exactly the same as making a method call, but asynchronously. If a direct reply is necessary, an event hub provides callbacks to the event emitter. The callback is passed as a parameter by the event emitter to the hub. For example:

// Somewhere on the server
eventHub.on('ADD_TO_CART'
    , function(userId, itemId, callback) {
        d.cart.push(itemId);
        callback(null, { items: userId.cart.length });
});

// Meanwhile, somewhere else (in the browser, probably)
function addItemToCart(userId, itemId) {
    eventHub.fire('ADD_TO_CART'
      , { user_id: userId, item_id: itemId }
      , function(err, result) {
        if (!err) {
                console.log('Cart now has: ' + result.cart.items + ' items');
        }
    });
}

Here, we fire a generic ADD_TO_CART event with some information and we wait for the callback. The supplied callback to the event hub is called with data provided by the listener.

How do event-based architectures compare with Model-View-Controller (MVC) approaches? They are actually quite similar. In fact, event-based architectures help to enforce the separation of concerns and modularity that MVC advocates.

But there are a few differences between the two, with the biggest difference being that in event-based architectures models are turned inside out, eliminated, or pulled apart, depending on how you like to think about these things. For example, using MVC, a Model class is instantiated for each database row; this class provides the data and the methods that operate on that data. In an event-based architecture, models are simple hashes storing only data; this data is passed using events for listeners (you can call them models, I suppose) to operate on. This separation of data and functionality can provide greater testability, memory savings, greater modularity, and higher scalability, all with the benefits of putting the data and methods together in the first place. Instead of lots of individual instantiated Model objects floating around, there are lots of data hashes floating around, and one instantiated object to operate on them all.

The controller is now simply the event hub, blindly passing events between views and models. The event hub can have some logic associated with it, such as being smarter about where to pass events instead of passing them blindly to all listeners. The event hub can also detect events being thrown with no listeners and return an appropriate error message. Beyond event-specific logic, the controller in an event-centered world is just a dumb hub (perhaps upgraded to a slightly smarter switch, exactly like Ethernet hubs and switches).

Views, perhaps the least changed, have data pushed to them via events instead of querying models. Upon a user-initiated event, views “model” the data and throw the appropriate event. Any required UI updates are notified by events.

Storing data along with the methods that operate on it is the basic tenet of object-oriented programming. Another tenet of object-oriented programming is reuse. The theory is that more generic superclasses can be reused by more specific subclasses. Object-oriented methodology introduces another form of coupling: inheritance coupling. There is nothing stopping an event-based programmer from using object-oriented principles when designing her listeners, but she will encounter a few twists.

For starters, the entire application is not based on object-oriented programming. In addition, there are no chains of interconnected objects connected only by inheritance or interface coupling, and the application is not running in a single thread or process, but rather in multiple processes. But the biggest difference is that the data is not stored within the objects. Singleton objects are instantiated with methods that operate on the data, and data is passed to these objects to be operated on.

There are no “public,” “private,” or “protected” modifiers—everything is private. The only communication with the “outside” world is via the event-based API. As these objects are not instantiated by dependents, there is no need to worry that an external object will mess with your internals. There are no life-cycle issues, as the objects live for the entire life of the application, so constructors (if there are any) are called once at the beginning and destructors are unnecessary.

Event-based architectures facilitate Software as a Service (SaaS). Each independent piece can join the event hub to provide a service in isolation from all the other services used to create the application. You can easily imagine a repository of services either available for download or accessible over the Internet for your application to use. Your application would connect to their hub to access their services. The “API” for these services is a unique event name with which to call exposed actions and the data that must be present in the event. Optionally, the service can either fire another event upon completion or use the callback mechanism for responses, if any response is necessary.

An event hub creates a super single point of failure: if the hub goes down, your application goes down with it. You need to either put a set of event hubs behind a load balancer, or build failing over to another event hub into your application. This is no different from adding more web servers; in fact it’s actually simpler, as you do not have to worry about the same-origin policy using socket.io.

A lot of events being broadcast to all clients can potentially result in a lot of traffic. Guards should be put in place to ensure that events that are meant to be consumed locally do not get sent to the hub. Further, the hub itself can act more like a switch than a hub if it knows which client is listening for an event, sending it directly there instead of broadcasting it.

Whereas misspelling a function or method name will result in a runtime error, the compiler cannot check string event names for misspellings. Therefore, it is highly recommended that you use enumerations or hashes for event names instead of typing them over and over. A nice way to get runtime checking of your event names is to do something like this:

// Return an object with 'on' and 'fire' functions for the specified
// eventName
hub.addEvent = function(eventName) {
    var _this = this;
    this.events[eventName] = {
        on: function(callback) {
            _this.on.call(_this, eventName, callback);
         }
         , fire: function() {
             Array.prototype.unshift.call(arguments, eventName);
             this.fire.apply(_this, arguments);
         }
    };
    return this.events[eventName];
};

You would use this code as follows:

var clickEvent = hub.addEvent('click');
clickEvent.on(function(data) { /* got a click event! */ });
clickEvent.fire({ button: 'clicked' }); // fired a click event!

Now you have runtime checking of event names.

If you’re afraid that random unwashed masses will connect to your event hub and inject any events they want, don’t be; the event hub implementation requires “trusted” clients to authenticate with the hub.

If you want to encrypt event hub connections, you can build your event hub solution using socket.io, which supports encrypted connections.

State, which typically is provided by a web server via a session cookie, moves from the web server to a module. Upon web application load, a new session object can be created and persisted completely independently of a web server. The client-side JavaScript writes the session token as a cookie itself, which is then available to the web server if it needs to serve authenticated-only content. The event hub itself injects the session into events, making it impossible for one session to masquerade as another.

Trusted (typically server-side) modules get the session key, and therefore the state, from untrusted (typically client-side) events, passed as a parameter or hash field.

A monolithic application typically has all the server-side logic intertwined with the HTTP server. Deploying a new version involves pushing the entire application logic at once and restarting the web server. To upgrade a portion of the application, everything must be pushed. The logic for event-based applications is completely separate from the web server; in fact, the logic of the application resides in many different independent modules. This makes pushing new versions of code much simpler, as the modules can be updated and deployed completely independently of one another and of the web server. Although there are more “moving parts” to deal with, you gain much finer-grained control of your deployment and code.

So, how can you safely stop a listener without dropping an event? You can use unicast events and broadcast events. An event switch is necessary for safely shutting down listeners without missing an event.

Unicast events

Unicast events, such as depositMoney in the following code, have only one listener. In this case, a listener must notify the event switch that this event is a unicast event and that it is the (only) listener for it. When we’re ready to upgrade, we need to start the new version of the module, which announces to the event switch that it is now the sole listener for the event. The event switch will notify the older module that it has been replaced, and that module can now shut down cleanly after handling any outstanding events. No events are lost; the event switch will switch the unicast event over to the new listener, but the switch will remain connected to the original listener to handle any callbacks or events emitted by that listener while it finishes handling any outstanding events. In this way, we have successfully shut down the old listener and brought up a new one with no loss in service:

eventSwitch.on('depositMoney', function(data) {
    cash += data.depositAmount;
    eventSwitch.emit('depositedMoney', cash);
}, { type: 'unicast' });

When we begin listening for this event, this code informs the event switch that this is a unicast event, and that all events of this name must go only to this listener. All we have done is add a third parameter to the on method with some metadata about the event, which the client passes to the switch.

Meanwhile, the switch will replace the current listener for this event (if there is one) with the new listener, and will send a “hey, someone bumped you” event to the previous listener (again, if there was one). Any listener for this event should have another listener for the “go away” event too:

eventHub.on('eventClient:done', function(event) {
    console.log('DONE LISTENING FOR ' + event);
    // finish handling any outstanding events & then safely:
    process.exit(0);
});

The eventClient:done event signifies that this listener will no longer receive the specified event, and that when it is done processing any outstanding events it can safely shut down or can continue to handle events it is still listening for.

The atomic operation of the event switch ensures that no events are dropped and none are sent to a listener that has been replaced. To understand this more fully, take a look at Figure 3-3. In the figure, time flows from the top of the picture to the bottom. The module on the left registers for the unicast event, and events are delivered to it. Then the updated module on the right registers for that same unicast event. The first module receives the done event; all new event requests are sent to the module on the right, while the module on the left finishes handling any current events and then shuts down. The updated module continues to serve event requests until another updated module notifies the hub that it is now responsible for the unicast event.

Figure 3-3. Event switch flow for uninterrupted unicast event handling

eventHub.on('eventClient:done', function(event) {
    console.log('I have been advised to stop listening for event: '
      + event);
    eventHub.removeAllListeners(event);
});

This sample implementation of an event switch with clients for Node.js, YUI3, and jQuery based on socket.io can be installed using npm:

% npm install EventHub

Built on top of socket.io, this implementation provides a centralized hub running under Node.js and provides event callback functions for direct responses. Most events do not require a direct callback, so be careful and do not overuse that feature. Think carefully about receiving a direct callback versus firing another event when the action is complete.

After EventHub is installed, simply start the hub:

% npm start EventHub

This starts the event switch listening on port 5883 by default. All clients need to point to the host and port where the hub is listening. Here is a Node.js client:

var EventHub = require('EventHub/clients/server/eventClient.js');
    , eventHub = EventHub.getClientHub('http://localhost:5883');
eventHub.on('ADD_USER', function(user) {
    // Add user logic
    eventHub.fire('ADD_USER_DONE', { success: true, user: user });
});

These lines of code instantiate an event hub client connecting to the previously started event hub (running on the same machine as this client, but of course it can run on another host). Simply execute this file:

% node client.js

Now any ADD_USER event fired by any client will be routed to this function. Here is a client running in a browser using YUI3:

<script src="http://yui.yahooapis.com/3.4.1/build/yui/yui-min.js">
  </script>
<script src="/socket.io/socket.io.js"></script>
<script src="/clients/browser/yui3.js"></script>
<script>
    YUI().use('node', 'EventHub', function(Y) {
        var hub = new Y.EventHub(io, 'http://myhost:5883');
        hub.on('eventHubReady', function() {
            hub.on('ADD_USER_DONE', function(data) { };

             ... TIME PASSES ...

            hub.fire('ADD_USER', user);
        });
    });
</script>

After loading the YUI3 seed, socket.io, and the YUI3 EventHub client, a new EventHub client is instantiated, and when it’s ready we listen for events and at some point fire the ADD_USER event. It’s that simple.

Here is the same example using jQuery:

<script src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js">
  </script>
<script src="/socket.io/socket.io.js"></script>
<script src="/clients/browser/jquery.js"></script>
<script>
    var hub = new $.fn.eventHub(io, 'http://myhost:5883');
    hub.bind('eventHubReady', function() {
        hub.bind('ADD_USER_DONE', function(data) { });
            ... TIME PASSES ...
        hub.trigger('ADD_USER', user);
    });
</script>

The process is the same: load up the jQuery seed, socket.io, and the jQuery EventHub client. The EventHub is provided as a jQuery plug-in and uses the jQuery event syntax of bind and trigger.

Any event emitted by any client can have an optional callback function as the last parameter in the event arguments:

hub.fire('CHECK_USER', 'mark',
    function(result) { console.log('exists: ' + result.exists); });

And any responder to this event is given a corresponding function as the last parameter in the event argument list to pass back any arbitrary data:

hub.on('CHECK_USER', function(username, callback) {
    callback({ exists: DB.exists(username) });
});

This is slick! The callback will execute the remote function in the caller’s space with the callee’s provided data. The data is serialized as JSON, so do not get too crazy, but if necessary you can receive a targeted response to the event you fired!

You can also use the addEvent helper for compile-time checking of event names using YUI3:

var clickEvent = hub.addEvent('click');
clickEvent.on(function(data) { /* got a click event! */ });
clickEvent.fire({ button: 'clicked' }); // fired a click event!

This is exactly as outlined earlier. In the jQuery world, you use bind and trigger instead:

var clickEvent = hub.addEvent('click');
clickEvent.bind(function(data) { /* got a click event! */ });
clickEvent.trigger({ button: 'clicked' }); // triggered a click event!

Finally, you can use event switch features for unicast events:

hub.on('CHECK_USER', function(username, callback) {
    callback({ exists: DB.exists(username) });
}, { type: 'unicast' });

You can kick off any other listeners for broadcast events, like so:

// this goes to everyone BUT me...
hub.fire('eventClient:done', 'user:addUser');

To play nicely you must listen for this event:

hub.on('eventClient:done', function(event) {
    console.log('DONE LISTENING FOR ' + event);
    hub.removeAllListeners(event);
});

This will be fired by the event switch itself when a new unicast listener comes online or by a user module when broadcast modules are being upgraded.

Trusted unicast listeners receive session data from thrown events. A “trusted” client connects to the hub using a shared secret:

eventHub = require('EventHub/clients/server/eventClient.js')
  .getClientHub('http://localhost:5883?token=secret)

Now this client can listen for unicast events. All unicast events receive extra session data in their event callbacks:

eventHub.on('user', function(obj) {
    var sessionID =  obj['eventHub:session'];
    ...
});

The eventHub:session key is a unique string (a UUID) that identifies this session. Trusted listeners should utilize this key when storing and accessing session data.

Session keys are completely transparent to untrusted clients. Both the YUI3 and jQuery clients persist the session key into a cookie.

The HTTP server, just a trusted event hub client, leverages the session key from the cookie on an HTTP request when deciding to send trusted, authenticated, or personalized content to the browser.

The socket.io library has clients in many languages, so services you use are not limited to only JavaScript client implementations. It is relatively trivial (I hope!) for users of other languages supported by socket.io to write an EventHub client using their language of choice.

A unit test should load only the bare minimum needed to actually run the test. Any extra code may influence the test or the code being tested, and can cause problems. Typically, unit tests exercise a single method. That method is probably part of a file containing a class or module. That physical unit of code will have to be loaded. Unfortunately, not only does the method under test probably depend on other functions and methods in that file, but it likely has external dependencies (i.e., dependencies in another file) as well.

To avoid loading external dependencies, we can use mocking, stubbing, and test doubles. I will provide details about these strategies later, but for now it’s important to note that they are all used in an attempt to keep the code under test isolated from other pieces of code as much as possible.

Unit testing tests the smallest amount of code possible—a method, and nothing else. For that to be feasible, your test code must strive to isolate that method as much as possible.

The scope of a unit test—what your test is actually testing—must be small. A fully isolated method allows the scope of the test to be as small as possible. Good unit tests test only one method; they should not rely on other methods being called or used. At the bottom level of a single unit test, a single assertion should rely on only the method being tested and any mocks, stubs, or doubles needed for the method to work.

Unit tests are cheap; you should have a lot of them. Just as a “regular” method should not try to do more than one thing, neither should a unit test. Try to test and load the minimal amount of code necessary to successfully execute a unit test for your application. Unit tests typically focus at the level of a single function or method; however, it is up to you to determine the “unit” size that makes the most sense for your testing.

Before we go into further detail, we need to take a step back. It is impossible to write good unit tests unless you know exactly what you are testing and what the result should be. What defines what the result should be? The tests? Having to read and understand tests (if they even exist) to discern how a function should work is not ideal. The comments define what the result should be. This may not be ideal either, if the comments are not kept up to date. So do you have two places to keep up to date—the tests and the comments? Yes, you do. Utilizing test-driven development (TDD) to write tests before code does not obviate the need for comment blocks above functions.

/*
 * This function adds two numbers, otherwise return null
 *
 * @param a first Number to add
 * @param b second Number to add
 * @return the numerical sum or null
 */
function sum(a, b) {
    return a + b;
}

Now that we have a well-defined function, let’s test the “correct” case. In this instance, we will pass in various flavors of two numbers. Here are the Y.Assert statements:

Y.Assert.areSame(sum(2, 2), 4, "2 + 2 does not equal 4?");
Y.Assert.areSame(sum(0, 2), 2, "0 + 2 does not equal 2?");
Y.Assert.areSame(sum(-2, 2), 0, "-2 + 2 does not equal 0?");
Y.Assert.areSame(sum(.1, .4), .5, ".1 + .4 does not equal .5?");

The preceding code is not earth-shattering; it just tests the basic cases, which is how this function will be called 99% of the time (answering the question, “Does the function do at a very basic level what it claims it does?”). These tests should be the easiest part of your testing, passing in good data and receiving good data back. These should be your first set of tests as these cases are by far the most common. This is where unit tests catch the most bugs; functions that do not fulfill their contract (from the function definition) are obviously broken.

Positive tests should be the first unit tests you write, as they provide a baseline of expected functionality upon which negative and bounds testing can be built. Here, you want to test all the common cases and permutations of how the function is actually supposed to be called and used.

Negative testing will help locate those hard-to-find bugs typically manifested by the code blowing up somewhere far away from where the bug actually is. Can the code handle values it is not expecting? These tests pass in parameters not expected or wanted by the function under test and ensure that the function under test handles them properly. Here is an example:

Y.Assert.areSame(sum(2),null));
Y.Assert.areSame(sum('1', '2'), null));
Y.Assert.areSame(sum('asd', 'weoi'), null));

This test quickly reveals that our sum function is not behaving properly. The key is that we know what “properly” is for the sum function: it should be returning null for non-numbers. Without the comment block describing this function’s behavior, we would have no idea whether this function was misbehaving.

Negative testing will typically not find the same number of bugs as positive testing, but the bugs negative testing does find are usually nastier. These are the hard-to-find bugs when something is not working at a much higher level. They test corner cases, or cases when unexpected things happen. In such situations, what does the function do? Besides meeting its contract, will it behave sanely with unexpected input or state?

Code coverage is a measure, typically a percentage, of the lines of code executed versus not executed. It is generally used to view how much code is touched by any given test. More tests can be written to “cover” more uncovered lines of code, typically to a certain percentage. We will discuss code coverage in more depth in Chapter 5, but for now, suffice it to say that code coverage is another key to effective unit tests. While code coverage can be misleading when the percentages are high, it is much more applicable (and scary) when the covered percentage is low. A unit test with less than 50% code coverage is a red flag; 60% to 80% code coverage is the sweet spot, and anything over 80% is gravy. The law of diminishing returns can apply to unit testing when trying to get unit tests above 80% coverage. Remember, unit testing is not the only arrow in your QA quiver, but it is one of the few QA metrics that developers are responsible for. In Chapter 5, we will look at how to measure and visualize code coverage.

It is important that code coverage information be generated automatically, without any human intervention. Once people get involved, things deteriorate rapidly. The process for generating code coverage must be seamless.

We touched on the problem with dependencies earlier in the book. Almost every function has external dependencies that unit testing does not want to test. Unit testers can extract dependencies by utilizing mocks and stubs. Note that I said, “Unit testers can extract” here, because the author of the code under test also has several tools to extract dependencies from code, as detailed in Chapter 2. Once all of those avenues have been exhausted, the burden falls on the unit tests to isolate the code in question for testing.

Use of command query separation highlights the differences between mocks and stubs: mocks are used for commands and stubs are used for queries.

// actual production code:
function buyNowClicked(event) {
    hub.fire('addToShoppingCart', { item: event.target.id });
}
Y.one('#products').delegate('click', buyNowClicked, '.buy-now-button');

/* ... and in your test code: */
testAddToShoppingCart: function() {
    var hub = Y.Mock();
    Y.Mock.expect(hub,
         {
          method: "fire"
          , args: [ "addToShoppingCart" , Y.Mock.Value.String]
         }
    );
    Y.one('.buy-now-button').simulate('click');
    Y.Mock.verify(hub);

function addToShoppingCart(item) {
    if (item.inStock()) {
        this.cart.push(item);
        return item;
    } else {
        return null;
    }
}

testAddOk: function() {
    var shoppingCart = new ShoppingCart()
    , item = { inStock: function() { return true; } }
    , back = shoppingCart.addToShoppingCart(item)
    ;

    Y.Assert.areSame(back, item, "Item not returned");
    Y.ArrayAssert.contains(item, shoppingCart.cart, "Item not in shopping cart"); 
}
, testAddNok: function() {
    var shoppingCart = new ShoppingCart()
        , item = { inStock: function() { return false; } }
        , back = shoppingCart.addToShoppingCart(item)
    ;

    Y.Assert.isNull(back, "Item returned is not null");
    Y.ArrayAssert.isEmpty(shoppingCart.cart, "Cart not empty!");
}

            , testWithSpy: function() {
                var origSum = sum
                    , sumSpy = function(a, b) {
                        Y.Assert.areSame(a, 2, 'first arg is 2!');
                        Y.Assert.areSame(a, 9, 'second arg is 9!');
                        return origSum(a, b);
                    }
                ;
                sum = sumSpy;
                Y.Assert.areSame(sum(2, 9), 11
                  , '2 + 9 does not equal 11?');
                sum = origSum;  // reset it (or use teardown)
            }

JavaScript relies heavily on events. Asynchronous testing involves suspending the testing flow and waiting for an event to fire, then resuming the flow in the event handler, probably with an assert or two thrown in for good measure.

testAsync: function () {
    var test = this, myButton = Y.one('#button');
    myButton.on('click', function() {
         this.resume(function() {
              Y.Assert.isTrue(true, 'You sunk my battleship!');
         });
    }
    myButton.simulate('click');
    this.wait(2000);
}

hub.on('log', function(severity, message) {
    console.log(severity + ': ' + message);
});

console = Y.Mock();
testLogHandler: function () {
    var sev = 'DEBUG', message = 'TEST';
    Y.Mock.expect(console, { method: log
      , arguments: [ sev, message ] });
    hub.fire('log', sev, message);
    this.wait(function() {
        Y.Mock.verify(console);
    }, 1000);
}

PhantomJS is a headless WebKit browser—that is, a browser that is accessed programmatically. This is an excellent sandbox within which to run unit tests without having a browser up and running somewhere. Note that unit tests typically focus on core functionality abstracted from the UI. Obviously, PhantomJS cannot and does not attempt to handle all the various CSS levels as they are implemented in each browser (although it is very up to date with most standards). Testing fancy CSS or browser-specific CSS requires that browser, and it is unclear whether a unit test is even a valid way to test this type of functionality. That being said, PhantomJS/WebKit can handle a ton of modern features; only the latest cutting-edge CSS 3D transformations, local storage, and WebGL are not supported. Of course, what is supported all depends on the version of WebKit used when building PhantomJS, which is constantly evolving and adding new features.

PhantomJS no longer requires an X server running anywhere, so setup cannot be easier! Simply download the binary for your operating system and you are ready to go. You can also compile phantomjs from source, but prepare to wait awhile, as a good chunk of Qt must be compiled as well. The actual phantomjs binary is tiny compared to the giant chunk of required Qt.

Here is our complex JavaScript file to test in sum.js:

YUI().add('sum', function(Y) {
    Y.MySum = function(a, b) { return a + b };
});

Once you are set up, running your YUI tests through PhantomJS is easy with one little trick. Here again is our HTML glue for the sum tests, with a single addition:

<html>
    <head>
        <title>Sum Tests</title>
    </head>
    <body class="yui3-skin-sam">
        <div id="log"></div>
        <script src="http://yui.yahooapis.com/3.4.1/build/yui/yui-min.js">
         </script>
         <script src="sum.js"></script>
         <script src="phantomOutput.js"></script>
         <script src="sumTests.js"></script>
    </body>
</html>

And here’s another JavaScript file to be loaded, phantomOutput.js, which defines a small YUI phantomjs module:

YUI().add('phantomjs', function(Y) {
    var TR;
    if (typeof(console) !== 'undefined') {
        TR = Y.Test.Runner;
        TR.subscribe(TR.COMPLETE_EVENT, function(obj) {
            console.log(Y.Test.Format.JUnitXML(obj.results));
        });
    }
});

The sole purpose of this module is to output test results, in JUnit XML format, to the console upon test completion (YUI supports other output formats that you can use instead; use whatever your build tool understands—for example, Hudson/Jenkins understands JUnit XML). This dependency must be declared in your test file. Here is sumTests.js:

YUI({
    logInclude: { TestRunner: true },
}).use('test', 'sum', 'console', 'phantomjs', function(Y) {

    var suite = new Y.Test.Suite('sum');
    suite.add(new Y.Test.Case({
        name:'simple test',
        testIntAdd : function () {
            Y.log('testIntAdd');
            Y.Assert.areEqual(Y.MySum(2 ,2), 4);
        },
        testStringAdd : function () {
            Y.log('testStringAdd');
            Y.Assert.areEqual(Y.MySum('my', 'sum'), 'mysum');
        }

    }));

    Y.Test.Runner.add(suite);

    //Initialize the console
    var yconsole = new Y.Console({
        newestOnTop: false
    });

    yconsole.render('#log');
    Y.Test.Runner.run();
});

PhantomJS will pick up the console output and can then persist it to a file for later processing. Unfortunately, including the phantomjs module in your tests is not ideal. In Chapter 8 we will make this process more dynamic.

Here is the PhantomJS script to grab the test output:

var page = new WebPage();
page.onConsoleMessage = function(msg) {
    console.log(msg);
    phantom.exit(0);
};
page.open(phantom.args[0], function (status) {
    // Check for page load success
    if (status !== "success") {
        console.log("Unable to load file");
        phantom.exit(1);
    }
});

That was quite simple! This PhantomJS script takes the URL to the “glue” HTML test file as the only command-line parameter, loads it up, and, if successful, waits to capture the console output. This script just prints it to the screen, but if you’re running it as part of a larger process you can redirect the standard output from this script to a file, or this PhantomJS script itself can write the output to a file.

PhantomJS has no access to the JavaScript running on the loaded page itself, so we utilize the console to pass the test output from the page being loaded back to PhantomJS-land, where it can be persisted.

Here is how I ran the whole thing against some tests for a sample Toolbar module in the JUTE repository (more on that later) on my Mac:

% phantomjs ~/phantomOutput.js sumTests.html

Here is the output I received (although not fancily formatted):

<?xml version="1.0" encoding="UTF-8"?>
  <testsuites>
    <testsuite name="simple test" tests="2" failures="0" time="0.005">
      <testcase name="testIsObject" time="0"></testcase>
      <testcase name="testMessage" time="0.001"></testcase>
    </testsuite>
  </testsuites>

This is the JUnit XML output for the two unit tests that were executed.

Adding snapshots, so you can actually see what happened, is easy. Here is the whole script with snapshot support added. The only difference is that here we “render” the output after any console output:

var page = new WebPage();
page.viewportSize = { width: 1024, height: 768 };

page.onConsoleMessage = function(msg) {
    console.log(msg);
    setTimeout(function() {
        page.render('output.png');
        phantom.exit();
    }, 500);
};

page.open(phantom.args[0], function (status) {
    // Check for page load success
    if (status !== "success") {
        console.log("Unable to load file");
        phantom.exit(1);
    }
});

First I set the viewport size, and after getting the test results the page is rendered into a PNG file (this needs to be wrapped in a timeout block to give the render step time to finish before exiting). This script will generate snapshots after each test. PhantomJS can also render PDF and JPG files. Figure 4-2 shows our lovely snapshot.

Mighty beautiful! By default, PhantomJS backgrounds are transparent, but we can clearly see the YUI Test output as it went to the <div id="log"> element in the HTML.

But wait! What about those awesome log messages YUI is outputting to the logger? We want to capture those too! We need to revisit the phantomjs YUI module:

YUI().add('phantomjs', function(Y) {

    var yconsole = new Y.Console();
    yconsole.on('entry',
        function(obj) {
            console.log(JSON.stringify(obj.message));
        }
    );

    if (typeof(console) !== 'undefined') {
        var TR = Y.Test.Runner;
        TR.subscribe(TR.COMPLETE_EVENT, function(obj) {
            console.log(JSON.stringify(
                { results: Y.Test.Format.JUnitXML(obj.results) }));
        });
    }
}, '1.0', { requires: [ 'console' ] });

Figure 4-2. PhantomJS screenshot

The biggest addition is the Y.Console object we’ve created solely to capture YUI Test’s logging messages. Listening for the entry event gives us all the messages in an object, which we stringify using JSON (note that the JSON object is included in WebKit; this JavaScript is running the PhantomJS WebKit browser).

Now two types of messages emitted to the console are passed “back” to our PhantomJS script: logging messages and the final JUnit XML results. Our PhantomJS server-side code must keep track of both types of messages.

Here is the first message:

{
    "time":"2012-02-23T02:38:03.222Z",
    "message":"Testing began at Wed Feb 22 2012 18:38:03 GMT-0800
      (PST).",
    "category":"info",
    "sourceAndDetail":"TestRunner",
    "source":"TestRunner",
    "localTime":"18:38:03",
    "elapsedTime":24,
    "totalTime":24
}

It’s not too exciting by itself, but the entire list of messages together is a great resource to dump into a log for each test suite. Details of message properties are available at the YUI website.

Here is the updated onConsoleMessage function from the PhantomJS script (that function is the only thing that has changed in the script):

page.onConsoleMessage = function(msg) {
    var obj = JSON.parse(msg);
    if (obj.results) {
        window.setTimeout(function () {
            console.log(obj.results);
            page.render('output.png');
            phantom.exit();
        }, 200);
    } else {
        console.log(msg);
    }
};

Besides parsing the JSON from the console output, the script now only exits when it gets the final test results. Of course, you need to ensure that nothing else (such as your tests or the code you are testing) is writing to console.log! You could also get crazier and take a snapshot before/during/after each test to view the actual test progress (you will know what stage each test is at due to the log messages).

PhantomJS is an excellent way to run your unit tests during an automated build process. During a build, you can feed this script a list of files/URLs for PhantomJS to execute in the WebKit browser. But you should also run your unit tests in “real” browsers at some point before pushing code out to your production environment. We’ll look at that next.

Using Selenium Remote Control (RC) or Selenium2 (WebDriver), you can farm out your unit tests to real browsers: either a browser running on your local machine or one running remotely. Running the Selenium JAR on a machine with Firefox, Safari, Chrome, or IE installed, you can easily launch your unit tests in that browser and then capture the results to be persisted locally. Selenium2/WebDriver is the preferred/current tool provided by Selenium; do not choose Selenium RC if you are just getting started with Selenium.

Here is how it works. Start Selenium somewhere where the browser in which you want to run your tests is installed. To do this you must download the latest version of the Selenium JAR from the SeleniumHQ website. You want the latest version of the Selenium server, which at the time of this writing is version 2.28. Now fire it up:

% java -jar ~/selenium-server-standalone-2.28.0.jar

This will start the Selenium server on the default port of 4444. You will need to reach this port from whatever machine you run the Selenium client on, so keep that firewall open. You can change this port with the -port option.

Now that the Selenium server is up and running, you need to tell it to open a browser and fetch a URL. This means you need a web server running somewhere to serve your test files. It doesn’t need to be anything fancy—remember, these are only unit tests; you are not serving up your entire application. However, it is easiest to have your test code under the same document root as your production code to make serving the tests easier during development. Keep in mind that you probably do not want to actually push your tests into production. Therefore, a nice setup is a test directory under your document root containing a mirror of your production directory structure with the tests for the corresponding modules in the same place in the mirrored hierarchy. When bundling for production, simply do not include the test directory. The structure looks like Figure 4-3.

Figure 4-3. Source code directory layout for testability

As you can see in Figure 4-3, the test tree mirrors the src tree. Each leaf in the test hierarchy contains (at least) two files: the JavaScript tests and the HTML glue file for those tests. The HTML glue file for test_user_view.html looks like this:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
    <head>
        <meta http-equiv="Content-Type"
          content="text/html; charset=ISO-8859-1">
        <title>User View Tests</title>
    </head>
    <body class="yui3-skin-sam">
        <h1>Test User View</h1>
        <div id="log" />
        <script src="http://yui.yahooapis.com/3.4.0/build/yui/yui-min.js">
        </script>
        <script src="../../../src/frontend/user/userView.js"></script>
        <script src="test_user_view.js"></script>
    </body>
</html>

This HTML uses relative paths to pull in the file/module to be tested: user_view.js. When the local web server serves, this file all the local files are found and the tests are run.

We now have a URL to feed to Selenium so that the remote browser controlled by Selenium can fetch and run our test(s). Using the webdriverjs Node.js npm package, we can easily send URLs to a Selenium server to be executed:

var webdriverjs = require("webdriverjs")
    , url = '...';

browser = webdriverjs.remote({
    host: 'localhost'
    , port: 4444
    , desiredCapabilities: { browserName: 'firefox' }
});
browser.init().url(url).end();

This code will contact the Selenium server running on port 4444 at localhost and tell it to fire up Firefox and load the specified URL. We’re halfway there! All we need to do now is capture the test output—those useful log messages that YUI Test emits—capture a snapshot, and persist it all locally.

As in the PhantomJS case, we need to somehow communicate all of that output (test results, logging messages, and snapshot data) back to the Selenium driver. Unlike PhantomJS, Selenium cannot read the console remotely, so we have to perform another trick to manage this communication. Here is the equivalent to the phantomjs module included by our test JavaScript for Selenium:

YUI().add('selenium', function(Y) {

    var messages = [];
        , yconsole = new Y.Console();

    yconsole.on('entry', function(obj) { messages.push(obj.message); });

    var TR = Y.Test.Runner;
    TR.subscribe(TR.COMPLETE_EVENT, function(obj) {
        // Data to dump
        var data = escape(JSON.stringify(
            {
                messages: messages
                , results: Y.Test.Format.JUnitXML(obj.results)
            }
        ));

        // Create a new Node
        var item = Y.Node.create('<div id="testresults"></div>');
        item.setContent(data);

        // Append to document
        Y.one('body').append(item);
    });
}, '1.0', { requires: [ 'console', 'node' ] });

OK, did you spot the trick? Instead of writing the data we want to capture to console.log, we save all the messages we get from YUI Test into an array. When the tests are complete, we create a <div> with a specific ID and dump the JSON-ified version of all the messages and results in there. Finally, we append this new element to the current document. The two most important points about this are that the <div> must be visible and we must escape the entire contents of the resultant JSON string, as the JUnit XML output is—surprise, surprise—XML. We do not want the browser to attempt to parse it; otherwise, it will get lost since it is not valid HTML.

Now let’s look at the other half to see how it all fits together. Here is the entire client-side Selenium runner:

var webdriverjs = require("webdriverjs")
    , url = '...'
    , browser = webdriverjs.remote({
        host: 'localhost'
        , port: 4444
        , desiredCapabilities: { browserName: 'firefox' }
    })
;

browser.init().url(url).waitFor('#testresults', 10000, function(found) {
    var res;
    if (found) {
        res = browser.getText('#testresults',
            function(text) {
                // Do something smarter than console.log!
                console.log(JSON.parse(unescape(text.value)));
            }
        );
    } else {
        console.log('TEST RESULTS NOT FOUND');
    }
}).end();

Using the same outline from earlier, after we load the URL we waitFor the element with the ID testresults to show up in the DOM (here we will wait for up to 10 seconds; your mileage may vary). When it shows up, we pull out its text.

The first thing we have to do is to unescape it to get our XML back. Now we can re-create the hash containing a messages property, which is the array of YUI Test messages, and a results property that contains the JUnit XML output for this test run.

Using this runner, you can run your tests in a real Firefox, Chrome, or IE browser from the command line, as long as the Selenium server is running somewhere reachable on the same host as one of those browsers.

To utilize the Chrome browser, you need to add an extra executable (the Chrome driver) somewhere in your path. You can download the latest version of the Chrome driver for your operating system from the Chromium open-source project site. Just add it somewhere in your PATH and use chrome as the browserName in the desiredCapabilities hash.

Finally, what about snapshots? Selenium conveniently provides snapshot support. So let’s take some pictures! Unlike PhantomJS, our simplistic Selenium runner only knows when the tests end, so we will take the snapshot then.

Here is the full script with snapshot support. Note that Selenium only supports the PNG format. After we get the test results, we grab the snapshot and write it to a local file named snapshot.png:

var webdriverjs = require("webdriverjs")
    , url
    , browser = webdriverjs.remote({
        host: 'localhost'
        , port: 4444
        , desiredCapabilities: { browserName: 'firefox' }
    })
;

browser.init().url(url).waitFor('#testresults', 10000, function(found) {
    if (found) {
        var res = browser.getText('#testresults'
            ,function(text) {
                // Get log messages and JUnit XML results
                console.log(JSON.parse(unescape(text.value)));

                // Now take the snapshot
                browser.screenshot(
                    function(screenshot) {
                        var fs = require('fs')
                            , filename = 'snapshot.png'
                            , imageData
                        ;

                        try {
                            imageData  =
                                new Buffer(screenshot.value
                                  , 'base64');
                            fs.writeFileSync(filename, imageData);
                        } catch(e) {
                            console.log('Error getting snapshot: '
                              + e);
                        }
                    }
                );
            }
        );
    } else {
        console.log('TEST RESULTS NOT FOUND');
        }
}).end();

Again, during your build, you will use a smarter way to pass all your tests to these drivers rather than having the URL or filename hardcoded into them.

An issue with the use of Selenium concerns speed: starting up a browser session for each test or set of tests can be a very slow process. Something to keep an eye on is the Ghost Driver project. This driver, similar to the Chrome driver, allows Selenium to use PhantomJS as a backend. This, of course, significantly speeds up Selenium backend startup and teardown times. Not all Selenium primitives are supported at the time of this writing, but most if not all of the basic ones are. If the speed of Selenium tests is important to you, help the project along!

Another option for speeding up Selenium tests is to farm out your tests to a lot of runners in parallel using the Selenium grid. We will examine better ways to run tests in an automated and distributed fashion in Chapter 5, where we will discuss code coverage, and in Chapter 6 and Chapter 8, where we will discuss other types of testing and automation, respectively.

var browser = webdriverjs.remote({
    host: 'localhost'
    , port: 3001
    , desiredCapabilities: { browserName: 'iPhone' }  // or 'iPad'
});

var browser = webdriverjs.remote({
    host: 'localhost'
    , port: 8080
    , desiredCapabilities: { browserName: 'android' }
});

$ adb shell am start -a android.intent.action.MAIN -n
org.openqa.selenium.android.app.MainActivity

Installing Jasmine is easy:

% npm install jasmine-node -g

Jasmine gives us a nice way to run tests from the command line and output test results in a number of interesting ways: namely, for human or automated consumption.

The idea is that you write a bunch of unit tests using Jasmine-provided syntax and semantics and then point the Jasmine command line to the root directory (or any subdirectory) where those tests live. Jasmine will recurse down the directory tree and run all the tests found within.

By default, Jasmine expects your test files to contain the string spec, as in sum-spec.js—this convention is a BDD artifact and you can override it with the --matchall option.

Go to the Jasmine website to see all of what Jasmine can do. For now, we will look at some short examples, starting with our favorite piece of code: the sum function! Here is the mySum.js file:

exports.sum = function(a, b) { return a + b };

Exciting stuff! Here is some Jasmine code to test integer addition:

var mySum = require('./mySum');

describe("Sum suite", function() {
  it("Adds Integers!", function() {
    expect(mySum.sum(7, 11)).toEqual(18);
  });
});

And finally, here is how the test is run:

% jasmine-node .
.

Finished in 0.009 seconds
1 test, 1 assertion, 0 failures

The test passed! We are definitely on to something. Jasmine matchers (toEqual in the previous example) are equivalent to YUI Test assertions. Plus, you can write your own custom matchers. Jasmine’s describe is equivalent to YUI Test suites and the specs (the it functions) are similar to YUI Test’s test cases. Jasmine also supports beforeEach and afterEach functions that are executed before and after each spec, similarly to YUI Test’s setUp and tearDown functions.

var fs = require('fs');
exports.sum = function(file) {
    var data = JSON.parse(fs.readFileSync(file, 'utf8'));
    return data.a + data.b;
};

var mySum = require('./mySumFS');

describe("Sum suite File", function() {
    it("Adds Integers!", function() {
        expect(mySum.sum("numbers")).toEqual(12);
    });
});

{"a":5,"b":7}

var mockery = require('mockery');
mockery.enable();

describe("Sum suite File", function() {

    beforeEach(function() {
        mockery.registerAllowable('./mySumFS', true);
    });

    afterEach(function() {
        mockery.deregisterAllowable('./mySumFS');
    });

    it("Adds Integers!", function() {

        var filename = "numbers"
            , fsMock = {
                readFileSync: function (path, encoding) {
                    expect(path).toEqual(filename);
                    expect(encoding).toEqual('utf8');
                    return JSON.stringify({ a: 9, b: 3 });
                }
            }
        ;

        mockery.registerMock('fs', fsMock);

        var mySum = require('./mySumFS');
        expect(mySum.sum(filename)).toEqual(12);

        mockery.deregisterMock('fs');
    });
});

    it("Adds Strings!", function() {

        var filename = "strings"
            , fsMock = {
                readFileSync: function (path, encoding) {
                    expect(path).toEqual(filename);
                    expect(encoding).toEqual('utf8');
                    return JSON.stringify({ a: 'testable'
                                            , b: 'JavaScript' });
                }
            }
        ;

        mockery.registerMock('fs', fsMock);

        var mySum = require('./mySumFS');
        expect(mySum.sum(filename)).toEqual('testableJavaScript');

        mockery.deregisterMock('fs');
    });

mockery.registerSubstitute('fs', 'fs-mock');

exports.sum = function(func, data) {
    var data = JSON.parse(func.apply(this, data));
    return data.a + data.b;
};

exports.getByFile = function(file) {
    var fs = require('fs');
    return fs.readFileSync(file, 'utf8');
};

exports.getByParam = function(a, b) {
    return JSON.stringify({a: a, b: b});
};

mySum = require('./mySumFunc');

    describe("Sum suite Functions", function() {
        it("Adds By Param!", function() {
            var sum = mySum.sum(mySum.getByParam, [6,6]);
            expect(sum).toEqual(12);
        });

    it("Adds By File!", function() {
        var sum = mySum.sum(mySum.getByFile, ["strings"]);
        expect(sum).toEqual("testableJavaScript");
    });
});

{"a":"testable","b":"JavaScript"}

    it("Adds By Param!", function() {
        var params = [ 8, 4 ]
            , expected = 12
        ;

        spyOn(mySum, 'getByParam').andCallThrough();
        expect(mySum.sum(mySum.getByParam, params)).toEqual(expected);
        expect(mySum.getByParam).toHaveBeenCalled();
        expect(mySum.getByParam.mostRecentCall.args).toEqual(params);
    });

        spyOn(mySum, 'getByParam').andReturn('{"a":8,"b":4}');

% ls reports
TEST-Sumsuite.xml    TEST-SumsuiteFile.xml
% cat reports/TEST-SumsuiteFile.xml
<?xml version="1.0" encoding="UTF-8" ?>
<testsuites>
<testsuite name="Sum suite File" errors="0" tests="2" failures="0"
time="0.001" timestamp="2012-07-25T15:31:48">
  <testcase classname="Sum suite File" name="Adds By Param!" time="0.001">
  </testcase>
  <testcase classname="Sum suite File" name="Adds By File!" time="0">
  </testcase>
</testsuite>
</testsuites>

Instrumenting a file is simple:

% java -jar yuitest-coverage.jar -o coveraged.js instrument-me.js

The file coveraged.js is now a fully working copy of instrument-me.js with embedded coverage tracking. If you look at the file you will see how it was transformed: interspersed between each statement is a new statement that increments a counter belonging to a global variable that tracks whether the line was executed. This instrumented file is a drop-in replacement for the original file. After exercising the code, the counts can be extracted from the global variable _yuitest_coverage.

Obtaining code coverage information from unit tests is a simple matter of instrumenting the code tested by the unit tests, running the tests, and then extracting the coverage information.

Extracting code coverage information from integration tests requires instrumenting all application JavaScript files, deploying the bundle exactly as you would the regular code, running your Selenium (or manual^[9]) tests against the instrumented build, and then extracting the coverage information. You can usually instrument all your code in one shot by using a single find operation (this must all be on one line, of course):

% find build_dir -name "*.js" -exec echo "Coveraging {}" \;
-exec java -jar yuitest-coverage.jar -o /tmp/o {} \;
-exec mv /tmp/o {} \;

Here we just start at the root of the deployment directory, find all JavaScript files, and replace them in place with their coveraged versions. We can then package and deploy the application as normal. However, as code coverage deals with lines of code, not statements, make sure you run the coverage tools on noncompressed JavaScript.

The YUI coverage tool takes a plain JavaScript file and morphs it into a file that tracks which lines and functions are executed. To see this in action, let’s revisit the sum function:

function sum(a, b) {
    return a + b;
}

Converting this file to its coveraged version:

% java -jar yuitest_coverage sum.js -o sum_cover.js

yields a 37-line file! The first 18 lines are boilerplate defining global variables and functions that YUI Test Coverage uses to track its information, if they are not already defined. The remaining 19 lines are as follows:

_yuitest_coverage["sum.js"] = {
    lines: {},
    functions: {},
    coveredLines: 0,
    calledLines: 0,
    coveredFunctions: 0,
    calledFunctions: 0,
    path: "/home/trostler/sum.js",
    code: []
};
_yuitest_coverage["sum.js"].code=["function sum(a, b)
  {","    return a + b;","}"];
_yuitest_coverage["sum.js"].lines = {"1":0,"2":0};
_yuitest_coverage["sum.js"].functions = {"sum:1":0};
_yuitest_coverage["sum.js"].coveredLines = 2;
_yuitest_coverage["sum.js"].coveredFunctions = 1;
_yuitest_coverline("sum.js", 1); function sum(a, b) {
    _yuitest_coverfunc("sum.js", "sum", 1);
    _yuitest_coverline("sum.js", 2); return a + b;
}

The first block of lines defines the _yuitest_coverage["sum.js"] object, which will hold the counts for line and function coverage as well as some other bookkeeping.

Setup continues in the last block, which defines the line counts (there are two countable lines in the file, line 1 and line 2, and one function at line 1, called sum).

The actual counting of lines happens with each call to _yuitest_coverline or _yuitest_coverfunc. Those functions are defined in the boilerplate, but all they do is increment the count for either the function or the line number.

So, in this example, when this file is loaded _yuitest_coverline("sum.js", 1) is executed, as every file has the first line executed. When the sum function is actually called _yuitest_coverfunc is executed first, meaning that our sum function is called, then _yuitest_coverline is executed, incrementing this line’s count, and finally the actual return a+b is executed and we are done.

In this way, at the beginning of every file, between every statement, and at the beginning of every function, YUI Test Coverage is tracking the lines and functions executed.

It is important to note that each time this file is loaded the counts are reset. Caching may prevent this, but be aware that if a file is loaded multiple times, any previous coverage information will be lost. It is always best to extract the coverage results after each test is run.

For unit testing, the HTML glue file can now include the coveraged version of the file to be tested instead of the regular version. There are several strategies for doing this, and we will discuss a fully automated method in Chapter 6. The simplest method is to instrument all your code before you run your unit tests. The HTML will pick up the instrumented version of your code when running the test. A fancier way, if you are using Apache, is to dynamically instrument the code based off a mod_rewrite rule. In this scenario, you must tag which JavaScript files you want coverage information for in the HTML file. Using a query string for this purpose is most convenient:

<script src="/path/to/file/myModule.js?coverage=1"></script>

A matching mod_rewrite rule will redirect requests of this type to a script that picks up the original file, generates the coveraged version of it, and then returns that instead of the plain version:

RewriteEngine On
RewriteCond %{QUERY_STRING} coverage=1
RewriteRule ^(.*)$ make_coverage.pl?file=%{DOCUMENT_ROOT}/$1 [L]

This will pass off any request for a file with a coverage=1 query string to a script that returns the coveraged version of the requested file.

The script can be as simple as:

#!/usr/bin/perl
use CGI;
my $q    = CGI->new;
my $file = $q->param('file');
system("java -jar /path/to/yuitest_coverage.jar -o /tmp/$$.js $file");
print $q->header('application/JavaScript');
open(C, "/tmp/$$.js");
print <C>;

There is no need to instrument the test code itself; the only code you should be instrumenting is the JavaScript actually being tested. If your module has external dependencies that also must be included to run your tests, you may be tempted to instrument those as well in order to see the connectedness of your code. However, I advise against this. You presumably also have unit tests for the dependencies, and further, any code your tests cover in an external module does not count as being “covered,” as the tests for this module are not intended to test that other module. Unit testing is all about isolation, not seeing what other modules your module may use.

In fact, in an ideal world, no external dependencies should even be loaded to test a single module; they should be stubbed or mocked out from your test code. Few things are worse than having to debug another module beyond the one you are currently trying to test. Isolation is key.

As for deploying coveraged code for integration/Selenium-type testing, the setup could not be simpler. Here, all code must be instrumented and then deployed as usual. Note that instrumented code will run more slowly because it has double the number of statements, so do not performance-test against a coveraged deployment!

Once you have deployed the code, run your tests, but note that coverage information is not persisted across reloads. If you reload the browser between every test, or if you jump to another page, you will need to extract and persist the coverage information before moving on.

Fortunately, Selenium makes this easy, as each test case or suite has a tearDown function within which you can accomplish this.

Also, a deployed instrumented build is fun for manual testing. Load the page in your browser and click around; when you’re finished you can dump the coverage information to the console (view the _yuitest_coverage global variable) and cut and paste that into a file for transformation into HTML. You can now see exactly what code was exercised during your random clicking.

It is important to note that you are not actually “testing” anything when you manually click around a coveraged build. You are merely satisfying your curiosity about what code is executed when you click around.

Mucking about with the Node.js loader is a not-too-hideous way to dynamically inject coveraged versions of JavaScript under test into the mix. If this proves too scary (it involves overriding a private method), fear not, as there is another option.

The scary but more transparent technique is to override Node.js’s Module_load method. Yes, this is an internal method that can change at any moment, and all will be lost, but until then, this method is very transparent.

Here is the basic code:

var Module = require('module')
    , path = require('path')
    , originalLoader = Module._load
    , coverageBase = '/tmp'
    , COVERAGE_ME = []
;

Module._load = coverageLoader;

// Figure out what files to generate code coverage for
//       & put into COVERAGE_ME
// And run those JS files thru yuitest-coverage.jar
//     and dump the output into coverageBase

// Then execute tests
//    All calls to 'require' will filter thru this:
function coverageLoader(request, parent, isMain) {
    if (COVERAGE_ME[request]) {
        request = PATH.join(coverageBase, path.basename(request));
    }

    return originalLoader(request, parent, isMain);
}

// At the end dump the global _yuitest_coverage variable

First we determine which JavaScript files we want to have code coverage associated with, and generate the coveraged versions of those files—this will drop them all into the /tmp directory without any other path information.

Now we execute our tests using whatever framework we like. While our tests execute, their calls to require will filter through the coverageLoader function. If it is a file we want code coverage information for, we return the coveraged version; otherwise, we delegate back to the regular Node.js loader to work its magic and load the requested module normally.

When all the tests are finished, the global _yuitest_coverage variable will be available to be persisted, and will be converted to LCOV format and optionally HTML-ized.

In the preceding code, the client-side JavaScript told the HTTP server to generate coverage information for it using a query parameter—but what about for server-side JavaScript? For this, I like to add an extra parameter to the require call. Like the query string for the client-side JavaScript, the extra parameter to require is transparent. This may be overkill, so another option is to regex-match the required file, if it exists in your local development area (as opposed to native, external, third-party modules that return a coveraged version).

Note that all of this requires two passes: the first pass determines which files need code coverage generated for them, and the second pass actually runs the tests, dynamically intercepts the require’s calls, and potentially returns coveraged versions of the requested files. This occurs because the yuitest_coverage code requires spawning an asynchronous external process to create the coveraged files, yet the require call is synchronous. It’s not a deal-breaker, but it is something to be aware of. If Node.js ever releases a synchronous spawning method, or if a pure synchronous JavaScript coverage generator becomes available, the coveraged versions of the files could be generated in the overridden _load method.

So, how does adding an extra parameter to require to request code coverage work? For starters, your test code looks like this:

my moduleToTest = require('./src/testMe', true);

This statement in your test file that requires the module you are testing simply adds a second parameter (true) to the require call. Node.js ignores this unexpected parameter. A simple regex will catch this:

/require\s*\(\s*['"]([^'"]+)['"]\s*,\s*true\s*\)/g

It looks nastier than it is. The idea is to suck in the source of your test JavaScript file and run this regex on it, which will capture all instances of modules required with the extra true parameter. You are free to get crazier using an abstract syntax tree walker (using a tree generated by JSLint or Uglify.js) or a JavaScript parser, but in practice this regex has been 100% solid (If you have a require statement that breaks it, let me know how ugly it is!).

Once you have collected the list of modules for which you want to generate code coverage metrics, the following code will generate the coveraged versions of them:

var tempFile = PATH.join(coverageBase, PATH.basename(file));
    , realFile = require.resolve(file)
;

exec('java -jar ' + coverageJar + " -o " + tempFile + " " + realFile
  , function(err) {
    COVERAGE_ME[file] = 1;
});

This code is looped over the results of the regular expression, asking Node.js where the file exists and then running that through the YUI code coverage tool and stashing the result where coverageLoader can find it later when the file under test is required.

The last bit is to run the tests and then persist the coverage results. The _yuitest_coverage variable is a JavaScript object that needs to be converted to JSON and persisted. Finally, it can be converted to LCOV format and pretty HTML can be generated, and you are done:

var coverOutFile = 'cover.json';
fs.writeFileSync(coverOutFile, JSON.stringify(_yuitest_coverage));
exec([ 'java', '-jar', coverageReportJar, '--format', 'lcov', '-o'
  , dirname, coverOutFile ].join(' '), function(err, stdout, stderr) {
    ...
});

Earlier, I alluded to another way to get coverage information using Node.js. Of course, there are probably several ways, many that I have never imagined, but the one I alluded to utilizes suffixes. The Node.js loader by default knows about three kinds of file extensions—.js, .json, and .node—and deals with them accordingly. When the Node.js loader is searching for a file to load, if no extension is provided the loader will tack on these extensions to continue its search. Due to the synchronous nature of the loader, we unfortunately cannot dynamically generate the coverage information at load time, so we still need the require('module', true) trick to determine which files need code coverage and pregenerate them.

Also, this method, unlike using the second parameter to require, forces us to load a specific coveraged version of the file under test. In this instance, we could just use the full path to a coveraged version of the file instead, but using the extension is cleaner. We also must be sure to dump the generated coveraged file into the same directory as the original and give it our new extension so that the original loader will load it for us.

Let’s take a look in our test file:

require('./src/myModule.cover');

This will load the coveraged version of the file. Our regex changes to match this:

/require\s*\(\s*['"]([^'"]+)\.cover['"]\)/g

When we generated the coveraged version of the file, instead of dumping it into coverageBase (/tmp, typically) we just put it right next to the original file, but we ensured that it has a .cover extension:

var realFile = require.resolve(file)
    , coverFile = realFile.replace('.js', '.cover');
;
exec('java -jar ' + coverageJar + " -o " + coverFile + " " + realFile,
  function(err) {});

We no longer need to keep track of which files are covered, as the loader will do the right thing due to the .cover extension.

Finally, we just tell the loader what to do when it encounters a file with a .cover extension:

require.extensions['.cover'] = require.extensions['.js'];

Conveniently, this is exactly what the loader should do with files with a .js extension.

There are several ways to generate code coverage information for your server-side JavaScript. Pick the one that works best for you. And fear not: if the steps covered here are too terrible to contemplate, Chapter 8 will provide a fully automated solution for dynamically incorporating code coverage generation and reporting without all the fuss.

This is all fun and games until you are able to persist coverage information locally. For unit testing, persisting coverage information, presents the exact same problem as persisting unit test results—namely, POST-ing or Ajax-ing the data back to the server for persistence. Normally you can run unit tests without a web server: simply load the HTML glue file into your browser and your tests will run. However, to persist test results and coverage information you will need the help of a web server.

YUI Test provides helper hooks to get this information in various formats:

var TestRunner = Y.Test.Runner;
TestRunner.subscribe(TestRunner.TEST_SUITE_COMPLETE_EVENT, getResults);
TestRunner.run();

function getResults(data) {
  var reporter = new Y.Test.Reporter(
    "http://www.yourserver.com/path/to/target",
    Y.Test.Format.JUnitXML);
  reporter.report(results);
}

Use this snippet at the bottom of each of your test suites, and unit test reports will be sent to your server in JUnit XML format, which is recognized by Hudson/Jenkins and many other build tools. YUI also provides output in XML, JSON, and TAP formats. The XML and JSON formats you will have to deal with yourself, but the TAP format, from the Perl world, is also recognized by a host of tools.

When passing the test results back you can also piggyback the coverage results:

function getResults(data) {
      // Use JUnitXML format for unit test results
      var reporter = new Y.Test.Reporter(
        "http://www.yourserver.com/path/to/target",
        Y.Test.Format.JUnitXML);
      // Toss in coverage results
      reporter.addField("coverageResults",
        Y.Test.Runner.getCoverage(Y.Coverage.Format.JSON));
      // Ship it
      reporter.report(results);
}

The addField method on the reporter object allows you to pass back arbitrary data to the server. In this case we are grabbing the coverage results, encoding them as JSON, and passing them back along with the unit test results. Note that JSON is the only sane output for coverage information; it is the format the YUI coverage reporting tool expects.

The end result of this is a POST to our server with results and coverageResults parameters. These two chunks of data can now be persisted to the local filesystem.

Persisting coverage information from integration tests using Selenium follows a similar pattern. After running the Selenium test(s) but before navigating away from the current page, you must grab the coverage information and pass it back to the server. Selenium provides tearDown and after hooks where this code should be placed to ensure that it is captured.

This is best done in Selenium using the global variable _yuitest_coverage, where all the coverage information is kept. Using Selenium1, the code looks like this:

String coverage = selenium.getEval(
  "JSON.stringify(window._yuitest_coverage)");

Using Selenium2/WebDriver, the code is as follows:

String coverage = (String)((JavaScriptExecutor) driver)
  .executeScript("return JSON.stringify(window._yuitest_coverage);");

Then simply dump the coverage string out to a file, ideally named after your test, such as testClick.coverage.json.

Keep in mind that if your application incorporates iframes, coverage information from code in the iframe will not be gathered from the top-level _yuitest_coverage variable. After grabbing the code coverage from the top-level main window, you will need to tell Selenium1 to use it like so:

selenium.SelectFrame("src=foo.html");

Use this code if you are using Selenium2/WebDriver:

driver.SwitchTo().Frame(driver.FindElement(By.CssSelector(
  "iframe[src=\"foo.html\"]")));

With this code you can grab the contents of the _yuitest_coverage variable. Of course, you can use any Selenium selector to pick the iframe that you want to extract code coverage from.

Be sure to aggregate the _yuitest_coverage data from each iframe into the total coverage report. We will examine how to do that in depth in the Aggregation section.

Testing JavaScript in a browser typically involves Selenium. Testing with Selenium usually requires a chunk of Java code running on the same box as the browsers you want to spawn to run your tests, and a client-side API for controlling the remote browser. Selenium2/WebDriver can control Firefox, Chrome, and Internet Explorer for Mac OS X and Windows.

You can write Selenium tests in a variety of languages, or you can use a Firefox plug-in that will generate your tests in various languages by following your mouse movements and keystrokes. Selenium also provides a set of assertion and verification functions that test the current page to ensure the current state is valid.

Using the Selenium IDE is the quickest way to get something to play with. While in any version of Firefox, go to the SeleniumHQ site and get the latest version of the IDE (1.10.0 as of this writing), and let Firefox install the add-on.

Now load your website and open the Selenium IDE (Tools→Selenium IDE). Set the Base URL to the URL of the page where your web application resides. Click on the record button on the upper right of the Selenium IDE and Selenium will start tracking your mouse and keyboard movements as you click and type around your application. Click the record button again to stop recording.

Select File→Export Test Case As and you can save your clicking and typing in a variety of languages for Selenium2/WebDriver, or for original Selenium (Remote Control), which you should not use if you’re new to Selenium.

You can rerun these tests from within the Selenium IDE by clicking the green play button. The log at the bottom of the Selenium IDE window will let you know what is going on.

A common problem with Selenium is that it uses element IDs by default to identify the elements you are interacting with, and using a JavaScript framework that dynamically generates IDs will cause your test to fail, as the elements with these dynamic IDs will not be found during subsequent runs. Fortunately, the Target text field in the Selenium IDE lets you remedy this situation by using XPath or CSS expressions to locate elements, instead of the IDs used by default (of course, if you are setting element IDs yourself you will not have this problem). Click the find button next to the Target text field to locate elements you want to target when changing selectors.

You can also run saved test cases from the command line using JUnit. Export your test case as a JUnit 4 (WebDriver Backend) file and name it something interesting. The IDE will put the following declaration at the top of your file:

package com.example.tests;

Change the declaration to match your environment, or just delete that line.

Now you’ll need both the current version of the Selenium server and the client drivers. From the SeleniumHQ site, download the current version of the Selenium server (version 2.28 as of this writing) and the Java Selenium client driver (version 2.28.0 as of this writing). You will need to unzip the Java Selenium client.

To compile your exported Selenium script you need the selenium-server JAR:

% java -cp path/to/selenium-server-standalone-2.28.0.jar test.java

This will compile your exported Selenium test case. To execute the test you need to start the Selenium server, like so:

% java -jar path/to/selenium-server-standalone-2.28.0.jar

And now you can run your JUnit test case (all on one line):

% java -cp path/to/selenium-server-standalone-2.28.0.jar:Downloads/
selenium-2.20.0/libs/junit-dep-4.10.jar:.
org.junit.runner.JUnitCore test

You need the path to the Selenium server JAR and the JUnit JAR (which is supplied by the Java Selenium client code if you do not already have it somewhere). The preceding code assumes you deleted the package declaration. If not, you need something like this (again, all on one line):

% java -cp selenium-server-standalone-2.28.0.jar
:selenium-2.20.0/libs/junit-dep-4.10.jar:.
org.junit.runner.JUnitCore com.example.tests.test

The compiled Java program must reside in com/example/tests for the Java interpreter to find it (or you can change the class path).

Using the Selenium IDE is clunky; you are better served by handwriting the test cases yourself (you can use JUnit for this). But note that this becomes an exercise in learning XPath or CSS selectors and/or using ID attributes judiciously throughout your HTML so that Selenium can “grab” them and manipulate your application: clicking links and buttons, dragging and dropping, editing form elements, and so on.

You can use either the assert or the verify family of Selenium functions to verify your application’s functionality. Note that the assert family of functions will fail the test immediately and skip to the next test function, while the verify family of functions will fail the assertion but continue running further code within the test function. You should almost always use the assert family of functions in your Selenium tests.

Fortunately, there are JavaScript bindings for Selenium (both Remote Control and WebDriver) by way of npm packages for NodeJS, so we can write Selenium integration tests using our beloved JavaScript.

WebDriver

Using the webdriverjs npm module to drive Selenium2 is straightforward:

var webdriverjs = require("webdriverjs")
    , browser = webdriverjs.remote({
        host: 'localhost'
        , port: 4444
        , desiredCapabilities: { browserName: 'firefox' }
    })
;

browser
    .testMode()
    .init()
    .url("http://search.yahoo.com")
    .setValue("#yschsp", "JavaScript")
    .submitForm("#sf")
    .tests.visible('#resultCount', true, 'Got result count')
    .end();

With the Selenium server started locally, the preceding code will start a Firefox browser, search for “JavaScript” at the Yahoo! search page, and ensure that an element whose id is resultCount is visible.

Generating a screenshot is equally easy. Simply add the saveScreenshot call:

var webdriverjs = require("webdriverjs")
    , browser = webdriverjs.remote({
        host: 'localhost'
        , port: 4444
        , desiredCapabilities: { browserName: 'firefox' }
    })
;

browser
    .testMode()
    .init()
    .url("http://search.yahoo.com")
    .setValue("#yschsp", "javascript")
    .submitForm("#sf")
    .tests.visible('#resultCount', true, 'Got result count')
    .saveScreenshot('results.png')
    .end();

And now you have a beautiful screenshot, as shown in Figure 6-1. Note that although the Yahoo! Axis ad appears in the middle of Figure 6-1, it is actually positioned at the bottom of the visible page. But since Selenium is taking a snapshot of the entire page, it appears in the middle. When you view this page in a browser, the ad appears at the bottom of the visible area.

Figure 6-1. Generating a screenshot with Selenium

To run this example in Chrome, you need to download the Chrome driver for your operating system and install it somewhere in your PATH. Then you simply change this line:

, desiredCapabilities: { browserName: 'firefox' }

to this:

, desiredCapabilities: { browserName: 'chrome' }

and your tests will run in Google Chrome.

How about Internet Explorer? You can download the latest IE driver for your platform from the code.google selenium site. Then put the executable in your PATH and fire it up. It starts up on port 5555 by default:

, port: 5555
, desiredCapabilities: { browserName: 'internetExplorer' }

var soda = require('soda')
    , browser = soda.createClient({
        url: 'http://search.yahoo.com'
        , host: 'localhost'
        , browser: 'safari'
    })
;

browser
    .chain
    .session()
    .open('/')
    .type('yschsp', 'JavaScript')
    .submit('sf')
    .waitForPageToLoad(5000)
    .assertElementPresent('resultCount')
    .end(function(err) {
        browser.testComplete(function() {
            if (err) {
                console.log('Test failures: ' + err);
            } else {
                console.log('success!');
            }
        })
    });

% java -jar selenium-server-standalone-2.28.0.jar -role hub

% java -jar selenium-server-standalone-2.28.0.jar
-role node -hub http://localhost:4444/grid/register

Selenium is not the only browser integration-testing framework around. Built on top of PhantomJS, CasperJS provides similar functionality as Selenium but in a completely headless environment. Using pure JavaScript or CoffeeScript, you can script interactions with your web application and test the results, including screenshots, without any Java. When using CasperJS with the latest version of PhantomJS (1.7.0 as of this writing) you no longer need X11 or Xvfb running to start up the PhantomJS WebKit browser, as PhantomJS is now built on the Lighthouse Qt 4.8.0 device-independent display framework. This means truly headless integration testing is now possible on your servers.

To use CasperJS, first you must install the latest version of PhantomJS from the code.google phantomjs site. Downloading the binary version for your operating system is easiest, but building from source is not much more difficult (unless you have an older version of Linux; I had to make some changes when compiling for Red Hat Enterprise 4/CentOS 4, due to my lack of Thread Local Storage, and to remove some SSE optimizations).

Now grab the latest version of CasperJS; 1.0.0-RC6 as of this writing.

Here is the CasperJS version of the earlier Yahoo! search test:

var casper = require('casper').create();

casper.start('http://search.yahoo.com/', function() {
    this.fill('form#sf', { "p": 'JavaScript' }, false);
    this.click('#yschbt');
});

casper.then(function() {
    this.test.assertExists('#resultCount', 'Got result count');
});

casper.run(function() {
   this.exit();
});

Here’s how to run this CasperJS script:

% bin/casperjs yahooSearch.js
PASS Got result count
%

Sweet, that was easy enough. And it is significantly quicker than connecting to a possibly remote Selenium server and having it spawn and then kill a browser. This is running in a real WebKit browser, but note that the version of WebKit that Apple uses in Safari and the version of WebKit that Google uses in Chrome are different from what is running here with PhantomJS.

How about a screenshot?

var casper = require('casper').create();

casper.start('http://search.yahoo.com/', function() {
    this.fill('form#sf', { "p": 'JavaScript' }, false);
    this.click('#yschbt');
});

casper.then(function() {

    this.capture('results.png', {
        top: 0,
        left: 0,
        width: 1024,
        height: 768
    });

    this.test.assertExists('#resultCount', 'Got result count');
});

casper.run(function() {
   this.exit();
});

The capture code can also capture a given CSS selector instead of the entire page; see Figure 6-2.

Figure 6-2. Generating a screenshot with CasperJS

This looks very similar to the Firefox screenshot captured by Selenium! The biggest difference between the two concerns specifying the exact size of the screenshot you want; CasperJS does not capture the entire browser area, whereas Selenium does.

CasperJS has other tricks up its sleeve, including automatic export of test results to a JUnit XML-formatted file. Here is the full script:

var casper = require('casper').create();

casper.start('http://search.yahoo.com/', function() {
    this.fill('form#sf', { "p": 'JavaScript' }, false);
    this.click('#yschbt');
});

casper.then(function() {
    this.capture('results.png', {
        top: 0,
        left: 0,
        width: 1024,
        height: 768
    });

    this.test.assertExists('#resultCount', 'Got result count');
});

casper.run(function() {
    this.test.renderResults(true, 0, 'test-results.xml');
});

Besides outputting test results to the console, the test-results.xml file will now contain the JUnit XML test output, a format well understood by build tools including Hudson/Jenkins. Here are the contents of that file after running this test:

<testsuite>
    <testcase classname="ss" name="Got result count">
    </testcase>
</testsuite>

Here is the console output:

PASS 1 tests executed, 1 passed, 0 failed.
Result log stored in test-results.xml

Of course, you will want to test your code in Internet Explorer, as (unfortunately) the bulk of your users are probably using it, and for that you will have to use Selenium. But CasperJS is a great addition for quick testing in a headless environment.

Several tools are capable of generating HAR files. One of the most flexible is a programmable proxy that intercepts HTTP requests and responses. The proxy can work with any browser, including mobile ones, giving it maximum flexibility.

Another option is to use a packet-sniffing tool such as tcpdump to capture HTTP traffic in PCAP format, and to then use a tool such as pcap2har to generate the HAR. This arguably gives “truer” performance numbers, as there is no proxy between your server and the client. Although this method is messier, I encourage you to check it out if the proxy method does not work for you. For instance, mobile browsers do not allow you to set proxies, so generating HARs for mobile devices requires a packet sniffer. Visit this code.google webpage for more details.

% /bin/sh bin/browsermob-proxy

% npm install browsermob-proxy

var Proxy = require('browsermob-proxy').Proxy
    , fs = require('fs')
    , proxy = new Proxy()
    ;

    proxy.doHAR('http://yahoo.com', function(err, data) {
        if (err) {
            console.error('ERROR: ' + err);
        } else {
            fs.writeFileSync('yahoo.com.har', data, 'utf8');
        }
    });

    , proxy = new Proxy( { host: 'some.other.host', port: 9999 } )

    , proxy = new Proxy( { selHost: 'some.other.host', selPort: 6666 } )

var Proxy = require('browsermob-proxy').Proxy
    , webdriverjs = require("webdriverjs")
    , fs = require('fs')
    , proxy = new Proxy()
;

/*
 * Call into the proxy with a 'name' for this session, a Selenium
 *     function to run the interaction we want to capture, and
 *     finally a callback that will contain either the HAR data or
 *     an error
 */
proxy.cbHAR('search.yahoo.com', doSeleniumStuff, function(err, data) {
        if (err) {
            console.error('Error capturing HAR: ' + err);
        } else {
            fs.writeFileSync('search.yahoo.com.har', data, 'utf8');
        }
});

/*
 * This is the Selenium function that gets passed the proxy webdriverjs
 *     should use and a callback to call when the interaction is done
 */
function doSeleniumStuff(proxy, cb) {
    var browser = webdriverjs.remote({
        host: 'localhost'
        , port: 4444
        , desiredCapabilities: {
             browserName: 'firefox'
             , seleniumProtocol: 'WebDriver'
             , proxy: { httpProxy: proxy }
        }
    });

    // Just run our regular Selenium stuff - note this can just
    //    be your regular test code or something special you want
    //    to capture with a HAR
    // Just pass the browsermob-proxy callback to 'end()'
    browser
        .testMode()
        .init()
        .url("http://search.yahoo.com")
        .setValue("#yschsp", "JavaScript")
        .submitForm("#sf")
        .tests.visible('#resultCount', true, 'Got result count')
        .saveScreenshot('results.png')
        .end(cb);
}

, proxy = new Proxy({
    downloadKbps: 56
    , uploadKbps: 56
    , latency: 200
})

var Proxy = require('browsermob-proxy').Proxy
    , spawn = require('child_process').spawn
    , fs = require('fs')
;

var proxy = new Proxy();
proxy.cbHAR('MyCoolHARFile', doCasperJSStuff, function(err, data) {
    if (err) {
        console.error('ERR: ' + err);
    } else {
        fs.writeFileSync('casper.har', data, 'utf8');
    }
});

function doCasperJSStuff(proxy, cb) {
    casperjs = spawn('bin/casperjs'
      , [ '--proxy=' + proxy, process.argv[2] ]);
    casperjs.on('exit', cb);
}

% node casperHAR.js casperScript.js

So, thus far we have generated HAR files, which are just JSON, and you know that you can get arbitrarily fancy, perhaps sticking their values in a database or storing the files to watch trends in your application profile. But at some point you are going to want to view the things.

Visualizing the data in HAR files is easy. The simplest method is to go to the canonical web-based viewer; simply drag a HAR file onto the page (go HTML5!) and drop it into any moderately modern browser, and you will see a waterfall graph of the HAR data. Make sure you uncheck the “Validate data before processing” checkbox before uploading your HAR. I have yet to come across a HAR file that validates correctly! Figure 6-3 shows a HAR file for our search.yahoo.com search example.

Figure 6-3. Waterfall graph for the search.yahoo.com example

This is pretty snazzy! From this graph, we can see that 26 requests were made; hovering over any bar will reveal a specific breakdown of the amount of time each request took, in order: DNS Lookup, Connecting, Sending, Waiting, and Receiving.

A much more involved example comes from Yahoo.com. In this example, shown in Figure 6-4, 81 requests were made to download the page, and the download time was 4.39 seconds (actually, the page was visible much sooner than that; the data that was downloaded at the end of the process comprised a big Flash ad). The perceived performance and the initial time until the page looks ready are the most important bits of information to pay attention to, not the total amount of time all the pieces take to download.

Figure 6-4. Waterfall graph for the Yahoo.com example

Other options are also available for viewing HAR files without having to upload them to a remote website. For starters, download the source code for the HAR Viewer. You can also easilyembed HAR graphs generated by the HAR Viewer into your own pages (the HAR files themselves can be grabbed remotely).

Another way to interrogate HAR files is with YSlow. Besides being a browser plug-in that gives grades on load performance, YSlow is also available as a command-line tool that can read HAR files and export YSlow output. You can run YSlow from the command line or from within a Node.js script via the following command:

% npm install yslow -g

The YSlow output can be in XML, plain text, or JSON format. To graphically view the YSlow output, a beacon can be sent to a YSlow visualizer, which you can also install locally if you do not want to send your precious YSlow data to a third party.

Let’s take a look at how this all fits together. After installing YSlow, we’ll feed it a HAR file and use the beacon to view the results at Showslow.com:

%  yslow -i all -b http://www.showslow.com/beacon/yslow/ yahoo.com.har

This will send our HAR output from Yahoo.com to be visualized. Then we cruise over to Show Slow and find our URL in the list of recent beacons to see the full graphical output.

In this case, a lot of people have YSlow’ed Yahoo.com, so there are nice history graphs, and of course all the grades are A’s! At the bottom of the page is a link back to the HAR Viewer for Yahoo.com—the circle is complete!

You can generate visualizations yourself using the -beacon feature—all the data provided by the beacon is detailed. Or you can leverage the Showslow code and run your own local Showslow server.

HAR files are very interesting, but of course they do not represent the complete performance picture. Entire books are dedicated to this topic, and with good reason!

HAR files are amusing and easy to generate, but they do not tell the entire story. Beyond network performance, browsers must also parse HTML, parse and execute JavaScript, and lay out and paint the browser window, and that all takes time. How much time? There are tools to measure what exactly the browser is doing while your web application is running. dynaTrace AJAX Edition for Firefox and Internet Explorer (Windows only) and Speed Tracer for Chrome are two such tools. Both accomplish the same basic tasks. While a page is loading, the tools are collecting timing information that can be graphed immediately, or saved and graphed and inspected later. By inspecting the graphed output, you can identify performance issues and then fix them. The process of collecting these low-level timings is very specific to each browser; hence, there can be no generic collector like a HAR proxy.

In this section we will take a quick look at Speed Tracer. Speed Tracer is an extension for Google Chrome.

Install the extension, and then click on its little green stopwatch icon to bring up the Speed Tracer UI. Clicking the red record button will start tracing browser internals, which mostly consists of fetching resources from the network, parsing HTML and JavaScript, and laying out and painting the browser window. This is all presented in the familiar waterfall graph. At the top of the UI are a Sluggishness graph and a Network graph. The Network graph is essentially identical to the HAR graphs we saw earlier. The Sluggishness graph is more interesting and visualizes how responsive (or not) the user interface is at the specified time. The taller peaks indicate that the browser’s single UI thread was blocked—a bad thing!

Speed Tracer provides hints regarding problem areas in your application (as does YSlow); for instance, Speed Tracer will flag an event lasting longer than 100 ms. Event handling blocks the main UI thread while events are being serviced, so handlers longer than 100 ms can make the UI seem sluggish.

Finally, Speed Tracer provides a save button to save the data so that you can load and examine it again at a later time—this is a great feature to leverage during an automatic build process. To wit, as part of our build we can automatically generate the Speed Tracer data for our application to ensure that no changes are impacting performance (we will investigate this further in Chapter 8). Figure 6-5 provides a peek at the Speed Tracer UI analyzing Yahoo.com.

Figure 6-5. Speed Tracer UI as it analyzes Yahoo.com

Load testing a web application in a browser usually involves sending your application as much traffic as possible and measuring its performance. Measuring performance typically means response time: you GET a page or POST a form multiple times and track how long the application takes to respond.

The canonical tool for this type of testing is Apache Bench. The command-line ab tool takes many options to GET, POST, PUT, or DELETE pages, and dumps out a CSV file of the results. In this chapter, we will work with the Node.js version, called nodeload.

nodeload has lots of great features beyond just hitting URLs repeatedly, so let’s get started. Begin by installing the tool:

% sudo npm install nodeload -g

As a basic example we will use the nl.js utility, which acts similarly to the ab Apache Bench executable:

% nl.js
1 Aug 20:28:52 - nodeload.js [options] <host>:<port>[<path>]

Available options:
  -n, --number NUMBER              Number of requests to make.
Defaults to value of --concurrency unless a time limit is specified.
  -c, --concurrency NUMBER         Concurrent number of connections.
Defaults to 1.
  -t, --time-limit NUMBER          Number of seconds to spend running
test. No timelimit by default.
  -e, --request-rate NUMBER        Target number of requests per
seconds. Infinite by default
  -m, --method STRING              HTTP method to use.
  -d, --data STRING                Data to send along with PUT or
POST request.
  -r, --request-generator STRING   Path to module that exports
getRequest function
  -i, --report-interval NUMBER     Frequency in seconds to report
statistics. Default is 10.
  -q, --quiet                      Supress display of progress
count info.
  -h, --help                       Show usage info

A typical usage of this utility looks like this:

% nl.js -c 10 -n 1000 http://yhoo.it/XUdX3p

Do not try this at home, as this will hit Yahoo.com 1,000 times, with 10 requests happening at a time. Here is what I got when I did not try this at home:

% nl.js -c 10 -n 1000 http://yahoo.com
http.createClient is deprecated. Use `http.request` instead.
Completed 910 requests
Completed 1000 requests

Server:                                 yahoo.com:80
HTTP Method:                            GET
Document Path:                          /
Concurrency Level:                      10
Number of requests:                     1000
Body bytes transferred:                 207549
Elapsed time (s):                       11.19
Requests per second:                    89.37
Mean time per request (ms):             111.23
Time per request standard deviation:    147.69

Percentages of requests served within a certain time (ms)
  Min: 86
  Avg: 111.2
  50%: 94
  95%: 113
  99%: 1516
  Max: 1638

These 1,000 requests averaged 111.2 milliseconds round trip, with one request taking 1.638 seconds to return. This kind of testing works best when also generating server-side statistics. Normally you would let this test run much longer, not only for “endurance testing” (can your application sustain a lot of hits over a long time?) but also to watch CPU, RAM, and disk utilization on the web server, as well as on any other backend machine that is providing services to your web application. Conveniently, nodeload can also generate those values.

nodeload also has a great reporting function. To see it, let’s look at a full example. First we will put a long-running load on our web application. While our web server is servicing those hits, we will measure its CPU, disk, and RAM load. Finally, while the test is running, we can watch a live-updated graph of web server performance.

The first step is to send lots of hits. Here we’re sending 100,000 of them:

% nl.js -c 10 -n 100000 -i 2 http://localhost:8080

While this is running, nodeload runs a web server on port 8000 to display the request activity (see Figure 6-6).

Upon completion, the final HTML and JSON values are saved into the current directory—pretty snazzy.

Meanwhile, you can monitor what is happening on the server side using your favorite statistics generator (vmstat, iostat, uptime, ps, etc.), using nodeload to graph and persist the values. Using Linux and the /proc filesystem, you can report and graph server-side values easily.

nodeload also provides a handy Loop class that will execute code at a specified frequency. As an example, this construct will execute the getMemory and getCPU functions once every five seconds, at most:

var myLoop = new loop.Loop(
    function(finished, args) {
        getMemory();
        getCPU();
        finished();
    }
    , []   // No args
    , []   // No conditions
    , .2   // Once every 5 seconds
);

myLoop.start();

The last parameter in the preceding code is the maximum number of times per second that the loop should execute.

Figure 6-6. nodeload graphical output

The header of this script sets up all our variables:

var reporting = require('nodeload/lib/reporting')
    , report = reporting.REPORT_MANAGER.getReport('System Usage')
    , memChart = report.getChart('Memory Usage')
    , cpuChart = report.getChart('CPU Usage')
    , loop = require('nodeload/lib/loop')
    , fs = require('fs')
;

Here I am defining a single report ('System Usage') with two charts, 'Memory Usage' and 'CPU Usage'. The getMemory function uses the Linux /proc filesystem to get memory usage data:

function getMemory() {
    var memData = getProc('meminfo', /\s*kb/i);

    memChart.put({ 'Free Memory': memData['MemFree']
      , 'Free Swap': memData['SwapFree'] });
    report.summary['Total Memory'] = memData['MemTotal'];
    report.summary['Total Swap'] = memData['SwapTotal'];
}

We can, of course, pick out any value we like. The getProc utility function is not shown; it simply takes a file in the /proc filesystem and objectifies it. The interesting bits are adding the current data point to the memory chart we defined in the header and adding it to the report summary, which is displayed in the righthand column on the reporting web page.

The getCPU function is similar:

function getCPU() {
    var meminfo   = fs.readFileSync('/proc/loadavg', 'utf8')
        , vals    = meminfo.split(/\s+/)
        , cpuInfo = getProc('cpuinfo')
    ;

    cpuChart.put( {
        '1 Min': vals[0]
        , '5 Min': vals[1]
        , '15 Min': vals[2]
    });

    report.summary['CPU'] = cpuInfo['model name'];
}

Again, we grab some values and add them to the CPU chart. Fire up the script and go to port 8000 to view the live results.

The summary information is displayed on the right, and live-updating graphs are in the main column. When the script ends, by whatever means necessary, a file will be available in the local directory with the HTML of the graph.

nodeload has a lot of other tricks up its sleeve, including multiple loops for parallel execution of loops; a statistics package for further analysis of data sets; and a very flexible, programmatic way to specify requests (you do not have to just send vanilla HTTP requests). Of course, you can wrap any testing, hitting of web pages, or anything else within a loop, and easily graph the result.

Finally, the monitoring package allows for easy monitoring and collection of runtime data to prod your code for slowness and bottlenecks.

The WebKit Developer Tools provide excellent support for tracking the memory usage of your client-side JavaScript. As you will see in this section, the Profile panel is your friend for both memory and CPU tracking.

Memory usage

First, to get a look at overall memory usage, fire up your Chrome browser and go to chrome://memory-redirect/. There is a lot of data here, a summary of which you can find by selecting Wrench→Tools→Task Manager or Windows→Task Manager. This output is similar to that of the top utility but within the browser, including CPU usage, I/O, and network status information for each plug-in and tab, as well as overall browser activity (see Figure 6-7).

You can alter the columns that are shown by right- or context-clicking on a column header. For now, JavaScript memory is most useful. Other potentially interesting values are current cache sizes (see Figure 6-8) and, of course, “Goats Teleported.”

There is a lot of good overall information here. Let’s take a closer look at our application.

The heavy memory user here is Gmail. This is not surprising, as Gmail is a single-page web application with lots of JavaScript (like Google Calendar).

Figure 6-7. Chrome Task Manager

Figure 6-8. JavaScript memory per tab/process

Note

As all recent browser versions use mark-and-sweep for garbage collection instead of reference counting, cycles can now be freed properly. But there are still plenty of other ways for your application to consume memory! A good overview is available on the Mozilla Developer Network site.

To determine whether an application is leaking memory, our first stop is the Memory graph in the Timeline panel (see Figure 6-9).

Figure 6-9. Memory graph in the Timeline panel

Memory usage can go up as long as it comes back down. As Figure 6-9 shows, this is a well-behaved application in terms of memory usage—usage goes up and down as the application requests and then releases memory. If your memory usage always increases and never decreases, you may have a memory leak.

In our case, the Profiles tab in the WebKit Developer Tools comes to our rescue! (See Figure 6-10.)

Figure 6-10. The Profiles tab in the WebKit Developer Tools

A heap snapshot makes it very easy to see how much memory a set of JavaScript objects is using. When you take a heap snapshot, the application runs the garbage collector first so that you are getting a “clean” view of actual memory usage (see Figure 6-11). Use the Class Filter text box to filter the resultant objects into the ones you are concerned about.

Figure 6-11. Heap memory used by RegExp objects

According to Figure 6-11, there are more than 1,200 regular expression objects; drilling down, you can inspect every one of them. Besides your own objects, you can also filter on DOM objects. If you are concerned that a certain action is leaking memory, take multiple snapshots. In the Summary view, shown in Figure 6-12, you can see which objects were allocated between each snapshot (note the pull-down at the bottom where I have selected “Objects allocated between Snapshots 1 and 2”).

Figure 6-12. The Summary view

Finally, you can compare two heap snapshots for another view of what has changed between the two (see Figure 6-13).

Figure 6-13. Comparison between two heap snapshots

Here, I used a lot of memory between Snapshot 1 and Snapshot 2. According to the Comparison view, more than 1,000 new array objects were created between the two snapshots. To determine whether this was intended, you can drill down into each object to see what they contain.

Interestingly, there currently is no way to trigger a heap snapshot programmatically. One solution to this issue is to insert a debugger statement into your code, and manually trigger a heap snapshot once the interpreter stops.

You can read about Gmail’s approach to finding and squashing memory leaks in its code. Also, the Chrome Developer Tools team has created a leak finder.

CPU usage

Collecting a JavaScript CPU profile from the Profiles tab shows similar information from the CPU usage angle. You can easily inspect how much time (real or a percentage) your program spends in each function, and how many times each function was executed. Click Start to begin capturing CPU information; you can click around or perform some actions and then click Stop to see what happened.

Figure 6-14 shows that the YUI function to add a node was the heavy hitter (although it was called many times, it still only took 40 ms to decorate the page). This displays the call stack to that function, and clicking on the link on the right will take you to the actual code.

Figure 6-14. JavaScript CPU usage

Clicking the % button will toggle the display between real time and percentage time spent in each function.

By taking heap snapshots and collecting CPU profiles, you can gain a very intimate understanding of what exactly your application is up to while it is running.

If you are interested in tracking noninteractive code paths, use console.profile:

<html>
    <script>
        var Cache = function() {
            this.cache = {};
            this.add = function(key, val) {
                var now = new Date().getTime();
                cache[key] = { val: val, time: now };
            };
        }

        var cache = new Cache();
        console.profile('squared');
        for (var i = 0, l = 1000000; i < l; ++i) {
            cache.add(i, i ^ 2);
        }
        console.profileEnd('squared');
    </script>
</html>

Loading this code in a WebKit-based browser and opening the Profiles tab will produce output similar to that shown in Figure 6-15.

Figure 6-15. CPU usage from console.profile

The Profiles tab has captured the “squared” profile report, and now it is available for inspection.

Node.js exposes the V8 profiler, which you can use to gather CPU and memory usage data beyond console.trace. Using the webkit-devtools-agent npm package makes profiling Node.js server-side applications almost as easy (and pretty) as profiling client-side ones. So, install it, and get ready to rumble!:

% sudo npm install webkit-devtools-agent -g

This package allows your Node.js application to utilize the Heap Snapshot and JavaScript CPU Profiles tabs in a WebKit-based browser (such as Chrome or Safari). To use the package, simply require it at the top of your program and then signal your Node.js process with a USR2 signal:

var agent = require('webkit-devtools-agent');
process.kill(process.pid, 'SIGUSR2');

Of course, you can also send the USR2 signal externally from your program. This starts up a local daemon listening for connections from a WebKit browser that will then fire up the Developer Tools to analyze your program.

To get all this to work, you will need to start a copy of Chrome with the -remote-debugging-port=9222 option. On a Mac, from a shell issue the following command (all on one line):

% /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
--remote-debugging-port=9222 -user-data-dir=/tmp

Another WebKit-based browser can use this copy of Chrome to connect to debug the Node.js application. Once your application has started and you have signaled it with USR2, you can now connect to the following URL from another WebKit browser: http://localhost:9222/devtools/devtools.html?host=localhost:1337&page=0.

This loads the Developer Tools as served by the first WebKit browser, which speaks the Web Sockets protocol to the webkit-developer-agent spawned by your Node.js program. While the entire set of Chrome Developer Tools appears, only the Profiles tab actually works (see Figure 6-16).

Figure 6-16. Profiles tab from webkit-developer-agent

% sudo npm install heapdump -g

require('heapdump');

% kill -USR2 <NodeJS process ID>

process.kill(process.pid, 'SIGUSR2');

% node --prof myapp.js

% sudo npm install profiler -g

% /bin/sh tools/build-nprof

% .../node_modules/profiler/nprof path/to/v8.log

The granddaddy of them all, Firebug is a Firefox extension that provides all the debugging bells and whistles expected in a JavaScript debugger. After installing the latest version (1.11.1 as of this writing) and restarting Firefox, start Firebug by selecting Tools→Web Developer→Firebug→Open Firebug. The Firebug window will open by default at the bottom of the browser; alternatively, you can “detach” it from the browser and place it in its own window if you like. Figure 7-3 shows the Firebug window while browsing Yahoo.com.

Figure 7-3. Firebug window while browsing Yahoo.com

With Firebug, you can manipulate HTML and CSS, step through JavaScript, and set breakpoints. The Net panel will show you the familiar waterfall graph of loading elements. You will see gaps in this graph after JavaScript loads while it is being parsed—holes that Speed Tracer (in Chrome) and dynaTrace (on Windows) can fill in.

Firebug also provides the window.console object that you can use to log messages to the console. In addition to printing strings, you can pass any object to the console output methods and Firebug will dereference it for you to display its fields. You can display basic timing information using the console.time(<STRING>) and console.timeEnd(<STRING>) methods (yes, the strings have to match, allowing you to have multiple overlapping timings simultaneously). Firebug will also display the time that has elapsed between the two calls. You can view more detailed timings using the console.profile() and console.profileEnd() methods. Firebug will display complete timing information for each function that was called between those two invocations. Firebug also provides the console.trace() method to generate a stack trace, including all parameters that were passed to each function within the trace. Objects can be inspected using console.dir(<object>) and HTML nodes can be inspected using console.dirxml(<node reference>). Finally, console.assert(<boolean condition>) will display a red error message in the console if the condition does not evaluate to true.

You can execute arbitrary JavaScript in Firebug or place console.* statements in your code to track it as it runs, and you can insert a debugger statement to set a breakpoint, but be careful to take them out when you are done debugging!

Finally, Firebug allows the naming of anonymous functions using the displayName property. This is easiest to see with an example. Imagine debugging this function:

function getIterator(countBy, startAt, upTill) {

    countBy = countBy || 1;
    startAt = startAt || 0;
    upTill  = upTill || 100;

    var current = startAt;

    return function() {
        current += countBy;
        return (current > upTill) ? NaN : current;
    };
}

The simple function in the preceding example creates an iterator. The following code demonstrates its usage:

var q = getIterator(10, 0, 200);
console.log(q());

That’s simple enough, but debug this in Firebug and look at the stack, as shown in Figure 7-4.

The stack reveals a function named (?). Firebug does not know what to call this anonymous function, so you can tell it what to call it using the displayName property of the anonymous function, like so:

function getIterator(countBy, startAt, upTill) {

    countBy = countBy || 1;
    startAt = startAt || 0;
    upTill  = upTill || 100;

    var current = startAt
        , ret = function() {
            current += countBy;
            return (current > upTill) ? NaN : current;
        }
    ;

    ret.displayName = "Iterator from " + startAt + " until "
      + upTill + " by "  countBy;

    return ret;
}

Figure 7-4. Anonymous functions in Firebug

Here I added the displayName property to the anonymous function—and a pretty descriptive displayName at that! Now when we use Firebug to step through this code, we’ll see something similar to Figure 7-5.

Figure 7-5. Anonymous function with displayName set in Firebug

That’s much better! We have transformed (?) into something very descriptive and helpful. You can add the displayName property to any function, and it can be anything you like. Obviously, it is especially useful for anonymous functions, such as those typically used in event callbacks or, as in this example, ones you generate yourself.

Chrome has an equally useful set of developer tools, including a debugger. Accessed from the View→Developer menu, the Chrome Developer Tools can also be attached to the bottom of the main Chrome window or detached as a separate window. Figure 7-6 shows the window for Yahoo.com.

Awaiting you here is a set of tabs that are similar to those in Firebug. However, Chrome’s Timeline tab includes much of the same data as Speed Tracer, showing not only network traffic, but also what the UI thread is up to, including painting, events, and layout. The Timeline graph also displays when the main resource has finished loading (a purple line) and when the main resource DOM document is finished parsing (a red line). These events represent the initial load time and the first time when the user sees the initial HTML and can start interacting with it—both important measurements. The Timeline panel also has a memory graph. For longer-lived applications with just one page you do not want to see the number forever climbing upward, as such a condition indicates a memory leak in your code. Figure 7-7 shows a peek at the Timeline panel.

Figure 7-6. Chrome Developer Tools window while browsing Yahoo.com

Figure 7-7. Chrome Developer Tools Timeline panel

The Chrome debugger also supports all of Firebug’s console methods, and for minified code the debugger has a nice “prettifier” that renders the JavaScript code readable again. Once the code is prettified, you can set breakpoints as normal—a very handy feature! Obfuscated and minified code requires more work to prettify, and we will investigate how to do this using source maps later in this chapter.

The Chrome debugger also supports the “naming” of eval blocks. As you are not using eval, this hopefully will not affect you. However, some tools—especially tools that manipulate JavaScript, such as the CoffeeScript compiler—use eval generously. The following format:

//@ sourceURL=<any string without spaces>

will make your eval appear in the Scripts drop-down, where you can select it to jump immediately to the eval statement. Here is a quick example:

var two = eval('1 + 1; //@ sourceURL=addedOnePlusOne!');

Figure 7-8 shows what this looks like in the Scripts panel of the Chrome debugger.

Figure 7-8. sourceURL set in Chrome Developer Tools

As you can see in the figure, addedOnePlusOne! is available in the list of scripts to select to jump directly to—and the evaled expression will be available to examine and breakpoint, as it is in the earlier example. The name is also visible in the stack trace.

Chrome also allows you to easily change the User Agent string it sends when fetching web pages. You can access this capability in the Settings menu, where you can pretend to be any browser you want (see Figure 7-9).

Figure 7-9. Changing the User Agent string in Chrome

Finally, Chrome allows you to break on all errors, even errors that were caught in a try/catch block, as shown in Figure 7-10.

Figure 7-10. “Pause on exceptions” toggle in Chrome Developer Tools

You can toggle this feature on and off. I recommend that you leave it on initially, to ensure that the errors and exceptions you are catching are acceptable.

Like Chrome, Safari is based on WebKit, and its debugger is very similar to the Chrome debugger. To use the tools, you begin by enabling the Develop menu in Safari. The checkbox for doing so is hidden under Preferences→Advanced→”Show Develop menu in menu bar” (see Figure 7-11).

Figure 7-11. Enabling the Develop menu in Safari

Now you have a Develop top-level menu with a lot of options. Go ahead and open the Web Inspector, and you’ll see something similar to Figure 7-12.

Figure 7-12. Safari Web Inspector

Chrome has added some bells and whistles that are not available in the standard WebKit—namely, the remote debugging JSON protocol (even though it was ported back to WebKit, the feature is not yet available in Safari) and other advanced options—but typically Safari and Chrome behave in virtually the same manner when rendering pages, so choose whichever one you enjoy developing with the most. Of course, there are differences between the two browsers, but they are not as pronounced as are those between Safari/Chrome and Firefox, and especially between Safari/Chrome and Internet Explorer. Like Chrome, Safari also offers easy access to changing the User Agent string it sends to masquerade as different browsers. You can enter an arbitrary string to trick websites into sending content optimized for other browsers. This is most useful for pretending to be a mobile iOS browser, as the iPhone, iPad, and iTouch User Agent strings are all available. Figure 7-13 shows what happens after selecting the iPhone User Agent string and visiting LinkedIn.

Figure 7-13. Changing the User Agent string in Safari

Safari also supports the displayName property on functions for display in its debugger.

I cannot say much about Internet Explorer that has not been said already. Unfortunately, most of your users may be using IE. Fortunately, use of IE 8 and earlier versions is waning; however, IE 8 and later versions do provide a nice debugger. You access the IE debugger by pressing the F12 key on your keyboard (hence the name “F12 Developer Tools”) or via the Tools menu. The debugger provides similar tools to Firefox and WebKit-based browsers, including rudimentary profiling information.

IE 8 also provides the console object, but with very limited functionality: only log, info, warn, error, and assert are supported. At some point you will have to use the IE debugger, but fear not, it is not ridiculously hideous.

Chrome/WebKit has, by far, the most mature remote development environment. Versions 18 and later of Chrome have the latest version of the JSON-based remote debugging API, version 1.0. Note that this is not the same API as the V8 debugger API. Chrome allows its debugger to be used on remote code and allows a remote debugger to connect to Chrome to debug JavaScript running within it. That’s service!

To debug JavaScript running in Chrome remotely, you need to start the Chrome executable with a port for the debugger to listen on. Here’s the code if you’re using Windows:

% chrome.exe --remote-debugging-port=9222

Here it is if you’re on a Mac (all on one line):

% /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome
--remote-debugging-port=9222

You should also start Chrome with this option:

--user-data-dir=<some directory>

This is equivalent to starting Chrome with a fresh profile, such as your Firefox profile. Now you can attach to port 9222 and interact with the 1.0 debugger profile.

Here is an example of how to use this functionality to pull out timing statistics—the same statistics as those that Speed Tracer and the Chrome debugger’s Timeline panel visualize. We will use Selenium to automatically spawn a Chrome instance listening on port 9222 for debugger connections. You may find it interesting that the JSON debugging API runs over Web Sockets, not HTTP; use of Web Sockets makes event propagation trivial. Using EventHub or socket.io would provide the same functionality over plain HTTP.

Let’s take a look at a Node.js script using webdriverjs, the Node.js package discussed in Chapter 6 for Selenium WebDriver, which leverages Chrome’s remote debugging capabilities. This script is a bit longer, so we will look at it in two parts. This first part starts up Selenium with the appropriate Chrome command-line options and exercises the browser with the flow we want to capture:

var webdriverjs = require("webdriverjs")
    , browser = webdriverjs.remote({
        host: 'localhost'
        , port: 4444
        , desiredCapabilities: {
            browserName: 'chrome'
            , seleniumProtocol: 'WebDriver'
            , 'chrome.switches': [
                '--remote-debugging-port=9222'
                , '--user-data-dir=remote-profile'
            ]
        }
    }
);

browser.addCommand("startCapture", startCapture);

browser
    .init()
    .url('http://search.yahoo.com')
    .startCapture()
    .setValue("#yschsp", "JavaScript")
    .submitForm("#sf")
    .saveScreenshot('results.png')
    .end();

This is mostly standard webdriverjs stuff we have seen before. However, there are two additions. The first addition is the chrome.switches desired capability. The Chrome driver conveniently allows us to provide command-line switches to the Chrome executable. Here we are telling Chrome to start listening for remote debugger connections on port 9222 and to use a profile from a specific directory. We do not need any specific Chrome extensions or settings to use remote debugging, so this is pretty much just a blank profile.

The second addition is the startCapture function. webdriverjs allows us to define a custom method that can be chained along with all the standard webdriverjs methods. Any custom method receives a callback function to be invoked when the custom function is finished. Here we have defined a startCapture method that will start capturing all Chrome-supplied timing information—network times, painting times, layout times, everything that is available. There is no corresponding stopCapture function in this example, as we will just capture everything until the browser is closed.

Here is the startCapture function:

function startCapture(ready) {

    var http = require('http')
        , options = {
           host: 'localhost'
           , port: 9222
           , path: '/json'
        }
    ;

    http.get(options, function(res) {
        res.on('data', function (chunk) {
            var resObj = JSON.parse(chunk);
            connectToDebugger(resObj[0], ready);
        });
    }).on('error', function(e) {
        console.log("Got error: " + e.message);
    }

Visiting http://localhost:9222/json (or whatever host Chrome is now running on) will return a JSON response, which is an array of tabs that can be attached to for remote debugging. Since we just opened this Chrome instance with Selenium there is only one tab, and hence only one object in the array. Note that webdriverjs passed startCapture a callback function to be called when our startCapture step is finished. So, this function connects to the local (or remote) Chrome instance, gets the JSON data about the current tab we want to debug, and then hands off this information to the connectToDebugger function, shown here:

function connectToDebugger(obj, ready) {

    var fs = require('fs')
        , WebSocket = require('faye-websocket')
        , ws = new WebSocket.Client(obj.webSocketDebuggerUrl)
        , msg = {
            id: 777
            , method: "Timeline.start"
            , params: {
                maxCallStackDepth: 10
            }
        }
        , messages = ''
    ;

    ws.onopen = function(event) {
        ws.send(JSON.stringify(msg));
        ready();
    };

    ws.onmessage = function(event) {
        var obj = JSON.parse(event.data);

        if (obj.method && obj.method === 'Timeline.eventRecorded') {
            obj.record = obj.params.record;  // Zany little hack
            messages += JSON.stringify(obj) + '\n';
        }
    };

    ws.onclose = function(event) {
        var header = '<html isdump="true">\n<body><span id="info">'
          + '</span>\n<div id="traceData" isRaw="true" version="0.26">'
          , footer = '</div></body></html>'
        ;

        ws = null;
        fs.writeFileSync('DUMP.speedtracer.html', header + messages
          + footer, 'utf8');
    };

OK, this is the meat of the whole thing! Remember, the debugger protocol runs over a web socket connection. The faye-websocket npm module provides an excellent client-side web socket implementation, which we leverage here. The object provided by startCapture contains the webSocketDebuggerUrl property, which is the web socket address to connect to for this tab—which was just spawned by Selenium.

After connecting to the specified web socket address, faye-websocket will issue a callback to the onopen function. Our onopen function will send a single JSON-encoded message:

msg = {
    id: 777
    , method: "Timeline.start"
    , params: {
        maxCallStackDepth: 10
    }
};

The specification for this message is available at the Chrome Developers Tools website. This tells Chrome to send us web socket messages, which are Chrome debugger events, for every Timeline event. Once we’ve sent this message, we call the webdriverjs callback so that our webdriverjs chain can continue (remember that?).

Now, we perform some Selenium actions for which we want to capture Timeline events—in this case, loading Yahoo! and then searching for “JavaScript”. While all this is happening, Chrome is sending us Timeline.eventRecorded events, which we dutifully capture and keep via the onmessage web socket callback.

Finally, after those actions have finished, we shut down Selenium, which closes Chrome, which calls our onclose handler, which does some interesting things as well—namely, dumping all our saved events into an HTML file. This HTML file is, conveniently, the same file format used by Speed Tracer, so if you load this HTML file into Chrome with the Speed Tracer extension installed, it will load the Speed Tracer UI with this data—awesome! This allows you to automatically capture Speed Tracer input that you can use to compare against previous versions of your code, or examine at your leisure. Figure 7-15 shows how the HTML code looks when loaded into Chrome, with Speed Tracer installed.

Figure 7-15. HTML code when loaded into Chrome, with Speed Tracer installed

Clicking the Open Monitor! button brings up the Speed Tracer UI with our captured data in it, as shown in Figure 7-16.

Figure 7-16. Speed Tracer UI showing captured data

Beyond capturing Timeline events from Chrome, you can also completely control the Chrome debugger from a remote location, pausing and resuming scripts, capturing console output, calling and evaluating JavaScript in the context of the page, and doing all the other things you can do using the Chrome debugger directly.

Similar to Chrome, PhantomJS can be used as a target for remote debugging. But in this case, the remote machine can be headless, or you can run PhantomJS locally without having to fire up another browser instance with its own separate profile.

Unfortunately, you cannot directly interact with the web application running in the PhantomJS browser. Fortunately, you can step through the code and interact programmatically with your running code via a PhantomJS script.

Remote debugging using PhantomJS is most useful for scriptable or programmable debugging. Here is how to set it up using the latest version (1.7.0 as of this writing):

% phantomjs -remote-debugger-port=9000 ./loader.js <webapp URL>

In the preceding command line, loader.js is a PhantomJS script that simply loads your URL and waits:

// Open page from the command line in PhantomJS
var page = new WebPage();

page.onError = function (msg, trace) {
    console.log(msg);
    trace.forEach(function(item) {
        console.log('  ', item.file, ':', item.line);
    })
}

page.open(phantom.args[0], function (status) {
    // Check for page load success
    if (status !== "success") {
        console.log("Unable to access network");
    } else {
        setInterval(function() {}, 200000);
    }
});

This script will also dump out any syntax errors or uncaught exceptions from your application, which is nice. Once this script is running, open your local WebKit-based browser, type http://<phantomjs_host>:9000 in the URL bar, and click on the link that is your web application. The familiar debugger will open and you will be live-debugging your application.

PhantomJS provides an evaluate method that allows you to manipulate the DOM of the loaded page and execute JavaScript on the page. Note that any JavaScript executed by PhantomJS on the page is sandboxed and cannot interact with the running JavaScript in your application—but that is what the remote debugger is for! One-way interaction from your web application to a PhantomJS script can happen via console.log messages, and there are interesting ways to leverage that path, as we will see when gathering unit test output and code coverage information and using PhantomJS as a target for automated unit test execution.

Firebug also has a remote debugging capability, using the Crossfire extension. Crossfire is an extension to Firebug that exposes a debugging protocol to the network for programmable debugging. The latest version (0.3a10 as of this writing) is available at their website. Once you have installed Crossfire and restarted Firefox, you will see a Crossfire icon in your Add-on bar. Clicking on that icon and then clicking Start Server brings up the dialog box shown in Figure 7-17.

Figure 7-17. Crossfire configuration dialog in Firefox

Click OK to start the Crossfire server on this host, listening on port 5000 (or set the port number to something else).

Alternatively, you can start Firefox with a command-line option to automatically start the Crossfire server on a given port:

% firefox -crossfire-server-port 5000

Now you can connect to the Crossfire server and start debugging! Similarly to Chrome’s tabs, Firebug treats each tab as a separate “context.” Unfortunately, the Selenium Firefox driver does not currently support passing arbitrary command-line options to the Firefox executable, and nor does Crossfire support profile-based configuration, so this cannot be automated by Selenium. I hope this changes soon.

Crossfire is not as mature as the debugging server built into Chrome. I expect this to change over time, but currently you are better off using the WebKit/Chrome-based debugger for remote debugging within the browser.

You can install Chrome for Android Beta on Android 4.0 and later from the Google Play store. This version allows for remote debugging from your desktop using the standard WebKit debugging protocol. Once Chrome for Android Beta is installed, you must go to Settings→Developer Tools to enable remote debugging.

Meanwhile, on your desktop you must install the Android Software Developer Kit (SDK) from the Android website. We only need one script from this package: the Android Debug Bridge (adb). That executable is available in the stock SDK download and installing it is easy. Once you’ve downloaded the SDK, run the Android executable, which is the Android SDK Manager. From that tool you have the option to install the Android SDK Platform tools, which contain the adb tool. Simply check the corresponding box and click Install. Figure 7-18 shows what the Android SDK Manager tool looks like on my Mac.

Installing all that stuff will take a long time so if you just want the adb tool, uncheck all the other checkboxes and then click Install. Once the tool is installed, a platform-tools directory will exist in the main SDK tree. You must now connect your phone to your desktop using your USB cable. You can run the adb tool like so:

% ./adb forward tcp:9222 localabstract:chrome_devtools_remote

Figure 7-18. Android SDK Manager

On your desktop Chrome, connect to http://localhost:9222 and you will see a list of the URLs in each tab on the Chrome browser on your phone. Click the tab you would like to debug, and voilà, you can use the Developer Tools on your desktop Chrome to debug and control the browser on your phone.

The biggest shortcoming to this approach is that you must be running Android 4.0 or later, you must install Chrome Beta, and your phone must be physically connected to your desktop. This method works only for that exact scenario.

iOS 6 brings a new remote Web Inspector feature to Mobile Safari. Start by selecting Settings→Safari→Advanced to enable the feature on your iDevice (see Figure 7-19).

Now browse to the site you want to debug in Mobile Safari [in this example, Yahoo!], connect the device to a Mac running desktop Safari 6.0+, and pull down the Develop menu (which must be enabled), as shown in Figure 7-20.

Figure 7-19. Enabling the remote Web Inspector in iOS 6

Figure 7-20. Debugging a website on an iPhone from desktop Safari

As you can see here, my iPhone is now available to be Web Inspected remotely. You can choose any open mobile Safari page to attach the debugger to and then debug as usual, setting breakpoints, stepping through JavaScript, and inspecting page elements. Figure 7-21 shows the Safari Web Inspector window for the mobile Yahoo.com page.

Figure 7-21. Safari Web Inspector window for the mobile Yahoo.com page

Adobe Edge Inspect (originally Adobe Shadow) is a cross-mobile-OS solution that allows remote WebKit mobile debugging on all versions of Android, iOS, and Kindle Fire. It consists of a desktop Chrome extension, a desktop daemon (similar to adb), and an application on your device. Your device must be on the same local network as your desktop so that they can connect to each other. Adobe Edge Inspect only works on Windows 7 and Mac OS X.

Start at the Adobe Creative Cloud website and grab the latest version of the Inspect daemon. From that page you can also download the application for iOS, Android, or Kindle Fire and the Inspect Chrome extension.

Start up the Inspect application; to do this you must log into the Creative Cloud website again—Bad Adobe!

In Chrome, install the Adobe Inspect extension from the Chrome Web Store and you will be greeted by the Inspect extension icon on your browser; click it and you’ll see something similar to Figure 7-22.

Figure 7-22. Configuring Inspect in Chrome

Make sure the slider is set to “on.” Adobe Inspect is now ready to accept connections from a mobile device running the Adobe Inspect application, so grab that from your mobile app store and run it. You will be prompted to add a connection. Although a “discovery” feature is available for this, I have not had success with it. Fortunately, you can manually add a connection by specifying the IP address of your desktop running the Adobe Inspect daemon (see Figure 7-23).

After connecting, you will be presented with a PIN that you must enter into your desktop Chrome browser (see Figure 7-24).

Figure 7-23. Specifying the desktop IP address on an iPhone

Figure 7-24. Entering the PIN on desktop Chrome

That passcode is entered into your desktop Chrome browser from the extension icon. At this point, the device is ready to be debugged (see Figure 7-25).

Figure 7-25. Debugging a remote device running Inspect from desktop Chrome

Now open a tab in your desktop Chrome browser and navigate to the page you would like to debug; that page will also load on your mobile device. In fact, once you are connected, any URL you visit will be mirrored on that device. Clicking the <> icon from within the Inspect extension will bring up the debugger, and what is being debugged is the version of the URL on the mobile device.

You can now use the debugger as you would on a local page, selecting elements, changing CSS, and debugging JavaScript. It is as though the location being debugged is running in the local browser.

This works on all versions of Android, iOS, and Kindle Fire. The only requirements are that the device (or devices, as multiple devices can be mirrored from a single Chrome desktop simultaneously) must be on the same local network as the desktop, you must use Chrome, and you must be using Windows 7 or Mac OS X.

Things get goofy when a website offers both a “mobile” and “desktop” version of its site, so it’s best to set the User Agent of your desktop Chrome browser to match whatever device is being mirrored. You can do this from the Developer Tools menu; click on the Settings wheel in the lower-right corner and select the Overrides tab (see Figure 7-26).

Figure 7-26. Setting the User Agent string in Chrome

Now the site viewable in desktop Chrome will match what is being viewed on your mobile device, making for easier debugging.

While this is a neat tool, with the advent of iOS 6 and good native Android debugging the value of using Adobe Inspect is limited, so stick with the native solutions if possible.

Other mobile debugging options are also available, such as weinre (pronounced “winery”), which became part of PhoneGap and is now an incubator project at Apache called Apache Cordova. weinre—which stands for WEb INspector REmote—works similarly to Adobe Inspect, but Inspect is more polished. And with the advent of native iOS 6 and Android debugging, its usefulness is minimized.

Jsconsole.com is another option: it requires the injection of its JavaScript via a bookmarklet to inject debugging code. The end result is similar, but the method is more clunky and complicated.

Going forward, your best bet for a robust debugging environment is either one of the native options discussed here, or Adobe Inspect. But this space is changing quickly, so keep your eyes and ears open for new solutions!

As previously mentioned, WebKit browsers have a “de-minify” button for the simplest case of only compressed code. Figure 7-27 shows minified code in the Chrome debugger.

Figure 7-27. Minified code in Chrome Developer Tools

As you can see, this is not terribly useful! It is impossible to set a breakpoint, and if the code does stop somewhere it is impossible to tell exactly where. Decompressing the code after clicking the {} button yields what’s shown in Figure 7-28.

Figure 7-28. Expanded code in Chrome Developer Tools

Great, now this code is readable and breakpoints can be set on each line. But this code was also obfuscated using Google’s Closure Compiler, so we do not have access to the original variable names (similar obfuscation tools will yield similar results).

Source maps come to our rescue here. A source map is a single file containing one large JSON object mapping lines in the compressed, obfuscated, and combined JavaScript code back to the original code. An added bonus is the fact that the “original code” does not even need to be JavaScript! The source map specification is available here and is currently at Revision 3.

Using source maps, code that has been minified, combined, and obfuscated can be mapped directly back to the original source in the debugger. As of this writing, only Google Chrome supports source maps natively (on the Beta branch), although other browsers are sure to follow. The Google Closure Compiler combines and generates minified and obfuscated code and can also output a source map for that code. Google also supplies the Closure Inspector, a Firebug extension that lets Firebug understand source maps as well. Hopefully, source map support will soon be supported in all browsers natively.

Let’s take a quick look at the process. For this example we will use the getIterator function shown earlier. Here it is again, in a file called iterator.js:

function getIterator(countBy, startAt, upTill) {

    countBy = countBy || 1;
    startAt = startAt || 0;
    upTill = upTill || 100;

    var current = startAt
        , ret = function() {
            current += countBy;
            return (current > upTill) ? NaN : current;
        }
    ;

    ret.displayName = "Inerator from " + startAt + " until "
        + upTill + " by " + countBy;

    return ret;
}

As you can see, there’s nothing special here—it weighs in at 406 bytes.

Let’s grab the latest version of compiler.jar from the Google Closure Compiler home page. Now we are ready to run the Closure Compiler on iterator.js:

% java -jar compiler.jar --js iterator.js --js_output_file it-comp.js

Here is our new file, it-comp.js (lines broken for readability):

function getIterator(a,b,c){var a=a||1,b=b||0,c=c||100,d=b
,e=function(){d+=a;return d>c?NaN:d};
e.displayName="Iterator from "+b+" until "+c+" by "+a;return e};

This file weighs in at a svelte 160 bytes! In addition to deleting all the whitespace (and any comments), variable names were renamed: countBy was transformed to a, startAt to b, upTill to c, and so forth. This cuts down on the size of the file tremendously, and now we are ready to deploy into production!

Or are we? There is still a problem with this code: debugging the code in a browser will be very difficult. Even “unminifying” it using the {} button in a WebKit debugger will not bring our original source code back, due to our renaming of the variables.

Fortunately, the Closure Compiler can make more advanced transformations to our code to make it even smaller. However, these transformations will deviate our code even further from the original.

And here is where this becomes a problem. If we load the code into the debugger as part of our web page and try to debug it, we see that the code is quite ugly (see Figure 7-29).

Figure 7-29. Minified Iterator code

Figure 7-30 shows the unminified version.

Figure 7-30. Expanded Iterator code

OK, that version is slightly less ugly, but the variable names are still not correlated to our original source, and the line numbers are different from those in the original file.

Source maps to the rescue! First we tell the Closure Compiler to generate a source map for us (all on one line):

% java -jar compiler.jar --js iterator.js --js_output_file
it-comp.js --create_source_map ./it-min.js.map --source_map_format=V3

If we take a look at the generated source map file, it-min.js.map, it is indeed a giant JSON object:

{
"version":3,
"file":"it-comp.js",
"lineCount":1,
"mappings":"AAAAA,QAASA,YAAW,CAACC,CAAD,CAAUC,CAAV,CAAmBC,CAAnB,CAA2B,
CAE3C,IAAAF,EAAUA,CAAVA,EAAqB,CAArB,CACAC,EAAUA,CAAVA,EAAqB,CADrB
,CAEAC,EAASA,CAATA,EAAmB,GAFnB,CAIIC,EAAUF,CAJd,CAKMG,EAAMA,QAAQ
,EAAG,CACfD,CAAA,EAAWH,CACX,OAAQG,EAAA,CAAUD,CAAV,CAAoBG,GAApB,CAA0BF
,CAFnB,CAMvBC,EAAAE,YAAA,CAAkB,gBAAlB,CAAqCL,CAArC,CAA+C,SAA/C,CAA2DC
,CAA3D,CAAoE,MAApE,CAA6EF,CAE7E,OAAOI,EAfoC;",
"sources":["iterator.js"],
"names":["getIterator","countBy","startAt","upTill","current","ret"
,"NaN","displayName"]
}

The meat of this object is the mappings property, which is a Base64 VLQ-encoded string. You can read plenty of gory details about this encoding, as well as what exactly is encoded, online.

The last bit of magic is to tie the source map to the JavaScript served to the browser, which you can do by adding an extra HTTP header or by adding a magical line to the minified JavaScript telling the debugger where to find the corresponding source map:

function getIterator(a,b,c){var a=a||1,b=b||0,c=c||100,d=b
,e=function(){d+=a;return d>c?NaN:d};
e.displayName="Iterator from "+b+" until "+c+" by "+a;return e};
//@ sourceMappingURL=file:////Users/trostler/it-min.js.map

Here we added a line to the Closure Compiler output pointing to the source map generated by the compiler.

Now go back to the browser, load it all up, and look in the debugger (see Figure 7-31).

Not only is the code in the debugger window our exact original code, but also the filename in the Scripts pull-down is the original filename. Breakpoints can be set as though this were the exact code running in the browser, but indeed the browser is actually running the minified output from the Closure Compiler.

The biggest issue when using source maps is printing/evaluating expressions, as the original source looks like it is being executed as is, but those original variable names do not actually exist in the browser as it is executing your minified code. You cannot evaluate expressions to determine variable values, nor do you have the mapping to know what the variable was transformed into! Figure 7-32 shows an example.

Figure 7-31. Iterator code expanded showing original code

Figure 7-32. Debugging source-mapped code

In the debugger I am looking at code where the variable current should be defined, but my Watch Expressions display reveals that it is not defined! Conversely, some random variable named d is defined with the value 0, but it does not appear to be so defined in the source code listing. This is weird and something to be aware of. Perhaps future versions of the specification will handle this inconsistency.

Google’s GWT compiler can also output source maps, and work is being done for the CoffeeScript compiler as well, so as far as you can tell you are debugging your original native code while the browser is actually running the compiled version. As time goes on other tools besides the Closure Compiler will support this format, so get behind (or ahead?) of it!

Perhaps the biggest advantage of a completely automated environment is the ability to do continuous integration. By constantly building and testing (at every commit), you catch errors very quickly, before the code is deployed anywhere.

Developers are responsible for running unit tests before checking in their code, but unit testing is only the beginning. In a continuous integration environment, the code is tested as a whole for any mismatches (and unit tests are executed over the entire codebase in case you accidentally break something else in the process!).

To accomplish this for every commit, you need to run the build and the tests as quickly as possible. You can run unit tests in parallel, followed by a quick deploy to a test environment for some basic integration testing. Not all of your tests need to run while doing continuous integration—typically you just need to run unit tests and several integration tests that test very basic and core application functionality.

You will be able to trace failures directly back to the commit and the developer responsible for the failure. At this point, all builds should be halted until the problem is fixed. (Perhaps the developer’s name should go up on a “wall of shame” for breaking the build!) All attention should now be focused on fixing the build so that the rest of the team can continue moving forward.

Upon success, the build can be deployed to a QA environment for more extensive testing, and from there into other environments, and eventually out to production.

A quick, fully automated development build gives rise to a continuous integration environment. Applications with many integration points and pieces are especially prone to errors between all the moving parts. The ability to quickly discern issues in an automated fashion without having to bother developers or QA people speeds development by not wasting time on obviously broken builds.

There are very few, if any, reasons why you should not be using continuous integration in your project.

The software development stage is the most manual, error-prone, time-consuming part of any software project. Until we can teach computers to write code for us, we are stuck typing characters one at a time into an editor. Every modern industry has been completely transformed by automation, with newer, shinier, faster machines doing the repetitive tasks humans once toiled at. Not so with writing software. The “science” and “art” of writing software has not changed in the more than 40 years since the terminal was introduced—the conversion from punch cards to terminals in the early 1970s was the last “breakthrough” in software creation. Instead of writing software on pads of columned paper to be punch-carded, we can now type our programs directly into the computer—woo-hoo.

So, writing software is a very hard, very time-consuming, and very manual process. Any automated tool that can in any way facilitate, speed up, and automate the task is a very good thing. Let’s take a tour of some tools that are available for this task and see how we can use them to automate the development environment.

Unit tests

Having taken the time to write the unit tests, now you should enjoy the fruits of your labor by running them automatically while you develop. Several unit test frameworks provide similar features: the ability to run unit tests from the command line, dynamic code coverage report generation, and multiple browser support. JUTE is a handy tool that does all of that, and a bit more. In this section we will focus on integrating JUTE into our development environment to run our unit tests and generate coverage reports as painlessly as possible (in the spirit of full disclosure, I am the author of JUTE).

Available as an npm package, JUTE’s biggest requirements are the use of YUI3 Test and your directory structure. From our work with Yahoo! Mail, my colleagues and I determined that the sanest directory structure between application and test code is a mirrored hierarchy. From the root directory there are two main subdirectories, src and test. The test directory tree mirrors the src directory tree. All unit tests for each file in the src tree live in the corresponding directory in the test tree. Of course, your mileage may vary, and you do not have to set up your repository that way—some people like to have their test files in the same directory as the source code, and JUTE can be configured for this scenario. However, my experience suggests that having a mirrored test tree is a superior layout.

Begin by installing JUTE:

% npm install jute

Use the npm variable to configure it. The most important configuration variable is docRoot, which is the root of your project. By default, JUTE expects a test directory within your docRoot:

% npm config set jute:docRoot /path/to/project/root

Now you must restart JUTE (as you must do after any configuration variable change):

% npm restart jute

The JUTE UI should be running in your browser at http://localhost:5883, where you will see something similar to Figure 8-1.

Figure 8-1. The JUTE user interface

Starting with the Status panel, you will see all “captured” browsers—in this case there is only one captured browser, the one I’m using to look at this page. To “capture” a browser, simply navigate to the root JUTE UI page. Any submitted unit tests will be run through all captured browsers in parallel.

The middle frame, while not running tests, simply shows all available unit tests. This list is populated by recursively finding all *.html files in the test subdirectory. To run any test, click on one of the Run links. You can choose to run either with or without code coverage. To run multiple tests, check the checkboxes in the corresponding columns and click the Run Tests button. Remember, these HTML files are the “glue” HTML files we discussed in Chapter 4.

Finally, the Results panel will display the results and any optionally generated code coverage reports for all the tests that were run.

You can also run tests from the command line, and they will run within any captured browser:

% jute_submit_test --test path/to/test.html

Whatever you set as docRoot will be prepended to the path passed to jute_submit_test. Of course, you can run multiple tests from a single command also:

% jute_submit_test --test test1.html --test test2.html

Finally, you can read in test files from stdin:

% find . -name '*.html' -print | jute_submit_test -test -

This is similar to what the JUTE UI does to display all your tests in the UI.

Running a test with code coverage enabled will automatically generate an LCOV-style coverage report for that test, a link to which will be available in the Results column along with the JUnit XML output from the test itself.

The actual output files are, by default, placed in an output directory in the docRoot directory. You can change this using the outputDir configuration variable:

% jute config set jute:outputDir results

Note that the full path to this directory is docRoot + outputDir, so it must live within your docRoot. All test-result XML files and LCOV data are placed in this directory. The test result filenames are browser User Agent strings, so you can tell how your tests ran in each browser. Figure 8-2 shows the Results panel in the UI after running a test.

Figure 8-2. The Results panel after running a test in JUTE

The “toolbar” test—the name comes from the Test Suite name—has a JUnit XML results file (which we already saw in Chapter 4), an output file containing debugging information (mainly YUI Test output, anything your code prints to the console, and timing information), and a dynamically generated coverage report. Connecting another browser to JUTE by visiting its page shows both browsers in the Status panel (see Figure 8-3).

Figure 8-3. JUTE Status panel

Now both Chrome and Firefox are connected to this JUTE instance and are ready to run unit tests.

Running jute_submit_test will cause any submitted tests to be run in both browsers in parallel, and there will be results for both Chrome and Firefox in the Results panel. Here is the directory listing after running the “toolbar” test with both browsers connected:

% ls output/toolbar/
cover.json
lcov.info
lcov-report/
Mozilla5_0__Macintosh_Intel_Mac_OS_X_10_6_8__AppleWebKit536_11__
KHTML__like_Gecko__Chrome20_0_1132_21_Safari536_11-test.xml
Mozilla5_0__Macintosh_Intel_Mac_OS_X_10_6_8__AppleWebKit536_11__
KHTML__like_Gecko__Chrome20_0_1132_21_Safari536_11.txt
Mozilla5_0__Macintosh_Intel_Mac_OS_X_10_6_rv_12_0__Gecko20100101_
Firefox12_0-test.xml
Mozilla5_0__Macintosh_Intel_Mac_OS_X_10_6_rv_12_0__Gecko20100101_
Firefox12_0.txt

There is only one coverage report, regardless of how many browsers are connected. However, there are now two JUnit XML files and two debugging output files: one set of each for each browser, as named by its User Agent string.

Is your code on a headless server? Want even more automation? Instead of using a “real” browser, JUTE can utilize PhantomJS as a backend! The latest version of PhantomJS (1.6.1 as of this writing) does not require that an X server be running. PhantomJS integration with JUTE is trivial:

% jute_submit_test --test path/to/test.xml --phantomjs

Now our results will contain another set of JUnit XML results and a debug logfile for the PhantomJS browser. And as a special added bonus, you also get a snapshot of the “browser” right after all the tests finish (see Figure 8-4).

Figure 8-4. JUTE running tests

Figure 8-4 shows what the headless PhantomJS browser looks like on a headless Linux system. You can see the currently running test in the middle panel. You can also see the PhantomJS browser in the Status panel. The yellow highlighted tests in the Status panel are the ones currently running.

A final word on JUTE in your development environment: JUTE requires no changes to your test code (or code under test) to get dynamic code coverage reports and command-line execution, and all the other goodies JUTE provides. You can still manually load your “glue” HTML test files directly into a browser and execute them directly if you wish. When we discuss automating the build environment we will see how JUTE also fits very nicely in that scenario.

With its dynamic code coverage report generation, JUTE allows you to easily track your unit test progress while you are developing code, via either the command line or the UI. That is a big step toward testable JavaScript.

#!/usr/bin/perl

# Passed from SVN
my $REPO = shift;
my $TXN  = shift;

# Set up PATH
$ENV{PATH} = "$ENV{PATH}:/usr/bin:/usr/local/bin";

# The log message
my @logmsg = `svnlook log -t "$TXN" "$REPO"`;
#print STDERR @logmsg;

# Get file changeset
my @changes = `svnlook changed --transaction "$TXN" "$REPO"`;
my $failed = 0;
#print STDERR @changes;

# Find JS files
foreach (@changes) {
    my($cmd, $file) = split(/\s+/);
    # Only JSLint *.js files that haven't been deleted!
    if ($file =~ /\.js$/ && $cmd ne 'D') {
        # Text of changed file:
        # my @cat = `svnlook cat "$REPO" --transaction "$TXN" $file`;
        # OR just grab the pre-committed file itself directly
        # This script runs from the directory of the commit itself so
        # these relative paths are the uncommitted versions
            my @jslint = `/usr/local/bin/jslint $file`;
        if ($?) {
            print STDERR '-' x 20, "\n";
            print STDERR "JSLint errors in $file:\n";
            print STDERR '-' x 20;
            print STDERR @jslint;
            $failed++;
        }
    }
}

# STDERR goes back to client if failed
exit $failed;

my @changes = `svnlook changed --transaction "$TXN" "$REPO"`;

# my @cat = `svnlook cat "$REPO" --transaction "$TXN" $file`;

% npm install jscheckstyle -g

#!/usr/bin/perl

# Get file list
my @files = `git diff --cached --name-only HEAD`;
my $failed = 0;

foreach (@files) {
    # Check *.js files only
    if (/\.js$/) {
        my @style = `jscheckstyle --violations $_`;
        if ($?) {
            # Send pretty error output to client
            print @style;
            $failed++;
        }
    }
}

exit $failed;

% git commit index.js
The "sys" module is now called "util". It should have a similar
interface.
jscheckstyle results - index.js
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳┳┓
┃ Line   ┃ Function                     ┃Length┃Args┃Complex..┃
┣━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋╋┫
┃ 30     ┃ Injectify.prototype.parse    ┃197   ┃2   ┃27       ┃
┣━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋╋┫
┃ 228    ┃ Injectify.prototype.statement┃42    ┃1   ┃10       ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻┻┛

% npm install fixmyjs -g
% fixmyjs myFile.js

% fixmyjs -r myFile.js

% fixmyjs -p myFile.js

The automations made in the build environment are a superset of what is happening in the development environment. You do not want to make large complexity numbers fail the build if they are not also being checked in the development environment. Similarly, do not fail the build due to JSLint errors if you are not also running the code through JSLint in the development environment. We developers hate surprises in the build environment, so don’t try to spring any new requirements onto the code in the build environment that are not also present in the development environment.

Jenkins

Jenkins, formerly Hudson, is a nice tool for automating the build process. With lots of community-supplied plug-ins plus hooks for even more local customization, Jenkins does a good job of managing and tracking builds, with all the bells and whistles and a nice UI that anyone can use.

Installing Jenkins is relatively straightforward, especially if you have experience deploying WARs (Web application ARchive files), as that is how Jenkins is packaged. Download either the latest or the Long Term Support version of Jenkins, dump the WAR into the proper container directory, restart your server, and you should be good to go. If you want to get up and running very quickly to play around, simply download the WAR and run:

% java -jar jenkins.war

Jenkins will start up on port 8080. When it’s ready, you will see the Jenkins home administrative page (see Figure 8-5).

Figure 8-5. Jenkins home administrative page

Before we jump in and create a job, let’s take a quick look at some plug-ins that may be of interest. Click Manage Jenkins, and you will see lots of configuration options. For now, click Manage Plugins to be transported to Jenkins’s plug-in manager. From here you can update any currently installed plug-ins, install new ones, and see what you already have installed. By default, CVS and Subversion support are enabled; if you need Git support, click the Available tab and find the Git plug-in (see Figure 8-6).

Figure 8-6. Obtaining the Git plug-in

Check the Git Plugin box and install Git, and then let Jenkins restart itself. Be careful about restarting Jenkins on your own! You will have lots of Jenkins jobs, so if you ever need to restart Jenkins, let Jenkins do it. It will wait until there are no currently running jobs and then restart itself (this is done in Manage Jenkins→Prepare for Shutdown).

Now Git will be available as a source code management (SCM) system when you create a new Jenkins job. A lot of plug-ins are available for Jenkins, some of which we will encounter later.

Creating a Jenkins project

Now you can create a project. You basically need to tell Jenkins two things: where to find your source code repository and how to build it. At a minimum, Jenkins will check your code out into a clean area and run your build command. As long as your build command exits with zero, your build has succeeded.

So, go to the top-level Jenkins page and click New Job, and give your job a name. Do not put spaces in your project name! Then click “Build a free-style software project.” Click OK, and you are ready to configure your new job. Figure 8-7 shows the home page of a Jenkins project.

Figure 8-7. Jenkins project home page

Click the Configure link and start filling out the basics. For a Subversion project, the Subversion URL can look like the one shown in Figure 8-8.

Figure 8-8. Configuring an SVN repository in Jenkins

For a local Subversion repository, if you installed the Git plug-in you can put in a Git URL (even something on GitHub).

Under Build Triggers, it’s nice to “Poll SCM” repeatedly to pick up any changes. In Figure 8-9 I am polling Subversion every 20 minutes, and if something has changed a build will be kicked off (here is our continuous integration!).

Figure 8-9. Polling Subversion

Finally, you need to tell Jenkins what to do once it checks out your repository to actually do the build.

Here is a quick makefile that will run unit tests on all the code and then compress the code into a release directory to be blasted out to production web servers if all is OK:

DO_COVERAGE=1
RELEASE=release
UGLIFY=uglifyjs

SRC  := $(shell find src -name '*.js')
OBJS := $(patsubst %.js,%.jc,$(SRC))

%.jc : %.js
    -mkdir -p $(RELEASE)/$(@D)
    $(UGLIFY) -o $(RELEASE)/$(*D)/$(*F).js $<

prod: unit_tests $(OBJS)

setupJUTE:
ifdef WORKSPACE
    npm config set jute:docRoot '$(WORKSPACE)'
    npm restart jute
endif

server_side_unit_tests: setupJUTE
    cd test && find server_side -name '*.js' -exec echo
{}?do_coverage=$(DO_COVERAGE)" \; | jute_submit_test --v8 --test -

client_side_unit_tests: setupJUTE
    cd test && find client_side -name '*.html' -exec echo
"{}?do_coverage=$(DO_COVERAGE)" \; | jute_submit_test --v8 --test -

unit_tests: server_side_unit_tests client_side_unit_tests

.PHONY: server_side_unit_tests client_side_unit_tests unit_tests
setupJUTE

This makefile uses UglifyJS for code compression, but YUI Compressor and Google’s Closure Compiler work just as well. The makefile lives at the root of our application’s repository and has a src and test directory tree under it containing the source and test files, respectively.

Executing the prod (default) target will run all the unit tests and minimize all the code, assuming all the unit tests run successfully. The unit tests are all run through V8, so no browser is required. However, this may not be appropriate for all your client-side JavaScript tests, so use PhantomJS (--phantomjs) or Selenium (--sel_host) to run them through a real browser. You can even use “captured” browsers as long as at least one browser is captured to the JUTE instance running on the machine. Note that in our case we must configure JUTE when running under Jenkins so that JUTE knows where the document root is while Jenkins is doing a build. If you have a dedicated build box you could configure JUTE once to always point to the Jenkins workspace and be done. Regardless, dynamic code coverage information can be toggled on the make command line to turn off code coverage:

% make prod DO_COVERAGE=0

There is some makefile magic (or insanity, depending on your perspective) with the implicit rule for UglifyJS. Regardless of how you like your makefiles, this will transform all your JavaScript files into compressed versions in a directory tree that mirrors the src tree rooted under the release directory. When the build is finished, we simply tar up the release directory and drop it on our web servers.

OK, enough fun; let’s integrate this makefile into our Jenkins job. (Of course, you could use Ant as your build system and cook up and maintain a bunch of XML files instead; Jenkins merely executes whatever you tell it, so roll your own build system if you like. It can’t be any uglier than Ant, can it?)

So, back to Jenkins: simply add make as the build command (this assumes you checked in your makefile in your SVN root directory), as shown in Figure 8-10.

Save it and then execute a build, either by waiting for the SVN check to determine there are new files or by clicking Build Now. If all went well (why wouldn’t it?), you will have a successful build.

Figure 8-10. Configuring a build command in Jenkins

% java -jar selenium-server-standalone-2.28.0.jar -role hub

% java -jar selenium-server-standalone-2.28.0.jar -role node
-hub http://<HUB HOST>:4444/grid/register

% java -jar selenium-server-standalone-2.28.0.jar -role node
-hub http://<HUB HOST>:4444/grid/register -port 6666

-browser browserName=firefox,version=13,platform=LINUX

% jute_submit_test --sel_host <grid host> --sel_port 4444
--seleniums 5 --test -

selenium_tests:
    cd test && find . -name '*.html' -printf '%p?do_coverage=1\n' | 
    jute_submit_test --sel_host 10.3.4.45 --seleniums 5 --test -

Unit test output

All that remains (besides adding stuff to your build) is to have Jenkins recognize the unit test output (the JUnit XML files that JUTE generates), the coverage data (which JUTE also generates), and any other build data you want Jenkins to consider.

Conveniently, JUTE puts all test output into a (configurable) output directory called output by default. This directory exists in jute:docRoot, which conveniently is also the Jenkins workspace directory. So, to have Jenkins recognize our unit test results we simply configure our project with a post-build action of “Publish JUnit test result report” and use this file glob to pull in all test results (all JUTE test result output ends in -test.xml), as shown in Figure 8-11.

Figure 8-11. Publishing JUnit XML output in Jenkins

Now we’ll kick off another build, and when things go right the first time we will see what’s shown in Figure 8-12 on our project’s dashboard.

Note the link to Latest Test Result and the graph with the number of successful unit tests run—pretty slick!

Figure 8-12. Unit test result graph on a Jenkins project home page

Coverage output

Integrating code coverage is unfortunately slightly more complex in the latest version of Jenkins, as support for LCOV-formatted coverage files seems to be missing. So, we must first aggregate all the individual coverage files into one file and then convert that file into another format that Jenkins supports.

Aggregating all the individual coverage files (the lcov.info files in each directory) into a single file is easy using the lcov executable. Here is our makefile rule to do just that:

OUTPUT_DIR=output
TOTAL_LCOV_FILE=$(OUTPUT_DIR)/lcov.info
make_total_lcov:
    /bin/rm -f /tmp/lcov.info ${TOTAL_LCOV_FILE}
    find $(OUTPUT_DIR) -name lcov.info -exec echo '-a {}' \;
| xargs lcov > /tmp/lcov.info
    cp /tmp/lcov.info ${TOTAL_LCOV_FILE}

All this does is collect all the generated lcov.info files in the output directory and run them through lcov -a ... to aggregate them into a single lcov.info file, which will sit in the root of the output directory.

Now that we have the aggregated lcov.info file, we need to convert it to the Cobertura XML format. We can do this using a handy script provided at this GitHub project:

cobertura_convert:
    lcov-to-cobertura-xml.py $(TOTAL_LCOV_FILE) -b src
-o $(OUTPUT)/cob.xml

Adding those two targets to our original unit_tests target will generate all the information Jenkins needs to display code coverage information.

The next step is to install the Cobertura Jenkins plug-in. Once that is complete the Publish Cobertura Coverage Report option will be available as a post-build action, so add it and tell the plug-in where the Cobertura XML files reside (in the output/ directory), as shown in Figure 8-13.

Figure 8-13. Configuring Cobertura output in Jenkins

Rebuild your project, and voilà, you have a Coverage Report link and a coverage graph on your dashboard, as shown in Figure 8-14.

Figure 8-14. Coverage graph on the dashboard

Clicking on the Coverage Report link will let you drill down to individual files and see which lines were covered by your tests and which weren’t. Figure 8-15 shows what a coverage report looks like.

Figure 8-15. Sample coverage report

This output is very similar to the LCOV output format we saw in Chapter 5. Jenkins will now track your code coverage percentages over time, so you can watch the trend go (hopefully) up.

Complexity

We will add one more Jenkins plug-in, and then you are on your own. Earlier we discussed the jscheckstyle npm package, which coincidentally can output its report in Checkstyle format—and wouldn’t you know it, there is a Jenkins plug-in for that format! Even though you may be checking complexity numbers pre-commit, it is still a great idea to also generate those numbers as part of your build, for two reasons. One, it is easy to see at a glance the complexity of all the files in your project, and two, you can keep an eye on the complexity trends in your entire application. The dashboard Jenkins provides is also great for nondevelopers to easily see the state of the project. Hopefully that is a good thing.

The flow should be similar: install the Jenkins plug-in, update the makefile to generate the required files, and then configure your project to use the installed plug-in and to point to the generated files. So, let’s do it!

First we will install the Checkstyle Jenkins plug-in and then add these targets to the makefile to generate the complexity information via jscheckstyle:

CHECKSTYLE=checkstyle
STYLE := $(patsubst %.js,%.xml,$(SRC))
%.xml : %.js
    -mkdir -p $(CHECKSTYLE)/$(@D)
    -jscheckstyle --checkstyle $< > $(CHECKSTYLE)/$(*D)/$(*F).xml

This is very similar to the UglifyJS code shown earlier. We are transforming the JavaScript files in the src directory into XML files in a Checkstyle mirrored directory. Note the use of the - before the jscheckstyle command—jscheckstyle exits with an error if it finds any violations, but that would then stop the build. With a pre-commit hook this is probably overkill; however, failing the build due to violated complexity constraints is not the worst thing in the world.

So, append the $(STYLE) prerequisite to the prod target:

prod: unit_tests $(OBJS) $(STYLE)

and all those files will be generated on your next build. Now to tell Jenkins about it: on the Configure screen of your project add the “Publish Checkstyle analysis results” post-build action, and configure it as shown in Figure 8-16.

Figure 8-16. Publishing Checkstyle output in a Jenkins project

Here we are just telling the plug-in to look in the checkstyle directory of the Workspace root and pull out all the XML files to analyze. Click Build and bask in the results (see Figure 8-17).

This graph will now be on your project’s dashboard, and clicking on it (or on the Checkstyle Warnings link that is also now on your dashboard) will show you a history and what all the current warnings are, including any new ones present in this build. You can drill further into the details of each warning and all the way down to the code itself to view the offending code. Great stuff!

Figure 8-17. Checkstyle output graph on a Jenkins project home page

JSLint

Integrating JSLint with Jenkins is very similar to the previous integrations—for this, you need the Violations Jenkins plug-in. Go ahead and install it, and you will see that it also handles Checkstyle-formatted files. We will look at that later; for now, the Violations plug-in requires JSLint output to be in a certain XML format, which is simple to generate:

<jslint>
    <file name="<full_path_to_file>">
        <issue line="<line #>" reason="<reason>" evidence="<evidence" />
        <issue ... >
    </file>
</jslint>

If you run the jslint npm package with the --json argument, you will see it is a trivial transformation from the JSLint JSON to this XML format. My implementation of the transformation is available at the Testable JS GitHub project.

The idea here is to run JSLint on our codebase, output that in XML format, and tell the Violations plug-in where to find the XML. So first we will add the standard stuff to our makefile:

JSLINT=jslint
JSL  := $(patsubst %.js,%.jslint,$(SRC))
%.jslint : %.js
    -mkdir -p $(JSLINT)/$(@D)
    ./hudson_jslint.pl $< > $(JSLINT)/$(*D)/$(*F).jslint

Then we will add the JSL targets to our prod target:

prod: unit_tests $(OBJS) $(STYLE) $(JSL)

And we are ready! Of course, to just run JSLint in isolation, simply add this target:

jslint: $(JSL)

After checking that in, install and configure the Violations plug-in with the location of the *.jslint XML files (see Figure 8-18).

Figure 8-18. Configuring report violations in Jenkins

You’ll note that while I was at it I also configured the location of the jscheckstyle output. Now rebuilding your project will embed on your project’s dashboard the snazzy Violations graph shown in Figure 8-19.

Clicking on it will give you a breakdown of all the JSLint and Checkstyle errors in your code, and allow you to drill down to each individual file to see exactly what is going on. When viewing the file line by line, hovering your mouse over the violation icon will display detailed error information about that line.

Figure 8-19. Jenkins Violations graph on project home page

Duplicate code

Although doing a build is very helpful in terms of finding all the duplicate code in your project, some duplicate-code-finding tools can be smart about ignoring whitespace and comments and comparing the underlying tokens and syntax tree to really find duplicate or very similar chunks of code.

One such tool is dupfind. It parses through all your code looking for duplicated sections. You can tweak the “fuzziness” of the matches and see what pops out. This command-line tool is an excellent addition to your automated build process. It can output a CPD-compatible XML file that—surprise, surprise—a Jenkins plug-in can visualize.

Installing the Duplicate Code Scanner plug-in creates the “Publish duplicate code analysis results” post-commit action, which you can enable in your project (see Figure 8-20).

Figure 8-20. Publishing duplicate code analysis in Jenkins

The priority threshold values allow you to configure how many duplicated lines indicate a normal problem or a very big problem. The plug-in will then track and graph all the duplicated sections of code. In the Advanced configuration you can set thresholds for when this plug-in will mark a build as “unstable” or even “failed” (see Figure 8-21).

Figure 8-21. Configuring priority threshold values in Jenkins

Installing dupfind is easy; get the dupfind.jar file from dupfind’s GitHub and add a line similar to this to your makefile:

dupfind: $(SRC)
    java -Xmx512m -jar ./dupfind.jar > output/dupfind.out

Then add the dupfind target to your prod target, and you are ready to configure dupfind itself. One of the places dupfind looks for its configuration file in the current directory is in a file named dupfind.cfg. Here is one now:

{
    min:        30,
    max:        500,
    increment:  10,
    fuzzy:      true,
    cpd:        true,

    sources:
    [
        {
            name:   "myProject",
            def:    true,
            root:   ".",
            directories:
            [
                "src"
            ],
            include:
            [
                "*.js"
            ],
            exclude:
            [
                "*/.svn",
                "*-[^/]*.js",
            ]
        }
    ]
}

This JSON-formatted configuration file tells dupfind specifically what to do. The most interesting bits are the fuzzy property that allows dupfind to do fuzzy matches (it will ignore variable names, for instance) and the sources array that allows us to fine-tune which directories and files dupfind should investigate and which to skip.

Once you have configured the file, on your dashboard you’ll get a snazzy duplicate-code graph, as shown in Figure 8-22.

Figure 8-22. A graph showing trends in duplicated code

From this graph you can then drill down into the details, as shown in Figure 8-23.

From here you can drill down to the files themselves and see the detected duplications. In this case, dupfind found a duplicate chunk of code in the same file. Remember, the priority of the duplicated code is set while configuring the plug-in; here the priority is “low” because there are only six lines of duplicated code.

Figure 8-23. Details of the duplicated code graph

The Full Monty

Figure 8-24 shows a snapshot of a Jenkins dashboard with all the aforementioned plug-ins disabled and building—that’s a good-looking dashboard!

Figure 8-24. A fully configured Jenkins project home page

% ssh -p 64812 localhost build MyJavaScriptProject -s

% java -jar ~/Downloads/jenkins-cli.jar
-s http://localhost:8080 build MyJavaScriptProject -s

Whether you’re deploying to 1 server or 50,000 servers, some things remain the same (and some, of course, are radically different). After verifying that your code is good to go to production, you must shut down the current code cleanly and bring up the new code. The goal is to drop as few connections as possible (if any). Most web servers have a “graceful” restart feature that should be utilized. If you have only one server, connections will be refused while the server is down. If you’ve got 50,000 servers behind various load balancers, the process will (hopefully) be seamless.

Rollback goes hand in hand with deployment. You should be ready to switch back to the old code as quickly as possible—not that anything will go wrong, of course. Ideally, merely flipping a symlink chooses between the “old” and “new” code—leave the old code on the box while you upgrade.

An upgrade can look like this:

For instance, suppose the DocumentRoot in your Apache configuration file points to a symlink at /var/www/current that resolves to /var/www/VERSION_X. Now you put /var/www/VERSION_Y on the box, and when Apache is stopped, you change /var/www/current symlink from VERSION_X to VERSION_Y.

When a rollback is necessary, simply gracefully stop the server, reposition the symlink, and then start the server. Of course, you will have a script that does all that for you automatically, right?