How To Build Testable and Framework Agnostic Single Page Applications with Node.js

In a previous blog post, I spoke about the package principles of cohesion:

  • The Release/Reuse Equivalency Principle
  • The Common Closure Principle
  • The Common Reuse Principle

In this blog post, I will use the principles of package cohesion to build cohesive npm packages, and I will use these npm packages to build testable and framework agnostic single page applications.

For this demonstration, we will create a fake analytics dashboard. Here is what the final product will look like.

Screen Shot 2016-01-31 at 10.14.36 PMGathering Requirements

We will describe the application requirements using the “User Story Mapping” approach.

The following snippet describes the feature of our application

We want our “system under test” to be testable; so, we need to place some architectural restrictions to guarantee “testability”.

At a minimum, a testable system must have the qualities of (a) observability, and (b) controllability.

Observability refers to the property that I can arbitrarily observe the states of the “system under test”, and controllability refers to the property that I can put the “system under test” into an arbitrary state.

The two properties are inherently related to each other: you can’t fully observe a “system under test” that you can’t fully control, and there we don’t care to fully control a “system under test” that we can’t fully observe.

I claim (but will not prove) that these architectural restrictions guarantee “testability”.

In order to support the “controllability” requirement of our architecture, we will use the following background block to load fake data into our “system under test” for every new test run.


By design, a user story will have various scenarios, and we will use the scenarios to determine what needs to be “observable”.

For this demonstration we will consider the following scenarios:

  • Visit the visualization page
  • Change the selected date on the page
  • Aggregate the items by month
  • Aggregate items by year

This snippet shows the scenario description for “visit visualization page”

This snippet shows the scenario description for “change the selected date on the page”:

This snippet shows the scenario description for “aggregate the items by month”:

This snippet shows the scenario description for “aggregate items by year”:

You can see the complete feature file here.

Testing the User Story

The following code snippets uses cucumber.js and babel (an es6 to es5 transpiler) to test the user stories. I use babel because it lets me use generators and coroutines to simplify the asynchronous nature of selenium code.

This snippet initializes the “system under test” based on the data provided in the background block for the user story. This satisfies the “controllability” property of our architecture.

This snippet executes the action(s) that change the state of the “system under test” for the behavior “When I visit the page at <some_url>”:

This snippet executes the action(s) that change the state of the “system under test” for the behavior “When I select the date <some_date>”:

This snippet executes the actions(s) that change the state of the “system under test” for the behavior “When I select to aggregate by <some_aggregation_type>”:

This snippet executes the post conditions checks of the “system under test” for the block “Then I should see a bar chart for <some_title>”.

Note: I will skip the rest of the blocks for brevity’s sake.

In the acceptance tests, I use a page object to encapsulate the data retrieval algorithms for each page.

For example, the following code snippet shows how the page object encapsulates the algorithm that “observes” when the page has finished loading.

This test looks for a DOM element with the html attribute “qa-chart-type”, and then waits for it to change.

We have to do this because the SPA fetches data using a http request when if first loads, and we want to detect when the SPA receives a response.

However, since we cannot easily detect when the SPA receives an http response, we make the SPA communicate this to our test script by creating and updating special “Quality Assurance” html attributes.

This makes testing with selenium much easier and maintainable.

I also created a page object factory to easily change implementations of the page object. It uses the same principles of a “contract test” that I mentioned in my blog post “Contract Tests: or, How I Learned to Stop Worrying and Love the Liskov Substitution Principle”.  

Let’s suppose that we implemented our application using (a) Backbone.js, and (b) React.js.

In order to test a Backbone implementation, we could use the following code

In order to test a React implementation, we could use the following code

This is what running the cucumber application looks like when I test a React implementation:


You can see the complete test suite here

Building Our Components

Suppose that you had the following directory structure for a JAVA application

  • src/
    • use_case001/
      • command/
      • delegate/
      • model/
    • use_case002/
    • use_case003/
    • controller/
    • view/
      • View001.jsp
      • View002.jsp
    • model/

This is an example of a “monolithic” or “big ball of mud” application architecture.

Architects typically have nothing but contempt for this architecture due to its well known rigidity, fragility, immobility, and viscosity.

These are well known application level architectural properties:

  • rigidity measures how easy an architecture can respond to change.
  • fragility measure how likely something will break when making a change
  • mobility measures how easy an architecture can support moving code
  • viscosity measure how easy an architecture supports maintaining the original design

When faced with a monolithic architecture, most architects I know would refactor the monolith into something that looks like this.

  • src/
    • controller/
    • view/
      • View001.jsp
      • View002.jsp
    • model/
  • lib/
    • use_case001.jar
    • use_case002.jar
    • use_case003.jar

Each .jar file is a self contained components that is independently testable, releasable, and versioned.

You might think that simply moving code from a directory to a .jar file does not significantly improve the design. However, when applied properly, it has a huge influence on reducing rigidity, fragility, viscosity, and increasing mobility.

