Setting Up Jasmine + Selenium + PhantomJS

I've started a new project as a means to develop skills working with Jasmine, Selenium, Karma, AngularJS, MongoDB and whatever incidental tidbits of cool webdev technologies crop up along the way.

My very first story was to create the landing page for my app which will have a status header on it.  As the first story, the header content is static -- because no way of changing it has been developed yet.  Despite being static, I still want a test for it and set about creating a test in Jasmine which would use Selenium to confirm the existence of this header and text within it.*

Surprising challenges stemming from an all-JavaScript environment and a non-Mocha choice in testing frameworks arose which made this far more time-consuming than expected.

So, for posterity, I present the steps required to get started.

Installing the Tools

Starting from my code on "the outside" of the environment, I first needed the Jasmine test framework in which to work:

bower install jasmine

Installing jasmine using Bower

A core aspect of testing this behavior is loading up a browser and verifying that the header is indeed present. This means bringing in Selenium bindings that I can use within my Jasmine tests.

npm install selenium-webdriver

Installing selenium-webdriver with NPM

Theoretically one can leverage selenium-webdriver from a client page, however I will want to incorporate this into my automated testing and see no reason to avoid it. All of that is to say that I needed a Jasmine test runner for node.

npm install -g jasmine-node

Installing jasmine-node globally with NPM

FYI, in order to install this I needed to reconfigure my npm repository to http.

I have really come to enjoy using Koding for my development, because it lets me maintain my workspace across any machine with Internet access and a modern browser. However, as a hosted terminal-only VM, having Selenium try to pop open Firefox and Chrome won't exactly work.  So I brought in PhantomJS for headless browser testing.

npm install -g phantomjs

Installing PhantomJS globally with NPM

Notes on the Tests

Working with selenium-webdriver is pretty frustrating at times, because it often fails in complete silence leaving you floundering for answers.

Here are the critical items I found this way:

• The documentation shows three styles of test writing: one in Java, a second using continuation passing (i.e. callbacks) and a third using promises. Promises in selenium-webdriver are apparently not fluency sugar, promises are required! Expect a long, but readable, chain of "then" methods.
• findElement does not pass undefined if nothing is found, it instead "rejects" the promise and flows to the error handler.
• Tip: instead of "expecting false to be true" in order to force a failed expectation in the error handler, I suggest "expecting the error not to be defined." This has the added benefit of outputting the error object's contents in the test log.

Get it Running

Lastly fire up Selenium and set jasmine-node loose on the tests. For bonus points, it can be set it to automatically rerun the tests when changes are detected in the specs (i.e. the tests) or the code file(s).

java -jar selenium-server-standalone-2.40.0.jar &
jasmine-node --autotest tests/ --watch index.html

The Future

While selenium-webdriver is capable of launching the stand-alone server from code, I have yet to figure it out and am living with one additional command (OH NOOOES!).


*It "appearing" constitutes a behavior which adds value according to a user story, and so it should be protected against regression.

RequireJS Paths: An Off-the-Shelf Plugin Engine

The RequireJS documentation doesn't do justice to the power of the paths configuration option; the sample configuration they include hints at its potential, but it’s never fully spelled out.

Code sample from the RequireJS Configuration Options API documentation

Paths as Mapping

The documentation describes the paths option primarily as a way of resolving the name of a module to an unconventional path from where it must be loaded. Though simple, this use case can be very useful.

One example would be CDNs:

paths: {
'jquery': '//code.jquery.com/jquery-1.10.2.min',
'jqueryui': '//code.jquery.com/ui/1.10.4/jquery-ui',
'webfont': '//ajax.googleapis.com/ajax/libs/webfont/1.5.0/webfont'
}

Paths to jQuery, jQuery UI and Web Font CDNs

Another common use case would be Bower modules:

paths: {
'bootstrap': 'bower_components/bootstrap/dist/js/bootstrap.min',
'jquery-rescope': 'bower_components/jquery-rescope/src/jquery-rescope'
}

Paths to Bootstrap and jQuery-Rescope Bower modules

Paths as Tokens

However what is actually illustrated in the documentation isn’t a one-to-one mapping -- unless they’re loading the v1.0.js module from the some folder -- it’s much more powerful!

By mapping the path “some” to “some/v1.0,” they are creating a replacement token which will interpret requiring “some/module” as needing to actually load “some/v1.0/module.”

The specific example in the documentation demonstrates how RequireJS frees you from explicitly referencing versions in your modules while allowing you to maintain that information on the file system. Which is interesting, but it doesn't exactly solve a critical problem.

What this example demonstrates generally, is an ability to swap compatible modules -- not just across versions, but with completely independent implementations -- via configuration without needing to write any special support for it in our applications. Add to this the fact that RequireJS is configured in JavaScript (as opposed to through a static file of some kind), and we can generate a path configuration based on whatever criteria we can imagine.