We will use this approach, but in this case we will use npm modules as components: a npm module is equivalent to a JAVA .jar file; so, all the same rules apply.

I will use the discipline of Responsibility Driven Design to guide the cohesion strategy for our components. Responsibility Driven Design makes component “responsibility” the most important organizing principle for code.

I claim (but will not prove) that organizing our components by “responsibility” will force our components to obey (a) the Reuse-Release Equivalency Principle, (b) the Common Closure Principle, and (c) the Common Reuse Principle.

From the scenarios in the user story, I can identify the following responsibilities:

  • Bar Chart Visualization
  • User Interface Interaction
  • Data Retrieval
  • QA HTML Attribute Generation

Therefore, I will respectively create the four following packages:

  • analytics-chart
  • analytics-facade
  • analytics-service
  • qa-locator-utility

Create the “Analytics Chart” Component

The actual details of how I created the component are not important; so, I will not talk about it.

However, I feel that I should mention the unit tests I wrote for the visualizations because it isn’t a common thing.

I created unit tests to prove partial correctness of my application using the approach I describe in my previous blog post.

For example, the following code snippet tests the visualization for some items.

This test verifies that certain DOM elements appear in the svg canvas. I consider it a very weak test because there is a good chance that it could pass and the visualization could still be wrong. However, it is also a cheap test to write; so, there is still value in writing it.

You can see the completed npm package here.

Create the “Analytics Facade” Component

This component encapsulates all the user interface “glue logic” (i.e. identifying which screen or page to display), and we use the command pattern and delegation pattern to promote loose coupling between the user interface and this component.

For example, these are the cucumber features that I wrote for this component.

From a client’s perspective, they only need to know how to execute a command from the facade, and how to delegate tasks to the facade. The cucumber tests above provide a very high level description of what types of commands and delegates this facade exposes.

For the sake of completeness, I will also show you the step definitions for this feature.

You can see the completed npm package here.

Create the “Analytics Service” Component

This component simply makes a request to our remote server and return the json results. It isn’t very interesting; so, I will not discuss it.

You can see the completed npm package here.

Create the “QA Locator Utility” Component

Officially, we do not need this component, but we would like to have an easy method to locate elements in our window’s DOM using xpath. This component encapsulates any algorithms that we might need to simplify the process of creating html attributes for the purpose of writing acceptance tests.

I don’t consider it a very interesting component; so, I will not discuss it. 

You can see the completed npm package here.

Composing the Components Into A Single Page Application Framework

To demonstrate how to migrate the application between frameworks, I will compose the components into (a) Backbone 1.2, and (b) React 0.14.

The following component diagram shows the general relationships between the components and framework.

Screen Shot 2016-02-03 at 11.27.24 PM

Backbone 1.2 and React 0.14

We have placed the bulk of the applications functionality inside of framework independent components. Therefore, in order to create a backbone version or a react version of the application, we have to create a special component that coordinates between our “independent” components and the framework.

In the case of React, we created the component backbone_app.

In the case of Backbone, we create the component react_app.

For example, here is the entry point for our Backbone application:

Here is the entry point for our React application:

The parallels in the code are very apparent. I will not go into detail into the code bases because it is not important. I only care about the “shape” of the design.

You can find the Backbone implementation here, and the React implementation here if you really care to dig into the code, however.


This approach might seem very complicated for such a simple application … and it is.

In reality, this approach only makes sense once your application reaches a certain scale. However, simple applications have a tendency of becoming big applications, and it is very expensive to put a test harness on an already existing system with no tests.

Personally, I recommend you always build an application with decoupled testable components from the very beginning because that investment will pay large dividends in the long run.

Further, decoupling your components from the framework has huge benefits even if you have no intention of switching frameworks.

One practical “use case” is with automated testing.

When you decouple your components from the framework then you can test the bulk of your application independent of the framework. This significantly simplifies the overall testing process.

In fact, the package principles were partially created to minimize the work of creating and maintaining tests.

In a future post, I will show you how you can use a Continuous Integration tool to automatically run your tests whenever someone releases a new version of a component.

That should demonstrate the practicality of strictly following package principles.


How to Build React Applications with Node.js, Jasmine, Babel, and Gulp

TL;DR: you can find the entire code at my github repository.

Facebook’s React has completely changed the way that I write applications. From my perspective, most javascript frameworks unnecessarily force you into particular programming styles. For example, I often hear people tell me to do things the “angular way” (whatever that means).

This isn’t necessarily a bad thing. Programming standards enable team development. However, I believe that the software architect or the team itself should develop those standards. Framework designers do not know your particular needs and concerns.

In the end, framework designers try to solve their problems. They do not generally care to solve your problems. Many times our problems will overlap with their problems, but it becomes incredibly hard to development when they do not.

We do not always know what designs work at different stages in our software lifecycle; so, we need to have as much control over the design of our applications as possible

In my opinion, React has a much better design simply because it makes much less assumptions.

Consider Angular 1.x. While it is a great framework, it also has an all or nothing philosophy. It is very hard to use it’s data-binding feature without also using its controllers, directives, modules, etc …

React only concerns itself with views.

This makes it possible to create a customized architecture around my particular use cases.

I created simple todo application that demonstrates how you can do this.

I would like to use this blog post to demonstrate in a step-by-step way to build it.

First let’s describe the use case for the application.

Gather the Requirements

Suppose we have the following requirements for our todo application

Use Case 1.0: Add List Items

We expect to give a list item to the application. The application should store this list item, and provide visual feedback that it has stored it.

Use Case 1.1: Detect Invalid List Items

We consider an empty string as invalid input. If we give invalid input we expect the system to detect it and give some visual feedback to the user about it.

Use Case 2.0: Remove List Items

We expect the application to allow us to remove items. The application should provide some visual of all the list items, and it should expose some way to remove individual list items.

When we remove a list item, the application should provide some visual feedback about removing the list item.

Decide on an Tool Set

In order to build the application, we need to make some initial design decisions.

For this tutorial, I decided to build the application in the following tools:

  • React + Babel for views
  • Node.js for the main application
  • Jasmine for testing
  • Gulp for building the application

Setup the Project

I will assume that you are using linux.

Create a directory for the project

change to the directory

Initialize the directory as a node project

Install (a) gulp, (b) jasmine, (c) browserify, (d) eventemitter, (e) run-sequence, and (f) vinyl-source-stream with the following commands:

Create the following folder structure

  • src/common
  • src/model
  • src/view
  • test
  • app

with the following commands

We will put (a) our react code in the “src/view” folder, (b) our node code in the “src/model” and “src/common” folders, (c) our jasmine tests in the “test” folder, and (c) our application into the “app” folder.

Build the Model

Let’s encapsulate the algorithms that fulfill these uses cases into a single node.js module.

Create the following file: src/model/TodoListModel.js.

TodoListModel references another node file called Guid. By design, we force the caller of TodoListModel.addItem to provide a guid as an argument.

I did this to make unit testing easy. We will illustrate unit testing in the next section.

Create the following file: src/common/Guid.js

Create the Unit Tests

We need to validate that TodoListModel actually implements our use cases correctly. We will create separate jasmine specs for each use case.

Create Tests for Use Case 1.0

We want to verify that the model obeys the following constraints when we add list items:

  • The model adds the list item properly when we add one list item
  • The model adds list items properly when we add two list items
  • The model fires events that informs subscribers that the model has added a list item

Create test/AddListItems.spec.js with the following contents to validate that our model obeys the rules for “Use Case 1.0”.

Create Tests for Use Case 1.1

We want to verify that the model obeys the following constraints when we add add list items:

  • Detect when the caller does not provide a valid list item
  • Detect when the caller does not provide a valid guid
  • Verify that the model fires the proper events for an invalid input

Create test/DetectInvalidListItem.spec.js

Create Tests for Use Case 2.0

We want to verify that the model obeys the following constraints when we try to remove items:

  • The model properly removes one item
  • The model properly removes 2 of three items
  • The model fires the proper events when it removes items

Create test/RemoveListItems.spec.js

Execute Unit Tests

We will use gulp to execute our unit tests.

In the main directory, create gulpfile.js with the following contents

Change the NODE_PATH to include ./src. This will ensure that model/TodoListModel.js and common/Guid.js are discoverable.

Our gulp file will now execute our jasmine tests by default. Let’s run it and see the result.

Build the Gulp Workflow

Now that we have a working model let’s build the application. I want to have a very simple deployment. I would like the entire application to run using this html.

I want bundle.js to bootstrap the entire application for index.html.

Let’s modify gulpfile.js to support this.

This will browserify all our react code (which we have not created yet) and package it into bundle.js in the app folder. Further, gulp will use babel to transpile our react code into ES5 javascript. We want to use babel with react because it will provide us with a better syntax than standard javascript.

Build the Views

Create src/Main.jsx with the following contents.

This code shows that we have a UI with three general components:

  • A message component
  • An input component
  • A list component

Further, each component takes a TodoListModel instance as an argument to it’s constructor.

Let’s build out each component one at a time.

Create a MessageArea Component

Create src/view/MessageArea.jsx

Create InputArea Component

Create src/view/InputArea.jsx

Create a TodoList Component

Create src/view/TodoList.jsx

ListBox.jsx creates several ListItems components as children.

Let’s create the component definition.

Create src/view/ListItem.jsx

Build the Application

We can now run gulp.

This gulp build uses babel to transpile the ES6 code into standard javascript and browserfys it into bundle.js in app.

You can open index.html in a browser to execute the application. It should look something like this:

Screenshot - 09162015 - 06:20:49 PM


I know that this project is very artificial. I only want you to take away the principles. You ultimately have to make decisions for you applications. Architecting your projects like this may or may not make sense for you.