Some possible applications of this include:

• browser feature detection
• HTML5: map a path for “storage” to a folder of modules using localStorage
• legacy: map the “storage” path to folder of modules using a database-backed web service
• layering security
• anonymous users: map to modules which only display messages that authentication is required
• authenticated users: map to modules which actually attempt privileged operations
• sharing a common code base
• mobile: map to modules which implement functionality using Cordova APIs
• Web: map to modules which implement functionality using browser and server APIs

Example

As a concrete example, I’ve written a simple demonstration which has two different modes of interacting with the user, and it switches between them without alteration to the code (or even any awareness of there being different modes in the app code) outside of the RequireJS configuration.

Setup

The entry point is my main.js file. This is where I bootstrap the environment before launching my application.

/*globals requirejs*/
(function (require) {
 'use strict';
 require(['paths'], function (paths) {
         require.config({
             paths: paths
         });

         ...
 });
})(require);

Configuring require using paths module

I’ve written the main module to load the paths as a separate module, so that it can be solely concerned with start-up operations.

The paths module interpolates the app's configuration into a RequireJS-compatible paths object.

define([
    'config'
], 
function (config) {
    'use strict';
    
    return {
                'jquery': '//code.jquery.com/jquery-1.10.2.min',
                'output': 'output/' + config.outputMode
            };
});

Mapping output path token based on configuration

The config module is "where the magic happens." For this demo, I'm determining the environment state based on the query string and sets it as the app's output mode.

define(function () {
    'use strict';
    
 function getOutputMode () {
        var outputModes = 
        [
         'obnoxious',
         'polite'
        ],
        currentOutputMode = 0,
        requestedOutputMode;
  
        // Dynamically set mode from query string
        requestedOutputMode = parseInt(
            (window.location.search.match(/[?&]mode=(\d+)/) || [])
            [1]);

        if(requestedOutputMode > 0 && requestedOutputMode < outputModes.length) {
            currentOutputMode = requestedOutputMode;
        }

        return outputModes[currentOutputMode];
 }
    
    var exports = {};
 
    exports.outputMode = getOutputMode();
    
    return exports;
});

Setting output mode in configuration based on query string

Now that RequireJS is configured to load modules from the correct path, we can return to the main module and start our demo app.

/*globals requirejs*/
(function (require) {
 'use strict';
 require(['paths'], function (paths) {
         ...

  // Launch our app
  require(['app'], function (DemoApp) {
   var demo = new DemoApp();

   demo.run();
  });
 });
})(require);

Launching demo app

The Demo App

Within the demo app, I require in the three output modules and assign the returned classes to local names.

define(
[
 'output/prompt',
 'output/confirm',
 'output/message'
],
function (Prompt, Confirm, Message) {
 ...
});

App module requiring and accepting prompt, confirm and message output modules

Then, within the body of the demo app, I can use the required-in modules, according to their individual contracts, in complete ignorance of how they are implemented.

 function EchoDemoApp () {
  var me = this;
 }
 
 EchoDemoApp.prototype.prompt = function () {
  var me = this,
   promptMessage = new Prompt('What do you want to say?');
   
  promptMessage.display(function (response) {
   var input = response || 'nothing',
    confirmation = new Confirm('Are you sure you want to say "' + input + '"?');
   
   confirmation.display(function (confirmed) {
    var output;
    
    if(confirmed) {
     output = new Message(input);
     output.display();
    } else {
     me.prompt();
    }
   });
  });
 };

 EchoDemoApp.prototype.run = function () {
  var me = this;
  
  me.prompt();
 }

Paths to jQuery, jQuery UI and Web Font CDNs

View a running version of the demo
Browse, download or fork the source from this article on GitHub

TDD *is* BDD and Multi-Class Modules

My friend and colleague, Dan Martinez, recently pointed me to Ian Cooper’s NDC talk, TDD where did it all go wrong. This is definitely recommended viewing for practical and “back to basics” TDD for neophytes and people who think they’re experts alike.

For me, I took away some new concepts, but it also clearly validated a lot of the practices that have emerged in my work and that I’ve picked up from my colleagues.

A particular point which is worth repeating is that TDD is BDD. Good tests test behavior, and behavior is expressed through public interfaces.

Restraining tests to interfaces doesn’t lead to an underpowered test suite, because all internal code should exist in the service of some behavior. Therefore testing the public interface for that behavior will provide complete coverage; any uncovered code implies unintended behavior.

This point is easily forgotten and probably often dismissed by recent converts as lazy or impure. However it is powerful, because it leads to focused development, lean suites and less rigid tests.

Applied to JavaScript Modules

Adding to this idea, it has implications for my current world of JavaScript in an unexpected way.

Modules, whether following the simple IIFE pattern or a CommonJS standard, export all functionality in an inherently public fashion. That implies, for the purposes of TDD, that a module is a behavior-level component. Which means that non-behavioral components, including support classes, must be completely scoped within and hidden by a module.

This is a somewhat hard pill to swallow for me, because, as a long-standing style practice (that I had ingrained in me from StyleCop in C#), I follow a “one class/one file” rule. But I’m trying to look at it as permission to break the rules and get that edge back into my coding!

Yeah. I’m bad.

jquery-rescope: DOM Mocking Made Easy

It’s easy to declare a technique to be correct, but it’s another thing to try and make it practical.

So after writing about Oreo Testing, I decided to convert the getJqueryMockDocument function from my sample into something that could be distributed and used by others.  Given its nature, a  jQuery plugin seemed like the most natural option.

It should surprise no one who's read this far that I rewrote it using TDD to ensure that it:

• follows AMD conventions
• follows jQuery’s basic and advanced guidelines for plugin creation
• performs its expected functions across all common, current browsers (of course)

Usage: Updating the Façade Example

Its usage should be straight-forward enough: invoke the plugin to separate a selected (or created) node from the current DOM and isolate it into a new one.  

Using our earlier façade example as a demonstration, it would be changed by:

1. Adding a reference to the rescope plugin:
   

   <script src="sampleViewFacade.js" type="text/javascript"></script>
   <script src="sampleViewFacade.tests.js" type="text/javascript"></script>
   <script src="jquery.min.js" type="text/javascript"></script>
   <script src="jquery-rescope.js" type="text/javascript"></script>
   

   HTML script tags including test JavaScript as well as jQuery and rescope plugin

2. Removing the getJqueryMockDocument function and replace all calls to it with $(...).rescope():

   $mock = $('<div class="sample"><input id="correctElement" type="checkbox" /></div>').rescope();
   …
   $mock = $('').rescope();
   …
   $mock = $('<button id="clickme">').rescope();
   

   Replacement lines for calls to getJqueryMockDocument using rescope

In my opinion, not only is this obviously much easier to incorporate into other projects, this is much more concise and readable.

Set it Free(ly licensed on GitHub)! 

The last step in distributing software is making it available! I have done so, not through some run-of-the-mill lazy link on my blog!  Oh no!

I tried something new (and long overdue) and created a repository for jquery-rescope on GitHub. I cordially invite you to browse the code, download it, submit pull requests, write up issues and otherwise make me feel like a real open sourcerer!

More to Come? 

For all the pixels I've spilled on this topic, I doubt this will be the last time that I write about it.

For example I stumbled into the interesting practice of wrapping each test modules in an IIFE so that I could run them all from a single HTML page without corrupting each test's namespace.

Most importantly, I haven’t found or heard any feedback that this combination of black-box and white-box testing is widely known or practiced.  Given all of its advantages, I can imagine myself continuing to advocate it as the Right Way to do TDD from now on.

jquery-rescope plugin on GitHub

Download my updated code from this article
Browse the source from this article on GitHub

querySelector vs. jQuery: Proving Black-Box Testing in Practice

Recently a colleague of mine, Justin Tullgren, made the point on Twitter that jQuery selectors are significantly slower than their (lesser known) native browser equivalents: querySelector and querySelectorAll.  This revelation leads to exactly the sort of changes that black-box testing a view façade allows you to make because it will won't change its behavior even though it improves the process.

To demonstrate, consider the getCheckbox implementation from our example using jQuery.

var result = $('.sample :checkbox:first').eq(0);
  
if (result.length === 1) {
 return result[0];
}
  
return null;

Using a jQuery to select our checkbox and return the DOM element or null

Since querySelector or querySelectorAll only operate on CSS selectors, we need to replace jQuery's :checkbox pseudo-class selector with the pure CSS equivalent of input[type="checkbox"].  We can avoid worrying about the CSS to replace the :first pseudo-class by using querySelector to only return the first element that matches the query.

All together, our replacement for the four lines (depending on how you count them) of code above is just a single line:

return document.querySelector('.sample input[type="checkbox"]');

Using querySelector to get the DOM element for our checkbox with a CSS selector

This does introduce a new dependency into our function which we have to inject or resolve in order to maintain our unit of work's isolation.

Personally, I like how resolving the document reference from the already-injected jQuery dependency means we won't have to change any outside code.

function SampleViewFacade ($) {
 var me = this,
  document = $('body')[0].ownerDocument;

Declaring a new document variable from the ownerDocument of the body

I might try to justify this as my using jQuery as a consistent gateway to the DOM, but mostly I think it's cool!

The end of the story is that we have just introduced a significant cross-browser performance enhancement, while maintaining our application's behavior.

Go ahead and run the tests to prove it to yourself.

Download the code from this article
Browse the source t on GitHub