Introduction

When we last left, we properly modified list-controller to support event notification upon change to its collection as well as created a storage-service communication layer with localStorage. That gave us some great passing tests, but nothing to show off as the service was not integrated into the Grocery List application. In this article, we’ll do just that, but…

Before we hook up list-controller events to storage-service operations…

We need a way to supply the list-controller with the stored items. The list-controller has a createNewItem() method, but no methods to provide a previously created item. Since we are not burdening the list-controller in communicating with the storage-service directly, we’ll need to open up the API to allow items to be added – at least at the onset.

Tests

First we’ll include all our tests in our specrunner again as changes to list-controller may impact tests across multiple specs. And while we are poking around, let’s add a spec suite for setItems() on the list-controller and watch it fail:

/test/jasmine/spec/list-controller.spec.js

describe('setItems()', function() {

  var itemOne = modelFactory.create(),
      itemTwo = modelFactory.create();

  beforeEach( function() {
    itemOne.name = 'apples';
    itemTwo.name = 'oranges';
    listController.setItems([itemOne, itemTwo]);
  });

  afterEach( function() {
    listController.getItemList().removeAll();
  });

  it('should fill list with provided items', function() {
    var items = listController.getItemList();
    expect(items.itemLength()).toEqual(2);
    expect(items.getItemAt(0)).toBe(itemOne);
    expect(items.getItemAt(1)).toBe(itemTwo);
  });

});

This simple first spec tells us that an array of items can be provided to the list-controller using setItems() and should be accessible by its collection. And we fail with no surprises:

list-controller modification

Throughout this series I have employed a quasi-“TDD as if you mean it” approach when creating new components and modifying the API on existing ones. With this modification to the list-controller, I am going to stick to getting the tests to pass by modifying the list-controller directly as I feel it is going to get a little more involved and will require some refactoring that would be better suited by focusing on true implementation.

With that said, let’s modify list-controller to get that new spec passing:

/script/controller/list-controller.js

listController = {
  $view: undefined,
  getItemList: function() {
    return collection;
  },
  getRendererFromItem: function(item) {
    var i = rendererList.itemLength(),
        renderer;
    while( --i > -1 ) {
      renderer = rendererList.getItemAt(i);
      if(renderer.model === item) {
        return renderer;
      }
    }
    return undefined;
  },
  createNewItem: function() {
    var model = modelFactory.create();
    collection.addItem(model);
    return model;
  },
  removeItem: function(item) {
    return collection.removeItem(item);
  },
  setView: function(view) {
    this.$view = (view instanceof $) ? view : $(view);
  },
  setItems: function(items) {
    collection = collectionFactory.create(items);
  }
};

Well, that was easy enough!

Tests

Not so fast… I think our single spec may be deceiving our expectations. Let’s add a few more and make sure we are on the right path. To start, we expect changes to these new models to propagate events when it is modified – such as in the work we have done previously.

/test/jasmine/spec/list-controller.spec.js

async.it('should dispatch events of property-change from provided items', function(done) {
  var items = listController.getItemList(),
      itemOne = items.getItemAt(0);
  $(listController).on('save-item', function(event) {
    $(listController).off('save-item');
    expect(event.item).toBe(itemOne);
    done();
  });
  itemOne.marked = true;
});

This spec tells us that changes to an item should be notified through the list-controller – basically the work we had done previously in getting the list-controller to dispatch events related to its underlying collection so as to be captured by observing parties.

This test actually reveals some refactoring that is required within the list-controller. In essence, creating a new collection from the provided items in setItems() is not enough to have the application work as expected – each individual item needs to be managed by a list-item-controller which responds and notifies of changes accordingly. We had previously paired an item with a item controller within the collection-change event handler of the collection in list-controller:

/script/controller/list-controller.js

(function assignCollectionHandlers($collection) {

  var EventKindEnum = collectionFactory.collectionEventKind,
      isValidValue = function(value) {
        return value && (value.hasOwnProperty('length') && value.length > 0);
      };

  $collection.on('collection-change', function(event) {
    var model,
        itemController,
        $itemController,
        $itemView;
    switch( event.kind ) {
      case EventKindEnum.ADD:
        $itemView = $('<li>');
        model = event.items.shift();
        itemController = itemControllerFactory.create($itemView, model);
        $itemController = $(itemController);

        $itemView.appendTo(listController.$view);
        rendererList.addItem(itemController);
        $(listController).trigger(createSaveEvent(model));
        itemController.state = itemControllerFactory.state.EDITABLE;

        $itemController.on('remove', function(event) {
          listController.removeItem(model);
        });
        $itemController.on('commit', function(event) {
          if(!isValidValue(model.name)) {
            listController.removeItem(model);
          }
          else {
            $(listController).trigger(createSaveEvent(model));
          }
        });
        break;
      case EventKindEnum.REMOVE:
        model = event.items.shift();
        itemController = listController.getRendererFromItem(model),
        $itemController = $(itemController);

        if(itemController) {
          $itemView = itemController.parentView;
          $itemView.remove();
          itemController.dispose();
          $itemController.off('remove');
          $itemController.off('commit');
          rendererList.removeItem(itemController);
          $(listController).trigger(createRemoveEvent(model));
        }
        break;
      case EventKindEnum.RESET:
        break;
    }
  });

}($(collection)));

That IIFE was run in the module prior to returning the list-controller instance. Now, we could just copy that code from the EventKindEnum.ADD case and shove it into setItems(), applying it to each item in a loop, but that wouldn’t be very efficient, not to mention a cry-inducing solution for anyone (including yourself) which need to revisit your code.

list-controller refactor

I think we are going to have to get rid of this IIFE, but let’s do that modification in piecemeal; first, let’s strip out the item management when added to a collection:

/script/controller/list-controller.js

var collection = collectionFactory.create(),
    rendererList = collectionFactory.create(),
    manageItemInList = function(item, listController) {
      var $itemView = $('<li>'),
          itemController = itemControllerFactory.create($itemView, item),
          $itemController = $(itemController),
          isValidValue = function(value) {
            return value && (value.hasOwnProperty('length') && value.length > 0);
          };

      $itemView.appendTo(listController.$view);
      rendererList.addItem(itemController);

      $itemController.on('remove', function(event) {
        listController.removeItem(item);
      });
      $itemController.on('commit', function(event) {
        if(!isValidValue(item.name)) {
          listController.removeItem(item);
        }
        else {
          $(listController).trigger(createSaveEvent(item));
        }
      });
      return itemController;
    },
    listController = {
      $view: undefined,
      ...
    };

Most of what was held in the EventKindEnum.ADD case of the collection-change handler has been moved to its own function expression – manageItemInList(). If we look at how this case is modified we see that we have left state initialization and event dispatching:

/script/controller/list-controller.js

case EventKindEnum.ADD:
  model = event.items.shift();
  itemController = manageItemInList(model, listController);
  itemController.state = itemControllerFactory.state.EDITABLE;
  $(listController).trigger(createSaveEvent(model));
  break;

When an item is added to the collection and the list-controller is notified, it creates a new list-item-controller using manageItemInList(), sets the controller’s state to EDITABLE and notifies of its addition. The last two operations are of note, as they only pertain to new additions to the collection – we don’t want such things for existing items being added to the list from setItems().

/script/controller/list-controller.js

setItems: function(items) {
  var i, length = items.length;
  collection = collectionFactory.create();
  for( i = 0; i < length; i++ ) {
    manageItemInList(items[i], this);
    collection.addItem(items[i]);
  }
}

Now if we run the tests again:

Passing!

Tests

I don’t think we are out of the woods yet, however… Let’s continue to add more expectations about setting the collection through setItems() on list-controller:

/test/jasmine/spec/list-controller.spec.js

async.it('should dispatch event of remove-item from collection', function(done) {
  $(listController).on('remove-item', function(event) {
    $(listController).off('remove-item');
    expect(event.item).toBe(itemOne);
    done();
  });
  listController.removeItem(itemOne);
});

This test ensures that the list-controller should still be responding to and notifying of changes to the new collection created through setItems() just as it should if the list-controller was only being instructed to modify the collection through calls to createNewItem().

list-controller refactoring

To save you some time in downloading more images, believe me when I tell you I just put us back in red The reason being that dang assignCollectionHandlers IIFE. The collection that is created in setItems() is not being observed. The IIFE to assign events handlers is only run upon load of the module and only targets the collection instantiated in its declaration. In other words, any new collections will not be observed.

I say we move that IIFE out into its own expression:

/script/controller/list-controller.js

var collection = collectionFactory.create(),
    rendererList = collectionFactory.create(),
    assignCollectionHandlers = function($collection) {
      var EventKindEnum = collectionFactory.collectionEventKind;
      $collection.on('collection-change', function(event) {
        var model,
            itemController,
            $itemController,
            $itemView;
        switch( event.kind ) {
          case EventKindEnum.ADD:
            model = event.items.shift();
            itemController = manageItemInList(model, listController);
            itemController.state = itemControllerFactory.state.EDITABLE;
            $(listController).trigger(createSaveEvent(model));
            break;
          case EventKindEnum.REMOVE:
            model = event.items.shift();
            itemController = listController.getRendererFromItem(model),
            $itemController = $(itemController);

            if(itemController) {
              $itemView = itemController.parentView;
              $itemView.remove();
              itemController.dispose();
              $itemController.off('remove');
              $itemController.off('commit');
              rendererList.removeItem(itemController);
              $(listController).trigger(createRemoveEvent(model));
            }
            break;
          case EventKindEnum.RESET:
            break;
        }
      });
    },
    manageItemInList = function(item, listController) {
      // implementation removed to reduce noise
    },
    listController = {
      // implementation removed to reduce noise
    }

We basically took what was the named assignCollectionHandlers IIFE and added it to the variable declarations within the list-controller module. That changes the code between those declarations and the return of the listController instance to:

/script/controller/list-controller.js

var collection = collectionFactory.create(),
    rendererList = collectionFactory.create(),
    assignCollectionHandlers = function($collection) {
      // implementation removed to reduce noise
    },
    manageItemInList = function(item, listController) {
      // implementation removed to reduce noise
    },
    listController = {
      // implementation removed to reduce noise
    };

assignCollectionHandlers($(collection));

return listController;

With those changes we are still failing on the last spec we created, but more importantly we have not caused any other tests to fail!

Let’s get that last spec to pass:

/script/controller/list-controller.js

setItems: function(items) {
  var i, length = items.length;
  collection = collectionFactory.create();
  for( i = 0; i < length; i++ ) {
    manageItemInList(items[i], this);
    collection.addItem(items[i]);
  }
  assignCollectionHandlers($(collection));
}

Hurrah!

Tagged 0.1.13: https://github.com/bustardcelly/grocery-ls/tree/0.1.13

Hooking it all together

We have created our storage-service to communicate with localStorage, modified list-controller to dispatch events and accept initial items for its collection and all our tests are still passing! It’s a wonderous feeling. Now let’s get to actually hooking them up so that the storage-service is told how to handle changes to the list by responding to list-controller events.

Normally, in such situations I would create another component to the application that would serve as an mediator for such integration, receiving events from list-controller and invoking the storage-service. Naturally, that would also call for more tests in assuring that the mediator did its job correctly. I am not going to do that here. This is a small application meant for our own personal use and this series has gotten quite long; I don’t want to scare you away by adding more dependencies, but I would encourage you to do so on your own if you feel so…. just don’t forget the tests!

I think modifying the main JavaScript file (/script/grocery-ls.js) that defines the module dependencies and initializes the Grocery List application is fine enough for the task at hand:

/script/grocery-ls.js

(function(window, require) {

  require.config({
    baseUrl: ".",
    paths: {
      "lib": "./lib",
      "script": "./script",
      "jquery": "./lib/jquery-1.8.3.min"
    }
  });

  require( ['jquery', 'script/controller/list-controller', 'script/service/storage-service'],
            function($, listController, storageService) {

    var $listController = $(listController);
    listController.setView($('section.groceries ul'));

    storageService.getItems().then(function(items) {
      listController.setItems(items);
    });
    $listController.on('save-item', function(event) {
      storageService.saveItem(event.item).then(function(item) {
        console.log('Item saved! ' + item.name);
      }, function(error) {
        console.log('Item not saved: ' + error)
      });
    });
    $listController.on('remove-item', function(event) {
      storageService.removeItem(event.item).then(function(item) {
        console.log('Item removed! ' + item.name);
      }, function(error) {
        console.log('Item not removed: ' + error);
      });
    });
    $('#add-item-button').on('click', function(event) {
      listController.createNewItem();
    });

  });

}(window, requirejs));

Just a slight modification to the main file. We added storage-service as an initial dependency, request and supply stored items to the list-controller and respond to save-item and remove-item events, forwarding actions along to the storage-service appropriately.

If we run the application now, we can add, mark-off, remove items from the list. Same as before, but now, if we refresh the page, items and their state a persisted!

It may look a little different than your if you have been following along in the code. I added some nice styling and committed it to the repo.

Tagged 0.2.0 : https://github.com/bustardcelly/grocery-ls/tree/0.2.0

Conclusion

We have completed our Grocery List application and have it fully tested (well, hopefully ). We now have a grocery list that we can curate and is persisted in the browser. It should be noted that it is not persistent across browsers, plural – so make sure to open it in the same browser on your mobile device when creating the list and shopping. I am most likely going to whip up a little server to persist the list remotely, but am not going to document that in this series. It may end up in the github repo eventually, however, so keep an eye out.

Thanks for sticking around in this long series (ten parts!) of building an application by trying to adhere to TDD. I may have gone off course here and there, but I hope it was informative in any way.

Cheers!

—-

Link Dump

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
TDD as if you Meant it by Keith Braithwaite
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

Introduction

In the previous article, we pretty much wrapped up all the user-based functionality and ended with a working Grocery List application that we could start using. There is one little snag though… no persistance. If you made this gloriously elaborate list that detailed everything you needed at the store, then closed the browser and reopened it, the list was gone! That will not do.

There are many factors and paradigms to consider in choosing the level of persistence when it comes to handling session and user based applications. Without introducing a discussion about authentication, when approaching the integration persistence you have to take into account system-based vs user-based persistence, client-side vs server-side storage, and – nowadays, more commonly – the cross pollination of the two: occasional-connectivity. (not to mention browser support in all this) We won’t be getting into all of that We’ll be using the localStorage of today’s modern browser.

The intent of this article in the series is to implement client-side, browser-based persistence for the Grocery List application. It would be nice to store our list remotely so it can be accessed by all browsers on all devices, but I feel it would introduce too many new libraries, software and concepts to this series. I will most likely add it personally after this series is over, and I invite you to as well – keeping in mind to do it using TDD The most I can offer at this point, is to keep the code we will write clean enough to support such future endeavours.

What Tests to Modify to Get Us There?

Good question. Let’s first think about what actions will prompt an update to the list in storage. Actually, if we look at the feature specs we have created throughout this series and separated out into the /feature directory itself, we pretty much have all the defined actions that will trigger an update to the stored list:

All of these features are a result from interacting with the list-controller. My first inkling is to add responsibility to the list-controller so that, along with the other operations it handles in list management, it communicates with a service layer to update the Grocery List in storage. However, I think that would add too much burden on the list-controller and, when taking into account that requirements around storage may change, the introduction of such complexity into the list-controller may quickly make our tests feel chaotic.

As such, I propose that we should start off with the expectation that the list-controller will notify of its underlying collection having been modified, not only upon its change in length, but of the items within the collection, as well. We can then capture those events and forward them on to whichever service implementation we have without having to pass that dependency into the list-controller and burdening it with such communication.

New Expectation for Add Item

To start, let’s add a quick spec to the Add Item feature that defines an expectation from the list-controller to notify when an item has been added:

/test/jasmine/spec/feature/additem.spec.js

async.it('should dispatch a save-item event', function(done) {
  var newItem;

  $(listController).on('save-item', function(event) {
    expect(event.item).not.toBeUndefined();
    $(listController).off('save-item');
    done();
  });
  newItem = listController.createNewItem();
});

In creating this expectation, we have also begun to define the actual make-up of the event we intend to receive: the event type being save-item and the access of the item that was saved.

Run it and we are red, as expected:

Taking what we have defined as our expectation when an item is added, we’ll modify the list-controller to get this passing. First we’ll add a factory method to generate save-item events:

/script/controller/list-controller.js

function createSaveEvent(item) {
  var event = $.Event('save-item');
  event.item = item;
  return event;
}

Fairly straight-forward and similar to other event factory methods declared previously in this series. Since we are addressing an expectation of event notification on add of item, we know where in the list-controller we can add that dispatch – in response to the addition of an item on the collection:

/script/controller/list-controller.js

$itemView.appendTo(listController.$view);
rendererList.addItem(itemController);
$(listController).trigger(createSaveEvent(model));
itemController.state = itemControllerFactory.state.EDITABLE;

Back in business.

New Expectation for Remove Item

Let’s quickly just do a similar modification to the list-controller with regards to the Remove Item feature. First we’ll append a spec in the removeitem.spec suite with an expectation of being notified on remove-item:

/test/jasmine/spec/feature/removeitem.spec.js

async.it('should dispatch a remove-item event', function(done) {
  var removedItem;

  $(listController).on('remove-item', function(event) {
    expect(event.item).not.toBeUndefined();
    $(listController).off('remove-item');
    done();
  });
  removedItem = listController.removeItem(groceryItem);
});

Sparing you another image of the specrunner turning red, that will fail with the timeout that we saw before. We’ll fix that up by adding a trigger in the removal of an item from the collection handler in list-controller. First with the addition of a factory method for the remove-item event:

/script/controller/list-controller.js

function createRemoveEvent(item) {
  var event = $.Event('remove-item');
  event.item = item;
  return event;
}

And then with an additional line to the remove response on the collection:

/script/controller/list-controller.js

case EventKindEnum.REMOVE:
  model = event.items.shift();
  itemController = listController.getRendererFromItem(model),
  $itemController = $(itemController);

  if(itemController) {
    $itemView = itemController.parentView;
    $itemView.remove();
    itemController.dispose();
    $itemController.off('remove');
    $itemController.off('commit');
    rendererList.removeItem(itemController);
    $(listController).trigger(createRemoveEvent(model));
  }
break;

Run the tests, and we are back to passing:

New Expectation for Save Item

Sort of repetitive, but we are on a roll… let’s go through the similar process to ensure that a notification for save-item is dispatched when the user has modified its name and committed it to the list – the Save Item feature we added in the last article.

/test/jasmine/spec/feature/saveitem.spec.js

async.it('should dispatch a save-item event', function(done) {

  $(listController).on('save-item', function(event) {
    expect(event.item).toEqual(item);
    $(listController).off('save-item');
    done();
  });

  item.name = itemName;
  itemRenderer.state = itemControllerFactory.state.UNEDITABLE;
});

That’ll put us in the red with the same old timeout issue. Getting back to green, we’ll trigger the save-item event upon committal of the item to the list, which if you remember – and is described in the test – is in response to the list-item-controller notifying of change to the item model:

/test/jasmine/spec/feature/list-controller.js

$itemController.on('commit', function(event) {
  if(!isValidValue(model.name)) {
    listController.removeItem(model);
  }
  else {
    $(listController).trigger(createSaveEvent(model));
  }
});

Back to green!

The amount of those little dots just keeps growing. Makes you feel all warm inside. Cherish that, ’cause it will go away…

Hold Up

Just stepping back, it may seem a little odd that we are calling save-item when we add and commit the item to the list; after all they are the same item, we do we need to notify on save multiple times? The reason being is that upon any modification to an item – including its existence – the store needs to be modified. We haven’t gotten into the service layer for storage yet, but it will be abstracted out that a response from save-item will be internally handled as whether to append the item (from add) or to update an item already existant (from commit). Until we get to that service layer implementation for localStorage, we’ll go about setting expectations of save-item notification on modification to an item.

Which actually brings up a good point… what about marking off an item? We will need to notify on change of an item being marked off, as well.

New Expectation for Mark-Off Item

We tackled the Mark-Off Item feature a while back in this series. Just a quick refresher on the story:

// story
—
Story: Item is marked off on grocery list

In order to remember what items have already made it to the cart
As a grocery shopper
I want to mark an item as being attained on the grocery list.
—

We implemented the feature, and upon user press of the item while in non-edit mode, it toggles its marked property on the model and updates the UI to add or remove a strikethrough on the label.

We’ve got a spec suite for the Mark-Off Item feature already, so we’ll append an expectation for save-item to it just as we have done with the other feature specs in this article:

/test/jasmine/spec/feature/markitem.spec.js

async.it('should dispatch a save-item event', function(done) {

   var timeout = setTimeout(function() {
     clearTimeout(timeout);
     $(listController).off('save-item');
   }, jasmine.DEFAULT_TIMEOUT_INTERNAL);

  $(listController).on('save-item', function(event) {
    expect(event.item).toBe(item);
    $(listController).off('save-item');
    done();
  });

  item.marked = true;
});

… and that will bring us back to failing.
The timeout placed in there is just to ensure that listener(s) to the save-item event are removed regardless of the async test timing out.

The resolution to the issue is a trickier one than those of the previous in this article, however. Currently the list-item-controller is the only component that actually concerned with this change in marked status. It is not concerned with notifying any other party of the change to its model. The model does, however, notify of any property changes. I see two ways in which we can get back to passing:

1. Assign a handler for property-change on model when it is first created and returned from listController.createNewItem()
2. Dispatch a commit event from list-item-controller on change to marked property on the underlying model

While both options will most likely get us where we need to be, the former adds additional management to the list-controller; its already listening in on commit from its list-item-controller instance, so modifying the list-item-controller to notify of change to the marked property seems to be the path of least resistance.

We had previously set up the commit notification on response from leaving the EDITABLE state of the list-item-controller:

/script/controller/list-item-controller.js

// append state-based item.
if(event.newState === stateEnum.UNEDITABLE) {
  controller.parentView.append(controller.$uneditableView);
  controller.save();
}

That implementation got us to passing previously in which we described the expectation of a user committing an item to the list with a valid name (un-empty string). Our issue at hand is to also invoke the save() method on list-item-controller when the marked property is modified. In thinking about it now, while the committal of an item is tied to the change of state, it runs a validation on the name property to ensure that the item can be added/kept in the collection – so, in actuality commit can be tied to property updates to the item model.

As such, let’s remove line 48 from the above snippet and insert the invocation of save() to the handler in list-item-controller for property-change on the model:

/script/controller/list-item-controller.js

$(this.model).on('property-change', (function(controller) {
  return function(event) {
    handlePropertyChange.call(null, controller, event);
    controller.save();
  };
}(this)));

Run the specrunner again…

… and we broke it

The reason for those X’s is due to the logic we have held in list-controller on save of an item: it checks it’s name property and removes it from the list if considered an invalid value – which an empty string is.

I sense some modification to such logic in the future, but for now we can get the tests back to passing by providing a name property value to the created item in our mark-item spec:

/tests/jasmine/spec/feature/markitem.spec.js

beforeEach( function() {
  item = listController.createNewItem();
  item.name = 'apples';
});

We’re green!

Tagged 0.1.13: https://github.com/bustardcelly/grocery-ls/tree/0.1.13

Settle Down

We have verified our expectations of save-item and remove-item events being dispatched from list-controller – new and model updates issuing the former, removal issuing the later. The work we have done was to separate concerns and not burden the list-controller itself with service communication for persisting the Grocery List items across browser sessions, but we have yet to address the actual service layer implementation that will take all these notifications.

Storage Service

The storage-service will provide a service layer for communication with storage – whether that be remote or local. It will serve as a facade to an existing storage of grocery list items persisted somewhere other than the current application session. For the purposes of this article, that persistence layer is going to be the localStorage of the browser.

While fleshing out the storage service and its API, we’ll loosely use the technique of ‘TDD as if you meant it’. I say loosely in part because to fully do it and explain each step would be a lot of noise for this article; the main practice point to take away – and I hope I express – is that the component you are testing is actually being built while you make the expectations for it pass.

Tests

To start, we’ll create a bare-bones module for our service layer:

/script/service/storage-service

define(['jquery'], function($) {

  var store = {};
  return store;

});

And let’s create the beginnings of our test:

/test/jasmine/spec/storage-service.spec.js

define(['jquery', 'script/service/storage-service', 'script/model/grocery-ls-item'],
        function($, store, modelFactory) {

  describe('Grocery List storage-service', function() {

    describe('getItems()', function() {

      it('should return of type array', function() {
        expect(false).toEqual(true);
      });

      it('should return array of grocery-ls-item types', function() {
        expect(false).toEqual(true);
      });

    });

  });

});

In the test we have set up some tests for the getItems() method for the service. Prior to any implementation, it should be known that communication with the storage-service will be considered asynchronous – meaning all operations will return a jQuery Deferred. This will abstract out the storage proxy that will be employed by the storage-service and will respond in an asynchronous manner regardless of whether the store is immediately accessible – as in the case of localStorage – or remote.

Truthfully, in practice, I should only do one tests at a time, but we are testing the expectations for access of the same item listing; to save you from reading the ramblings of adding another test, I declared them both at the start.

Let’s stub out the API and start testing and building the storage-service:

/test/jasmine/spec/storage-service.spec.js

describe('getItems()', function() {

  var items,
      itemOne = modelFactory.create(),
      itemTwo = modelFactory.create(),
      async = new AsyncSpec(this);

  async.beforeEach( function(done) {
    var deferred = $.Deferred(),
        getStub = sinon.stub().returns(deferred);

    deferred.resolve([itemOne, itemTwo]);
    store.getItems = getStub;

    store.getItems().then(function(list) {
      items = list;
      done();
    });
  });

  afterEach( function() {
    //
  });

  it('should return of type array', function() {
    expect(Array.isArray(items)).toEqual(true);
    expect(items.length).toEqual(2);
  });

  it('should return array of grocery-ls-item types', function() {
    expect(items[0]).toBe(itemOne);
    expect(items[1]).toBe(itemTwo);
  });

});

In the beforeEach(), we’re using anonymous stubs from SinonJS, which allow us to stub out methods that may not necessarily already exist on an object. I have used it previously in this series, but we’ll be using it pretty much exclusively while we stub out the API for the storage-service.

Staying true to our idea that the service will provide an asynchronous communication layer, getItems() returns a deferred which has resolved to a listing of two grocery-ls-item instances in our tests.

Sometimes when working with a single feature, I like to isolate it out from my tests for a bit. Here is what the specrunner reports with running just storage-service.spec:

We could move that implementation to storage-service module now, but we are sort of in a chicken-or-the-egg scenario. We’ve canned the resolved grocery-ls-item list in the test, but how does the list get filled up in an actual scenario for storage-service? It’s an excellent question, and something I often puzzle myself with. I mean, we’ll need a saveItem() method no doubt in order to add items to the store. But shouldn’t that method now be stubbed out in a new test? And how do I test that saveItem() works without getItems() being already tested and verified? I could go in circles…

Let’s just stub out an saveItem() method on storage-service and, afterward, set expectations in another spec suite:

/test/jasmine/spec/storage-service.spec.js

async.beforeEach( function(done) {
  var call = 0,
      tempList = [],
      deferred = $.Deferred(),
      getStub = sinon.stub().returns(deferred),
      saveStub = sinon.stub().callsArgOn(0, store),
      appendItem = function() {
        tempList.push((call++%2 === 0) ? itemOne : itemTwo);
      };

  store.saveItem = saveStub;
  store.getItems = getStub;

  store.saveItem(appendItem);
  store.saveItem(appendItem);
  store.getItems().then(function(list) {
    items = list;
    done();
  });
  deferred.resolve(tempList);
});

With these modifications, we have assigned an anonymous stub – saveStub – as the saveItem method on the store and specified that the function-local appendItem method should be invoked, appending items to the list prior to each of our tests.

A little more work in setup and slightly unrealistic in telling of the arguments to be given to saveItem(), but it kept us on green without having to hard code the result; it’s a litte truer to life than the previous setup, and still passes:

Implementation

Alright, so I think we should move this out to storage-service now and trash the stubbing in the test – we’ve got our expectations:

/script/service/storage-service.js

define(['jquery'], function($) {

  var itemCache = [],
      store = {
        saveItem: function(item) {
          var deferred = $.Deferred();
          itemCache[itemCache.length] = item;
          return deferred.resolve(item);
        },
        getItems: function() {
          var deferred = $.Deferred();
          deferred.resolve(itemCache);
          return deferred;
        }
      };

  return store;

});

/test/jasmine/spec/storage-service.spec.js

describe('getItems()', function() {

  var items,
      itemOne = modelFactory.create(),
      itemTwo = modelFactory.create(),
      async = new AsyncSpec(this);

  async.beforeEach( function(done) {
    store.saveItem(itemOne);
    store.saveItem(itemTwo);
    store.getItems().then(function(value) {
      items = value;
      done();
    });
  });

  afterEach( function() {
    //
  });

  it('should return of type array', function() {
    expect(Array.isArray(items)).toEqual(true);
    expect(items.length).toEqual(2);
  });

  it('should return array of grocery-ls-item types', function() {
    expect(items[0]).toBe(itemOne);
    expect(items[1]).toBe(itemTwo);
  });

});

Run that, and we are still green!

Tests

Now that we can verify that saveItem() is working enough for our getItem spec, let’s properly set the expectations for saveItem, as well, in our tests:

/test/jasmine/spec/storage-service.spec.js

describe('saveItem()', function() {

  var itemOne = modelFactory.create(),
      itemTwo = modelFactory.create(),
      async = new AsyncSpec(this);

  beforeEach( function() {
    store.saveItem(itemOne);
  });

  afterEach( function() {
    //
  });

  async.it('should be grow the length of items', function(done) {
    store.getItems().then( function(items) {
      expect(items.length).toEqual(1);
      done();
    });
  });

});

Simple enough. Back to the specrunner:

Oh noes! Our expectation is that the length of items is only 1. We have only specified one addition of an item in the setup… where did the length of 5 come from!? Put down the abacus – there are better things to throw. But before that, I have an explanation: we haven’t been cleaning up. We have let afterEach() just quietly be invoked without a job to do.

To do just enough in getting our tests pass, we can update the afterEach() declarations in each spec suite to the following:

async.afterEach( function(done) {
  store.getItems().then(function(items) {
    items.length = 0;
    done();
  });
});

That will get us back to passing:

I am not particularly fond of that solution, however. Mainly because I think it conveys a usage of the API on storage-service that I would not condone: directly mutating the underlying list of storage-service from another party.

I’m not gonna get crazy with the lock-down and privacy of properties and start introducing the latest-and-greatest framework that tries to tout that they really are just a library all in the attempt to stop someone from directly accessing the underlying array of items on storage-service. If some developers gonna go crazy and do so, hopefully we can find it in more tests later or they can look at our tests as a guideline of how to do what they want.

As such, I think we should add a method to storage-service that simply allows for emptying the list. First the expectation:

/test/jasmine/spec/storage-service.spec.js

describe('empty()', function() {

  var itemOne = modelFactory.create(),
      itemTwo = modelFactory.create(),
      async = new AsyncSpec(this);

  beforeEach( function() {
    store.saveItem(itemOne);
    store.saveItem(itemTwo);
  });

  afterEach( function() {
    store.empty();
  });

  async.it('should be appended to the list of items', function(done) {
    store.empty().then( function(items) {
      expect(items.length).toEqual(0);
      done();
    });
  });

});

/script/service/storage-service.js

define(['jquery'], function($) {

  var itemCache = [],
      store = {
        saveItem: function(item) {
          var deferred = $.Deferred();
          itemCache[itemCache.length] = item;
          return deferred.resolve(item);
        },
        getItems: function() {
          var deferred = $.Deferred();
          deferred.resolve(itemCache);
          return deferred;
        },
        empty: function() {
          var deferred = $.Deferred();
          itemCache.length = 0;
          deferred.resolve(itemCache);
          return deferred;
        }
      };

  return store;
});

Alright! We are passing expectations on three parts of the API for storage-service. Now let’s think of what else we need… I think only a removeItem() method will suffice. In working as we have previously in this article – stubbing out methods to be added to the storage-service implementation – we can add a spec suite for removeItem() such as the following:

/test/jasmine/spec/storage-service.spec.js

describe('removeItem()', function() {

  var items,
      itemOne = modelFactory.create(),
      itemTwo = modelFactory.create(),
      async = new AsyncSpec(this),
      deferred = $.Deferred(),
      removeItemFromList = function() {
        deferred.resolve(items.splice(0, 1));
      };

  async.beforeEach( function(done) {
    var removeItemStub = sinon.stub().returns(deferred).callsArgOn(0, store);

    store.saveItem(itemOne);
    store.saveItem(itemTwo);
    store.removeItem = removeItemStub;
    store.getItems().then( function(value) {
      items = value;
      done();
    });
  });

  afterEach( function() {
    store.empty();
  });

  async.it('should shorten length of the list', function(done) {
    store.removeItem(removeItemFromList).then( function(item) {
      store.getItems().then( function(items) {
        expect(items.length).toEqual(1);
        done();
      });
    });
  });

});

I think there are more expectations to assert for the removeItem() spec suite, but for now we are passing and we’ll move the implementation over to storage-service:

/script/service/storage-service.js

define(['jquery'], function($) {

  var itemCache = [],
      store = {
        saveItem: function(item) {
          var deferred = $.Deferred();
          itemCache[itemCache.length] = item;
          return deferred.resolve(item);
        },
        removeItem: function(item) {
          var deferred = $.Deferred(),
              itemIndex = itemCache.indexOf(item),
              removedItem;

          if(itemIndex > -1) {
            itemCache.splice(itemIndex, 1);
            removedItem = item;
          }
          return deferred.resolve(removedItem);
        },
        getItems: function() {
          var deferred = $.Deferred();
          deferred.resolve(itemCache);
          return deferred;
        },
        empty: function() {
          var deferred = $.Deferred();
          itemCache.length = 0;
          deferred.resolve(itemCache);
          return deferred;
        }
      };

  return store;

});

Now, we’ll update the spec suite for removeItem() and add a few more expectations to ensure the item removal process is correct:

/test/jasmine/spec/storage-service.spec.js

describe('removeItem()', function() {

  var itemOne = modelFactory.create(),
      itemTwo = modelFactory.create(),
      async = new AsyncSpec(this);

  beforeEach( function() {
    itemOne.name = 'one';
    store.saveItem(itemOne);
    store.saveItem(itemTwo);
  });

  afterEach( function() {
    store.empty();
  });

  async.it('should shorten length of the list', function(done) {
    store.removeItem(itemOne).then( function(item) {
      store.getItems().then( function(items) {
        expect(items.length).toEqual(1);
        done();
      });
    });
  });

  async.it('should remove item specified from the list', function(done) {
    store.removeItem(itemOne).then( function(item) {
      store.getItems().then( function(items) {
        expect(items.indexOf(itemOne)).toEqual(-1);
        done();
      });
    });
  });

  async.it('should return the item removed if found', function(done) {
    store.removeItem(itemOne).then( function(item) {
      expect(item).toEqual(itemOne);
      done();
    });
  });

  async.it('should return undefined if item not found', function(done) {
    store.removeItem(modelFactory.create()).then( function(item) {
      expect(item).toBeUndefined();
      done();
    });
  });

});

… and we’re still in business!

Revisiting saveItem()

When we setup the saveItem stub for our getItem() spec suite, we really only focused on getting the expectations to pass. To get back to green – at the time – we were only concerned with appending items to the list. I think this needs to be looked at again.

If we remember back to the notifications we set up for the list-controller, it will dispatch a save-item event upon the existence of a new item, as well as the modification to an existing item. So we will pass that item through the storage-service using saveItem() but we don’t want to continually append items that are previously stored to the list – if so, we’d be buying a lot of spinich spinnash spinach.

Normally I wouldn’t cut corners: a feature spec should be written up for what I have described here prior to modifying the tests. To save you some scrolling, however, I decided to not include walking through one and letting the expectations that we define in the following speak for the specification.

/test/jasmine/spec/storage-service.spec.js

describe('saveItem()', function() {

  var itemOne = modelFactory.create(),
      itemTwo = modelFactory.create(),
      async = new AsyncSpec(this);

  beforeEach( function() {
    store.saveItem(itemOne);
  });

  afterEach( function() {
    store.empty();
  });

  async.it('should grow the length of items on new item', function(done) {
    store.getItems().then( function(items) {
      expect(items.length).toEqual(1);
      done();
    });
  });

  async.it('should not grow the length of items on pre-existing item', function(done) {
    itemOne.name = 'oranges';
    store.saveItem(itemOne).then( function(item) {
      store.getItems().then( function(items) {
        expect(items.length).toEqual(1);
        done();
      });
    });
  });

});

We modified the description of the original expectation to state that the items list should only grow on new existence and added a new expectation that previously stored items do not get appended to the stored list:

As expected Let’s update saveItem() on the storage-service to account for this:

/script/service/storage-service.js

saveItem: function(item) {
  var deferred = $.Deferred(),
      index = itemCache.indexOf(item);
  if(index === -1) {
    itemCache[itemCache.length] = item;
  }
  return deferred.resolve(item);
}

Not leaving any to chance, let’s add a couple more expectations as to how items are placed and how they remain in their places:

/test/jasmine/spec/storage-service.spec.js

describe('saveItem() multiples', function() {

  var itemOne = modelFactory.create(),
      itemTwo = modelFactory.create(),
      async = new AsyncSpec(this);

  beforeEach( function() {
    store.saveItem(itemOne);
    store.saveItem(itemTwo);
  });

  afterEach( function() {
    store.empty();
  });

  async.it('should append new items to the end of the list', function(done) {
    store.getItems().then( function(items) {
      expect(items[items.length-1]).toBe(itemTwo);
      done();
    });
  });

  async.it('should update existing item at position', function(done) {
    itemOne.name = 'oranges';
    store.saveItem(itemOne).then( function(item) {
      store.getItems().then( function(items) {
        expect(items.indexOf(itemOne)).toEqual(0);
        done();
      });
    });
  });

});

I had begun to add these expectations for multiple items in the list to the saveItem() spec suite, but I saw a similar setup for them both that differed from the origin setup for the saveItem() suite. As such, I moved these expectations to their own spec suite and particular setup.

Without any new modification to storage-service implementation, run that and we are still green!

Tagged 0.1.14: https://github.com/bustardcelly/grocery-ls/tree/0.1.14

This Is All Great But We Still Haven’t Done Anything

In other words, what this subsection header is trying to say, the storage-service – even after we hook up communication to it from list-controller events – will do nothing but keep a session-cache of items: there still is no persistence across sessions.

Seeing as this is the case, let’s start integrating communication with localStorage into our storage-service. I am not going to modify the tests in order to verify the utilization of localStorage in relation to the operations available on storage-service – I am simply going to modify the storage-service and posible change expectations. The reason being that I do not really care about whether the storage-service relies on localStorage or a remote resource to read and write items to storage; I am only concerned with communication to storage-service being supported.

In truth, if this were a real world application and had to support occasional connectivity, i’d have two service modules: local-storage-service and remove-storage-service. They would both support the same API and there would be a service layer facade that would manage the ‘live’ instance and sync of both. That is a little too much for this series, so we’ll stick with a proxy to localStorage without modifying our tests to assume that the storage-service requires communication with it.

storage-service modification

To begin with, a String value is used as a key to read and write to an object held on localStorage. The API of localStorage is fairly simple and we’ll only be concerned with getItem() and setItem() to read and write to the store, respectively. We’ll use a key that we hope is unique to our application and won’t overwrite any object stored previously by another and use that key to access the stored grocery list items:

/script/service/storage-service.js

define(['jquery', 'script/model/grocery-ls-item'], function($, modelFactory) {

  var itemCache,
      groceryListKey = 'com.custardbelly.grocerylist',
      parseToCollection = function(json) {
        var i,
            length,
            list = (json && typeof json === 'string') ? JSON.parse(json) : [];
        length = list.length;
        for(i = 0; i < length; i++) {
          list[i] = $.extend(modelFactory.create(), list[i]);
        }
        return list;
      },
      store = {
        saveItem: function(item) {
          var deferred = $.Deferred();
          return deferred.resolve(item);
        },
        removeItem: function(item) {
          var deferred = $.Deferred(),
              itemIndex = itemCache.indexOf(item),
              removedItem;

          if(itemIndex > -1) {
            itemCache.splice(itemIndex, 1);
            removedItem = item;
          }
          return deferred.resolve(removedItem);
        },
        getItems: function() {
          var deferred = $.Deferred();
          if(itemCache === undefined) {
             try {
              itemCache = parseToCollection(window.localStorage.getItem(groceryListKey));
              deferred.resolve(itemCache);
            }
            catch(e) {
              deferred.reject('Could not access items: ' + e.message);
            }
          }
          else {
            deferred.resolve(itemCache);
          }
          return deferred;
        },
        empty: function() {
          var deferred = $.Deferred();
          itemCache.length = 0;
          deferred.resolve(itemCache);
          return deferred;
        }
      };

  return store;

});

That will light up our tests in pretty red… but that was expected. Actually, if it didn’t make our tests fail horribly, I would have been worried.

There are a couple things going on in this modification to storage-service that we should go over, however – the first being parseToCollection():

/script/service/storage-service.js

parseToCollection = function(json) {
  var i,
      length,
      list = (json && typeof json === 'string') ? JSON.parse(json) : [];

  length = list.length;
  for(i = 0; i < length; i++) {
    list[i] = $.extend(modelFactory.create(), list[i]);
  }
  return list;
}

This method is invoked from getItems() and is provided the value of the object held in localStorage with the key com.custardbelly.grocerylist. We’ll be saving our data down in JSON format, and as such, parseCollection() is responsible for parsing that data back out; as well, if it is the first time accessing the data it will be coming in as undefined so a new list is created. What is particularly important in this parsing is how the objects on the list held in localStorage are converted to instances of our grocery-ls-item model: we create a new instance using the modelFactory and extend it with the object values from the item held on the list. The reason for this is because grocery-ls-items are decorated with getters and setters to allow for property-change events to be notified. In serializing down to JSON, this object structure is not perserved – it is just a POJSO.

The parseToCollection() method is invoked from getItems():

/script/service/storage-service.js

getItems: function() {
  var deferred = $.Deferred();
  if(itemCache === undefined) {
    try {
      itemCache = parseToCollection(window.localStorage.getItem(groceryListKey));
      deferred.resolve(itemCache);
    }
    catch(e) {
      deferred.reject('Could not access items: ' + e.message);
    }
  }
  else {
    deferred.resolve(itemCache);
  }
  return deferred;
}

When getItems() is first invoked in a session, it will go about trying to access and parse the data held on localStorage; any subsequent invocations will immediately return the currently held reference to the store. In essence, during a session of creating and curating a Grocery List, we are working with live and current data so there is no need to keep accessing the list of grocery items from local storage every time – we’ll just return the live record.

Speaking of which, a lot of the failing tests I suspect are due to not actually not saving the list down to localStorage. Let’s just modify storage-service a little to do so and see where that gets us:

/script/service/storage-service.js

define(['jquery', 'script/model/grocery-ls-item'], function($, modelFactory) {

  var itemCache,
      groceryListKey = 'com.custardbelly.grocerylist',
      parseToCollection = function(json) {
        var i,
            length,
            list = (json && typeof json === 'string') ? JSON.parse(json) : [];

        length = list.length;
        for(i = 0; i < length; i++) {
          list[i] = $.extend(modelFactory.create(), list[i]);
        }
        return list;
      },
      serialize = function(key, data) {
        window.localStorage.setItem(key, JSON.stringify(data));
      },
      store = {
        saveItem: function(item) {
          var deferred = $.Deferred();
          $.when(this.getItems()).then(function(cache) {
            var index = cache.indexOf(item);
            try {
              if(index === -1) {
                cache[cache.length] = item;
              }
              serialize(groceryListKey, cache);
              deferred.resolve(item);
            }
            catch(e) {
              deferred.reject('Could not save item: ' + e.message);
            }
          });
          return deferred;
        },
        removeItem: function(item) {
          // implementation removed to reduce noise
        },
        getItems: function() {
          // implementation removed to reduce noise
        },
        empty: function() {
          // implementation removed to reduce noise
        }
      };

  return store;

});

saveItem() was modified to access the held list using getItems(), operate on that list as it had done previously and then try to serialize the list back to storage. Fairly simple. It’s important to note that we don’t access the itemCache directly in saveItem(), the reason being that we can’t ensure that saveItem() will only be called after a request to getItems(). As such, we need to be sure we’re always working with the same data and do so by requesting that cached list from getItems() within saveItem().

That gets us closer to green, but we still have some work to do…

Let’s modify removeItem() and empty() to work with the cached list returned from getItems() just as the modification to saveItems() has:

/script/service/storage-service.js

removeItem: function(item) {
  var deferred = $.Deferred();
  $.when(this.getItems()).then(function(cache) {
    var itemIndex = cache.indexOf(item),
        removedItem;
    try {
      if(itemIndex > -1) {
        cache.splice(itemIndex, 1);
        removedItem = item;
        serialize(groceryListKey, cache);
      }
      deferred.resolve(removedItem);
    }
    catch(e) {
      cache.splice(itemIndex, 0, removedItem);
      deferred.reject('Could not remove item: ' + e.message);
    }
  });
  return deferred;
}

/script/service/storage-service.js

empty: function() {
  var deferred = $.Deferred();
  $.when(this.getItems()).then(function(cache) {
    try {
      cache.length = 0;
      serialize(groceryListKey, cache);
      deferred.resolve(cache);
    }
    catch(e) {
      deferred.reject('Could not empty cache: ' + e.message);
    }
  });
  return deferred;
}

That oughta do. Basically doing the same as we had done with saveItem(): accessing the cached list through getItems(), then modifying that list and serializing back done to localStorage.

Run those tests again, and we are back to green!

… at least for our storage-service. Let’s turn on all our tests again and see if our previous expectations are met:

Whoopie!

Tagged 0.1.15: https://github.com/bustardcelly/grocery-ls/tree/0.1.15

We’re not done yet: we have still to hook up list-controller notification to storage-service operations. However, I want to end this article here on a good note

Conclusion

We have yet to reach our goal of incorporating session persistence within our Grocery List application – but that is not to say we have gotten nowhere. We implemented our storage-service layer for localStorage communication and modified the list-controller to notify of change events to its collection related to grocery-ls-item existence. Not to shabby.

I know we want to get a finished product out the door, but we’ll get there… just a few more things to tie up in the next article…

Cheers!

—-

Link Dump

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
TDD as if you Meant it by Keith Braithwaite
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

madmin is a node-based application that allows for generating immediately accessible RESTful URIs. Though it is possible to communicate with command line tools like cURL, madmin also provides a client-side console to easily create the URIs and structure of JSON response(s). It was originally intended to solve a front-end development problem in maintaining two sets of code – a fake service layer and production-level service layer – during development, but has grown to be a proven way to facilitate communication between the server-side and client-side teams in discussing the requirements of the services for a project. It also proved to be pretty handy documentation, to boot, which could be easily discussed with clients.

Anyway, you can read a more detailed description of the project and how it came to fruition over at the Infrared5 blog: http://blog.infrared5.com/2013/01/introducing-madmin-an-admin-console-for-generating-mock-services-with-restful-uris/

If you check it out, I hope you find it useful in any way and please log issues for requests or fork it to add features! I intend to get more basic instructions up on the wiki at its github location and perhaps write a few blog posts as well.

Introduction

In the past several articles we have sort of have been living in the spec runner. We fiddled about making it turn red and green, and – until the last article – we never really ran the Grocery List application we were building to give it a proper User Testing. If you did play around with the actual application we have been busy writing tests for, you may have found a bug. An unexpected result from supplying no grocery item name before saving it to the list:

As you can see from the screenshot, there is an empty item in the third entry of the list. While I do think the act of walking into a store and picking up nothing is an accomplishment at times, this Empty Item bug is not an intended feature. In this article, I want to squash that bug… but – in keep with the theme of this series – we are going to do it through tests! Calm down. It is hard to read when you jump up and down like that.

Bug Ticket

Before we begin fixing the bug, let’s get it down in writing what we think the problem is and how we think the intended behavior should be. To start, we don’t want empty items added to the Grocery List. We are currently able to add them – and rather easily – so let’s list out the steps that allows us to do so:

Empty Item Added to List
—
Steps to Reproduce

1. Launch the Grocery List application
2. Click ‘add item’ button
3. In focused input field, type the name of a grocery item, ie. ‘apples’ (sans quotes)
4. Click the Tab button to save to list
5. Click ‘add item’ button
6. Leave the focused input field blank
7. Click the Tab button

Result
Empty item is added to the list

Expected Result
An item without any name value provided is not added to the list

Additional Notes
It is not a requirement to first have a valid item added to the list in order to reproduce the issue. Steps 1-4 are intended to show expected behavior with a non-empty item.
—

If you are out there reading this and file bug tickets, please, for the love of software, log a ticket with a structure similar to this. Most modern bug tracking systems have fields like this, but you’d be surprised (or maybe not) how tickets come in sometimes. My least favorite is explained bug in the title. I can only imagine that they are the same people who write the whole email in the Subject field.

Alright, so now we know what we are dealing with. We have clear steps to reproduce the issue we think is a bug and have explained the difference between the actual result and the intended/expected result. Let’s tackle it.

Tests

As the developer of the application, we probably know exactly where this is happening. Our initial response is to go write to the source and resolve this issue. But we’re not going to do that. Don’t give me that look. I know, I know. The less we have to be in bug-fixing-mode, the happier developer we be, but I think if we have a test that supports the validity of this claim then, when we do make changes to the application code and it still passes, we know we have not committed a regression. I think it is a confidence builder in relying on my code to work properly and takes away some stress when refactoring comes into play.

Before we begin, let’s think about where we will add the tests. We could append another spec suite to the Add Item specs – after all, this bug occurs upon the completion of the Add Item feature. But in thinking about how to reproduce the issue, it seems like it may be another feature, or at least could be discovered in a feature we haven’t addressed – Edit Item. Essentially, when we get to the 3rd step – In focused input field, type the name of a grocery item, ie. ‘apples’ (sans quotes) – we have already added the item to the list. It has entered an edit mode, from which we need to ensure the validity of the value provided before saving it to the list.

Now, a true TDD‘er probably would stop me right now and tell me I am thinking too much to get this resolved. And, in part, they would be correct in doing so. But it is not my intent to start dreaming up new features during bug fixing. I just want to properly think about where the tests make the most sense. I don’t think they belong as an addendum to the Add Item specs and should live in there own spec suite in a separate file:

/test/jasmine/spec/feature/saveitem.spec.js

define(['jquery', 'script/controller/list-controller', 'script/controller/list-item-controller'],
        function($, listController, itemControllerFactory) {

  describe('Save item to grocery list', function() {

    it('should not save an empty item to the list') {
      expect(true).toEqual(false);
    }

  }
}

Given the steps provided in the bug ticket, we could easily translate that into the setup for the spec suite:

/test/jasmine/spec/feature/saveitem.spec.js

define(['jquery', 'script/controller/list-controller', 'script/controller/list-item-controller'],
        function($, listController, itemControllerFactory) {

  describe('Save item to grocery list', function() {

    var item,
        itemName = 'apples',
        invalidName = '',
        itemRenderer,
        async = new AsyncSpec(this);

    beforeEach( function() {
      item = listController.createNewItem();
      itemRenderer = listController.getRendererFromItem(item);
    });

    it('should not save an empty item to the list', function() {
      expect(true).toEqual(false);
    });

    afterEach( function() {
      item = undefined;
      itemRenderer = undefined;
    });
  });

});

In the beforeEach() setup, we have progressed the application – or at least a list item – to essentially the 3rd step in the Steps to Reproduce: we have added a new item to the list, and internally upon addition of an item in the list-controller, it has entered edit-mode for that item. In the variable declarations, we have also defined what we know of as being valid and invalid item entry names: ‘apples’ and ”, respectively.

We should be ready to go in our specs now to define the rest of the steps and expected results:

/test/jasmine/spec/feature/saveitem.spec.js

it('should not save an empty item to the list', function() {
  var listLength = listController.getItemList().itemLength();

  item.name = invalidName;
  // save item... ?
  expect(listController.getItemList().itemLength()).toEqual(listLength);
});

Oh, boy. How do we actually save an item? There is no API on the list-controller that saves an item. There used to be, but we refactored that out when we handed over item management to the list-item-controller. Furthermore, an item is added and kept on the list since its request for creation – the actual reason for the bug, I suppose. I am fine with such functionality internally to the list-controller as it stands now and don’t intend to change the item creation. I think an additional event should be dispatched from a list-item-controller signifying a request to commit the item to the list after being edited. Let’s finish up this spec under such assumptions, then work our way through the failing test:

/test/jasmine/spec/feature/saveitem.spec.js

async.it('should not save an empty item to the list', function(done) {
  var listLength = listController.getItemList().itemLength();

  $(itemRenderer).on('commit', function(event) {
    expect(listController.getItemList().itemLength()).toEqual(listLength-1);
    done();
  });

  item.name = invalidName;
  itemRenderer.save();
});

We marked the spec as asynchronous to support events from the list-item-controller and placed the expectation within the ‘commit’ event handler.

Run that, and we’ll be waiting for about 5 seconds until we are told that save() is not a method on the list-item-controller instance:

I have temporarily commented out the other tests in order to remove any noise and focus solely on resolving this bug. This is for local testing and would not commit the spec runner in such a state when committing back to the repo and running latest on a CI server.

To resolve that, let’s open up list-item-controller and add that method:

/script/controller/list-item-controller.js

listItemController = {
  $editableView: undefined,
  $uneditableView: undefined,
  init: function() {
    ...
    return this;
  },
  save: function() {
  },
  dispose: function() {
    ...
  }
};

Run that again, and now we are down to just the timeout failure:

To resolve that, we’ll first create a new event factory method and invoke it from save() to dispatch the commit event, of which we have assigned a handler for in the test:

/script/controller/list-item-controller.js

function createSaveEvent(controller) {
  var event = $.Event('commit');
  event.controller = controller;
  return event;
}

and…

save: function() {
  $(this).trigger(createSaveEvent(this));
},

No more timeout!

But still failing. Reason is that the item had not been removed from the collection. In previous tests we have verified its addition to the collection from the createNewItem() method on list-controller. Now that we are saving the list-item-controller with a modified model that has an invalid name, we are expecting such an action to remove the item from the collection – the crux of our Empty Item bug.

Let’s modify the list-controller in order to handle the commit event from a list-item-controller:

/script/controller/list-controller.js

$collection.on('collection-change', function(event) {
  var model, itemController, $itemView;
  switch( event.kind ) {
    case EventKindEnum.ADD:
      $itemView = $('<li>');
      model = event.items.shift();
      itemController = itemControllerFactory.create($itemView, model);

      $itemView.appendTo(listController.$view);
      rendererList.addItem(itemController);
      itemController.state = itemControllerFactory.state.EDITABLE;
      $(itemController).on('remove', function(event) {
        listController.removeItem(model);
      });
      $(itemController).on('commit', function(event) {
        if(!isValidValue(model.name)) {
          listController.removeItem(model);
        }
      });
      break;
    case EventKindEnum.REMOVE:
      model = event.items.shift();
      itemController = listController.getRendererFromItem(model);

      if(itemController) {
        $itemView = itemController.parentView;
        $itemView.remove();
        itemController.dispose();
        $(itemController).off('remove');
        $(itemController).off('commit');
        rendererList.removeItem(itemController);
      }
      break;
    case EventKindEnum.RESET:
      break;
  }
});

We’ve added another event listener to the list-item-controller when it is added to the collection to handle the commit event. Within the handler we check for its validity – which we have predetermined as not being an empty string – and if it does not pass, then we remove it.
Note: In shipped code I would hold a single reference to a wrapped non-jQuery object and not wrap it multiple times as is shown here when adding and removing event handlers. I left it in this example to not add extra noise to the task at hand.

Run that, and we are back to green!

User Test

Let’s run the application and see if the issue is resolved:

I think that picture says it all…

The bug is still there because save() is not being called on the list-item-controller. In our test, we explicitly called it after a change to the model, but in the application itself it is not being invoked upon change to the model.

But before we start adding calls to save() in our code, let’s think about the steps to reproduce the bug… or at least the fourth step – Click the Tab button to save to list. The tab keystroke, internally to the list-item-controller, causes a blur to the input field. If we look at the code from list-item-controller, that blur event performs a change to state:

/script/controller/list-item-controller.js

$('input', this.$editableView).on('blur', (function(controller) {
  return function(event) {
    controller.model.name = $(this).val();
    controller.state = stateEnum.UNEDITABLE;
  };
}(this)));

This snippet is taken from the event handler assignment in the init() function. When in edit mode of the list-item-controller, once focus is lost from the input field – which happens upon tab – the model is updated and state changed to non-edit mode. My first inkling is to put it here. It is true that, in doing so, it will pass and get rid of the bug… but the real commit of changes to the list-item-controller and its underlying model I feel lie in its change from edit mode to non-edit mode. I would argue that save() should be called from that occurrence. But before we add that to the code, let’s write up an expectation of that behavior.

More Tests

‘WHAT?!? The bug was in our sights. We know how to get rid of it, and you want to write more tests?!?’
That is the voice in my head most of the time when I decide to go back to tests. It has lessened, and the swearing really has decreased. And when I finally do get around to passing tests, it goes away and is replaced with: ‘Nice job! You deserve a raise.. or at least an egg sandwich!’

Anyway, let’s get to Egg Sandwich Status and add another test to ensure that upon change to non-edit mode, if the model properties are not valid, that the item is not saved:

/test/jasmine/spec/feature/saveitem.spec.js

async.it('should not save an empty item upon change to non-edit mode', function(done) {
   var listLength = listController.getItemList().itemLength();

  $(itemRenderer).on('commit', function(event) {
    expect(listController.getItemList().itemLength()).toEqual(listLength - 1);
    done();
  });

  item.name = invalidName;
  itemRenderer.state = itemControllerFactory.state.UNEDITABLE;
});

We have already verified the expectation that a list-item-controller is entered into an EDITABLE state from our additem.spec.js tests, so we don’t need to test for that here – just know that setting the list-item-controller instance to an UNEDITABLE state will trigger it to go into non-edit mode.

Run that, and we get the timeout failure from that test:

Good! Before you slap me… save that hand for modifying the list-item-controller to invoke the save() method from its state-change handler:

/script/controller/list-item-controller.js

function handleStateChange(controller, event) {
  // remove state-based item.
  if( typeof event.oldState !== 'undefined') {
    if(event.oldState === stateEnum.UNEDITABLE) {
      controller.$uneditableView.detach();
    }
    else if(event.oldState === stateEnum.EDITABLE) {
      controller.$editableView.detach();
    }
  }
  // append state-based item.
  if(event.newState === stateEnum.UNEDITABLE) {
    controller.parentView.append(controller.$uneditableView);
    controller.save();
  }
  else if(event.newState === stateEnum.EDITABLE) {
    var inputTimeout = setTimeout( function()  {
      clearTimeout(inputTimeout);
      $('input', controller.$editableView).focus();
    }, 100);
    controller.parentView.append(controller.$editableView);
  }
}

One little addition. Now run the tests:

Hooray! Now use that hand you were gonna slap me with and high-five yourself. Now look at yourself… you look silly. Run the application you crazy solo-high-fiver:

That picture doesn’t say much, but – if all has gone well – it conveys that we are no longer able to save an item to the list when nothing has been provided in the input field and we can close the bug.

Can’t Stop. Won’t Stop

I would normally stop there, but I do like to sew things up nicely and verify all expectations. Such as:

1. Item controller view is not retained in list view if not valid:
/test/jasmine/spec/feature/saveitem.spec.js

async.it('should not add an empty item to list view upon change to non-edit mode', function(done) {
   var listViewLength = $listView.children().length;

  $(itemRenderer).on('commit', function(event) {
    expect($listView.children().length).toEqual(listViewLength - 1);
    done();
  });

  item.name = invalidName;
  itemRenderer.state = itemControllerFactory.state.UNEDITABLE;
});

2. When going from edit to non-edit mode, valid items are retained:
/test/jasmine/spec/feature/saveitem.spec.js

async.it('should save a valid item upon change to non-edit mode', function(done) {
   var listLength = listController.getItemList().itemLength();

  $(itemRenderer).on('commit', function(event) {
    expect(listController.getItemList().itemLength()).toEqual(listLength);
    done();
  });

  item.name = itemName;
  itemRenderer.state = itemControllerFactory.state.UNEDITABLE;
});

async.it('should add a valid item to list view upon change to non-edit mode', function(done) {
   var listViewLength = $listView.children.length;

  $(itemRenderer).on('commit', function(event) {
    expect($listView.children().length).toEqual(listViewLength);
    done();
  });

  item.name = itemName;
  itemRenderer.state = itemControllerFactory.state.UNEDITABLE;
});

Those additional specs will pass with flying colors and without having to modify any more application code:

Tagged 0.1.12: https://github.com/bustardcelly/grocery-ls/tree/0.1.12

Conclusion

In this article we tested our way to closing a bug.

Just as we had done in the previous article, we adhered more closely to the principles of TDD and trudge along making things turn red before green – even when we found the reason and knew the resolution for the Empty Item bug. In doing so, we sort of verified and documented in test a Save Item feature. Now we know where to add or modify tests if the usability in committing an item to the list is changed in our requirements.

Todd can’t leave well enough alone

The application is pretty much ready to use as is to boot! There is just one more thing that is nagging me – persistence. No pun intended. We can create a list of all the items we need at the grocery store just fine, but if we close the browser window… oh-noes. It’s lost. I gotta fix that… next.

Cheers for sticking around!

—-

Link Dump

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
TDD as if you Meant it by Keith Braithwaite
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

Introduction

In the previous article we resolved tests for the Mark Off Item feature that were left in a failing state after refactoring the list-controller. The test are all green now and the application usable, but we are not done with implementing the required features. In this article I plan to address another – the Remove Item feature.

Before we begin, let’s drum up a quick story and scenario(s) for the Remove Item feature. I know the feature seems a little simple – just remove an item from the list – and going through and adding stories and scenarios may appear like adding complexity to the situation, but since I have begun to incorporate such a workflow, I feel like it actually gives me more time to think about not only the necessity of the feature but the design; in result, hopefully* cutting down on the complexity of the code.

// story
Feature: remove item from grocery list

In order to not buy an item previous on a grocery list
As a grocery shopper
I want to remove the existence of the item on the grocery list
—

That may be worded rather harshly, but I shop angry. It’s how I keep the cantelope in check. ‘I see you looking at me, you lousy melon.’ All kidding aside, I tend to be a little more terse in describing stories so as not to mince words (no pun intended) and leave as little vagueness as possible. Sometimes, I’ll admit, there is no avoiding having the story lead to a lot of assumptions – but that is where scenarios come in.

// spec
Scenario 1: Item removed from grocery list
Given an item has been added to the list
When a user requests to remove the item
Then the list decreases in size by one

Hmm. Pretty straight forward. Well, it all seems rather easy going to implement this feature. Looks like it might be a short blog post, for once; we’ll see how much rambling I can pack in. At least we have something to show somebody who doesn’t want/need to read code when they ask, ‘But, what does it do?’.

Tests

As always, before we get into adding code to the components of the application to implement the new feature, let’s get some failing tests to pass. We’ll start of with defining a new spec suite for the Remove Item feature, with the setup (beforeEach()) being the Given describe above:

/test/jasmine/spec/feature/removeitem.spec.js

define(['jquery', 'script/controller/list-controller'], function($, listController) {

  describe('Remove item', function() {

    var $listView = $('<ul/>'),
        groceryItem;

    beforeEach( function() {
      listController.setView($listView);
      groceryItem = listController.createNewItem();
    });

    it('should remove existing item from the collection', function() {
      expect(false).toEqual(true);
    });

    afterEach( function() {
      groceryItem = undefined;
    });

  });

});

Don’t mind the expectation declared in the spec. Jasmine does not check empty specs and automatically fail them. In fact, if we ran it without any expectations defined, it would be all green. So, I usually drop a failing expectation in quickly when creating new specs in cases where someone/thing comes and interrupts me, I know where to pick back up when i come back. It’s habit. Maybe a little paranoia. Don’t know if it’s right or wrong

If you have been following along in the articles of this series, I typically do my implementation in the tests then move them to their respective modules. It’s a nice workflow for me, and in most cases I feel it gets me more focused on design. In this case, I am just going to declare my expectations, see them fail and move over to implementing the code right in the module, running the spec runner as we go until we see green.

Anyway, first on the agenda is to verify that the Remove API from list-controller is expected to remove the item from the underlying collection of grocery list items:

/test/jasmine/spec/feature/removeitem.spec.js

it('should remove existing item from the collection', function() {
  var collection = listController.getItemList(),
      removedItem;

  removedItem = listController.removeItem(groceryItem);

  expect(removedItem).toBe(groceryItem);
  expect(collection.getItemIndex(groceryItem)).toBe(-1);
});

Add the new spec to the spec runner:
/test/jasmine/specrunner.html

require( ['spec/feature/additem.spec.js', 'spec/feature/markitem.spec.js', 'spec/feature/removeitem.spec.js',
          'spec/list-controller.spec.js', 'spec/list-item-controller.spec.js', 'spec/grocery-ls-item.spec.js',
          'spec/collection.spec.js'], function() {

  var jasmineEnv = jasmine.getEnv(),
      ...
  jasmineEnv.execute();

});

Run that, and we have a big honking failure:

Good!

In looking at the expectations of the removeItem() method on list-controller, we are expecting that the item is removed from the collection and returned on invocation. Let’s implement removeItem on list-controller with this understanding:

/script/controller/list-controller.js

listController = {
  $view: undefined,
  getItemList: function() {
    return collection;
  },
  getRendererFromItem: function(item) {
    var i = rendererList.itemLength();
    while( --i > -1 ) {
      if(rendererList.getItemAt(i).model === item) {
        return rendererList.getItemAt(i);
      }
      return undefined;
    }
  },
  createNewItem: function() {
    var model = modelFactory.create();
    collection.addItem(model);
    return model;
  },
  removeItem: function(item) {
    return collection.removeItem(item);
  },
  setView: function(view) {
    this.$view = (view instanceof $) ? view : $(view);
  }
};

Run it, and we pass!

Well, that was sort of easy and anti-climatic. No drama. A little boring, if I may say so.

But… there’s more! The list-controller isn’t just some dumb facade to the underlying Grocery List collection – it also manages the associated renderers to the grocery-ls-item models. Let’s get back to our tests and add a new spec:

/test/jasmine/spec/feature/removeitem.spec.js

it('should remove item renderer from view', function() {
  listController.removeItem(groceryItem);

  expect($listView.children().length).toEqual(0);
});

Just as we had done for the Add Item feature specification, we are inspecting the view reference held by list-controller that is updated based on change to the model. In this case, we are expecting that the list item renderer is removed upon removeItem() as well.

Run that, and failure!

It might be important to note the actual print out from the failing expectation. It says that the length of children on the list view is 2 – that is because we now have 2 specs that are defining the expectations of removeItem() that are failing to remove the item view from the list.

Let’s switch over the list-controller and get this sorted and back to green. But before we do, let’s think about the relationship of the list-controller and its underlying collection. The list-controller responds to collection event for EventKindEnum.ADD in order to modify the view. So, we will respond to EventKindEnum.REMOVE accordingly to modify the view on removal of an item as well, instead of adding more logic to the removeItem() method on list-controller:

/script/controller/list-controller.js

$collection.on('collection-change', function(event) {
  var model, itemController, $itemView;
  switch( event.kind ) {
    case EventKindEnum.ADD:
      $itemView = $('<li>');
      model = event.items.shift();
      itemController = itemControllerFactory.create($itemView, model);

      $itemView.appendTo(listController.$view);
      rendererList.addItem(itemController);
      itemController.state = itemControllerFactory.state.EDITABLE;
      break;
    case EventKindEnum.REMOVE:
      model = event.items.shift();
      itemController = listController.getRendererFromItem(model);

      if(itemController) {
        $itemView = itemController.parentView;
        $itemView.remove();
        rendererList.removeItem(itemController);
      }
      break;
    case EventKindEnum.RESET:
      break;
  }
});

In the EventKindEnum.REMOVE case, we are grabbing the model provided on the event, using it to access the associated list-item-controller instance, and – if defined – removing the list item renderer view from the DOM and the controller from the renderer collection.

Run that, and we are back to green!

Tagged 0.1.10: https://github.com/bustardcelly/grocery-ls/tree/0.1.10

Back to Reality

We’ve got test for the removal of a grocery list item working. We are currently feature complete. Let’s ship it! But hold up, does the Grocery List application – the thing we are actually building for someone like myself to Use in real life – actually use the new Remove API. We defined a business feature that was a requirement to have, and met that expectation, but we really didn’t address how an item is removed, or under what circumstances…

Without getting to crazy on discussing how to handle swipe gestures and implementing press-and-hold menu actions, let’s just start with saying that the list-item-controller will dispatch a new event – remove. How we decide on the usability of an item being deleted could easily be another whole discussion on User Experience. For now, we want to verify that when a list-item-controller dispatches a remove event, that it is handled properly.

Tests

We’ll start with the specs for the list-controller. We are not going to be adding any new specs to the Remove Item feature to accomplish the implementation of list-item-controller notifying of a remove event; it seems a little odd to me as well, but we have already established that the Remove API performs as expected. We need to verify that the list-controller uses that API in response to a list-item-controller – less of a feature and more of an integration point.

/test/jasmine/spec/list-controller.spec.js

describe('list-item-controller remove event response', function() {

  it('should invoke list-controller:removeItem()', function() {
    var newItem = listController.createNewItem(),
        itemRenderer = listController.getRendererFromItem(newItem);

    spyOn(listController, 'removeItem');
    $(itemRenderer).trigger('remove');
    expect(listController.removeItem).toHaveBeenCalledWith(newItem);
  });

});

In this spec, we set up a spy to verify that the removeItem() method is invoked upon dispatch of remove from a list-item-controller instance.

Run that and we are back to red, with a message letting us know that removeItem() was never called.

Good. Let’s open up list-controller and implement a remove event response:

/script/controller/list-controller.js

$collection.on('collection-change', function(event) {
  var model, itemController, $itemView;
  switch( event.kind ) {
    case EventKindEnum.ADD:
      $itemView = $('<li>');
      model = event.items.shift();
      itemController = itemControllerFactory.create($itemView, model);

      $itemView.appendTo(listController.$view);
      rendererList.addItem(itemController);
      itemController.state = itemControllerFactory.state.EDITABLE;
      $(itemController).on('remove', function(event) {
        listController.removeItem(model);
      });
      break;
    case EventKindEnum.REMOVE:
      model = event.items.shift();
      itemController = listController.getRendererFromItem(model);

      if(itemController) {
        $itemView = itemController.parentView;
        $itemView.remove();
        itemController.dispose();
        $(itemController).off('remove');
        rendererList.removeItem(itemController);
      }
      break;
    case EventKindEnum.RESET:
      break;
  }
});

We added the remove handler delegation in the ADD case when the collection changes, along with the other implementation of item renderer establishment. And, for good measure and memory management, we are sure to remove the event handler in the REMOVE case from the collection change, as well.

Run the test now and we are back to green!

list-item-controller Modification

That’s great, but we are still glazing over the usability aspect: How does a User delete an item?

Again, we could go into a lengthy discussion of UX and code implementations, but to save yourself from scrolling just to read me ramble off topic, we’ll keep it simple: add a delete button! I don’t know why I got excited there. I’ll show the implementation in piecemeal just to see how it all comes together. First we’ll start with the markup we declared for the list-item-controller views:

/script/controller/list-item-controller.js

uneditableItemFragment  = '<p class="grocery-item">' +
                                             '<span class="grocery-item-label" />' +
                                             '<button class="delete-item-button">delete</button>' +
                                           '</p>',
editableItemFragment    = '<p class="editable-grocery-item">' +
                                            '<input name="editableItem" ' +
                                              'class="editable-item" placeholder="Enter item name...">' +
                                            '</input>' +
                                         '</p>'

The uneditableItemFragment markup has changed slightly to support a label and a button. It was previously just a p element all by its lonesome, but with several references for modification and event click event handling. We’ll need to update those, as well as add another event handler for the button element:

/script/controller/list-item-controller.js

init: function() {
  this.$editableView = $(editableItemFragment);
  this.$uneditableView = $(uneditableItemFragment);

  // view handlers.
  $('span.grocery-item-label', this.$uneditableView).on('click', (function(controller) {
    return function(event) {
      var toggled = $(this).css('text-decoration') === 'line-through';
      controller.model.marked = !toggled;
    };
  }(this)));
  $('button.delete-item-button', this.$uneditableView).on('click', (function(controller) {
    return function(event) {
      $(controller).trigger(createRemoveEvent(controller));
    };
  }(this)));
  ...
}

As seen previously, we are using IIFEs here as a factory method in order to pass in a reference to the list-item-controller instance instead of declaring the old:

var self = this;

and then passing self around which always makes me cringe. In any event (no pun intended), we have transferred the click handling previously assigned to the p element over the span element in order to support the usability of marking off an item. As well, we added handling of delete button click to trigger a new event:

/script/controller/list-item-controller.js

function createRemoveEvent(controller) {
  var event = $.Event('remove');
  event.controller = controller;
  return event;
}

Pretty straight forward in how we have create factory methods for our jQuery events previously in this series. Next we need to modify the references that respond to model changes, such as the marked property value:

/script/controller/list-item-controller.js

function handlePropertyChange(controller, event) {
  if(event.property === "name") {
    // update view based on model change.
    $('input', controller.$editableView).val(controller.model.name);
    $('span.grocery-item-label', controller.$uneditableView).text(event.newValue);
  }
  else if(event.property === "marked") {
    // update view based on model change.
    $('span.grocery-item-label', controller.$uneditableView)
        .css('text-decoration', ( event.newValue ) ? 'line-through' : 'none');
  }
}

Alright. That should just about do it. Now you may be saying to yourself, ‘Why haven’t we modified any tests in order to support this change in UI and event handling?’ To which I will respond, ‘Stop bringing that up!’ In all seriousness, we perhaps should be writing tests to support these changes, however those will get pretty fine grained on the UI design aspect of the application. As you can see, it is constantly changing at this time and we are more concerned with the logical points of how the Grocery List application should behave.

Like with most of my code, future me may look back and shake his head at past me for such a statement – but for right now, present me will live with it

Using the Grocery List Application

Let’s actually run the application and use it. We spend all this time making our tests turn red and green, we barely get to use what we are building.

Oh my… that is ugly to look at. But it works! And it’s backed by tests!

Because I can’t leave well enough alone, I added some quick styling just to make it a little more pleasant on the eyes. I am not designer, so it might not be any more pleasant to you I won’t go into the styling of the application as that could be a whole ‘nother article and discussion of box model, but feel free to mess around with the styling on your own…

Tagged 0.1.11: https://github.com/bustardcelly/grocery-ls/tree/0.1.11

Conclusion

In this article of the series, we took more of a traditional approach to TDD and went along making things turn red before they turn green, one spec at a time, and all the while implementing the Remove Item feature.

The Grocery List application is also coming along pretty nicely and, as always, is easy and ready to use. But I can’t leave well enough alone and there are a few more items on my list (no pun intended) that I wish to address before ending this series, most importantly persistence. Our grocery list only last within the session of the page – once closed, our list is gone. We’ll get to that, but there might be some other things to address beforehand.

Cheers for sticking around!

—

Link Dump

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

Introduction

We left the previous post with failing tests!

I don’t necessarily condone leaving a master branch in such a state, so don’t give my name to your managers I, however, have no problem with leaving a feature or developer branch at the end of the day with failing tests – within reason. As long as the errors are from unimplemented behavior and the branch is not being monitored by some CI server feeding reports to your client(s), I see no problem. Sometimes I will write out the tests I plan to resolve the following day at 5:30 just so I can get a refresher the next morning as to the task at hand.

In the article I plan to get your tests all green again by modifying the Mark Off Item tests and possibly add a few new features.

Mark Off Item Feature

Way back in the third article in this series, we wrote up a story and some feature specs around the usability of marking off an item already existant in the list of item of the Grocery List application. In getting this feature implemented, we added a basic mark-item API to the list-controller, which allowed us to pass in a grocery-ls-item model to the list-controller which would then modify its state.

In the previous couple posts, we have refactored list-controller to not be responsible for item state and to respond to changes on a collection model – this is what led us to failing tests. We still want to keep the Mark Off Item feature, but instead of having specs that tested the mark-item API of the list-controller, we’re going to change the specs to verify that the grocery-ls-item model that is being modified updates its state and is retained in the collection held by the list-controller.

Tests

When I start creating the tests, I take some time in thinking about the Givens. Typically, the Givens are what make up the beforeEach() setup of a spec suite, but they can also lead to address some design concerns about components involved in getting the tests to pass. Such is the case in modifying our Mark Off Item feature specs.

We are not necessarily going to test the UI changes related to the action of marking off an item from the Grocery List. We could, but it is more important to me to test that the grocery-ls-item model that holds that state value of being marked is properly retaining that value and accessible from not only the collection, but from the associated list-item-controller instance, as well – after all, it is the list-item-controller that is responsible for responding to changes to an item being marked-off; i want to ensure that, in the very least, it has the opportunity, not actually what it does with the opportunity.

That statement may sound foolish, i’ll admit. If it was an expectation that the action of marking off an item was to trigger a reaction that defined another feature specification, then certainly I would write up tests accordingly. But as it stands, it changes a style on the list-item-controller view. I am not so concerned with that implementation at the moment – if it becomes a real business issue and it was a requirement to have the text shown with a strike-through, then yes.

Let’s start with the setup and teardown for the Mark Off Item feature specs:

/test/jasmine/spec/feature/markitem.spec.js

define(['jquery', 'script/controller/list-controller', 'script/controller/list-item-controller'],
        function($, listController, itemControllerFactory) {

  describe('Existing item is marked-off', function() {

    var item,
        itemController,
        getRendererStub;

    beforeEach( function() {
      item = listController.createNewItem();

      itemController = itemControllerFactory.create($('<li/>'), item);
      getRendererStub = sinon.stub();
      getRendererStub.returns(itemController);
      listController.getRendererFromItem = getRendererStub;
    });

    afterEach( function() {
      item = undefined;
      itemController = undefined;
      getRendererStub = undefined;
    });

  });

});

In the beforeEach(), we’ve stubbed out a new method on list-controller that allows us to access the associated list-item-controller with a model: getRendererFromItem().

If you remember from the last article, we also did some stubbing of methods before moving to implementation on list-controller. We are doing the same here and using the SinonJS stub API to stub a method that currently does not exist on list-controller. To do so, and not have exceptions thrown in your tests regarding the existence of the method on the object being stubbed, you create an anonymous stub and assign it to the target object:

/test/jasmine/spec/feature/markitem.spec.js

getRendererStub = sinon.stub();
getRendererStub.returns(itemController);
listController.getRendererFromItem = getRendererStub;

The stub is sort of a fub, seeing as it is not really accessing the list-item-controller created by the list-controller in response to change on the collection – but it does provide some basis of design in that getRendererFromItem() is expected to return a list-item-controller which in turn responds to the provided model. Anyway, once we remove the stub and implement the API on the list-controller itself, we’ll certainly have to write more tests for that integration as we are not necessarily concerned in this specification of getRendererFromItem() returning the correct list-item-controller instance… so you have that to look forward to Right now, we only care about the preservation of state and model existence within the application.

First we’ll test that setting an item as marked is preserved in the model and held on the item controller:
/test/jasmine/spec/feature/markitem.spec.js

it('should denote item as being in possession', function() {
  var itemRenderer = listController.getRendererFromItem(item);
      savedItemSpy = sinon.spy();

  savedItemSpy(itemRenderer.model);
  item.marked = true;

  expect(item.marked).toEqual(true);
  sinon.assert.calledWith(savedItemSpy, sinon.match.hasOwn('marked', true));
});

Then, I want to ensure that marking off an item does not mean that it is removed from the overall collection:
/test/jasmine/spec/feature/markitem.spec.js

it('should retain the item in the grocery list collection', function() {
  var itemIndex = listController.getItemList().getItemIndex(item);

  item.marked = true;
  expect(listController.getItemList().getItemIndex(item)).toEqual(itemIndex);
});

And finally, just to be sure that we can safely toggle the marked off state and it be retained:
/test/jasmine/spec/feature/markitem.spec.js

it('should retain item in renderer listing regardless of marked-off status', function() {
  var itemRenderer = listController.getRendererFromItem(item),
      itemIndex = listController.getItemList().getItemIndex(item);

  item.marked = true;
  item.marked = false;

  expect(itemRenderer.model.marked).toEqual(false);
  expect(listController.getItemList().getItemIndex(item)).toEqual(itemIndex);
});

Perhaps the last one is out of a little paranoia, but it also describes the behavior of the Mark Off Item feature as being togglable from a User standpoint – meaning, marking off an item is not considered deleting it from the list. Also, a little paranoia sprinkled on some tests can save you from fret when working with the implementation code.

Speaking of implementation…

list-controller Implementation

Moving the getRendererFromItem() method over to the list-controller will involve holding and maintaining a list of list-item-renderers. We’ll use the Collection object we created previously for the models and place the job of curation between both collections on the list-controller:

/script/controller/list-controller

var collection = collectionFactory.create(),
    rendererList = collectionFactory.create(),
    listController = {
      $view: undefined,
      getItemList: function() {
        return collection;
      },
      getRendererFromItem: function(item) {
        var i = rendererList.itemLength();
        while( --i > -1 ) {
          if(rendererList.getItemAt(i).model === item) {
            return rendererList.getItemAt(i);
          }
          return undefined;
        }
      },
      createNewItem: function() {
        var model = modelFactory.create();
        collection.addItem(model);
        return model;
      },
      setView: function(view) {
        this.$view = (view instanceof $) ? view : $(view);
      }
    };

If an associated list-item-controller cannot be found from the provided grocery-ls-item model, then undefined is returned. We will ensure this and other expectations in a new integration test for the list-controller in a bit, but for now we have a little more work to do in order for the list-controller to behave as described in the Mark Off Item feature specs.

Next step is to have the tests fail by removing the stub for the getRendererFromItem() method now on the list-controller:
/test/jasmine/spec/feature/markitem.spec.js

define(['jquery', 'script/controller/list-controller'],
        function($, listController) {

  describe('Existing item is marked-off', function() {

    var item;

    beforeEach( function() {
      item = listController.createNewItem();
    });

    it('should denote item as being in possession', function() {
      var itemRenderer = listController.getRendererFromItem(item);
          savedItemSpy = sinon.spy();

      savedItemSpy(itemRenderer.model);
      item.marked = true;

      expect(item.marked).toEqual(true);
      sinon.assert.calledWith(savedItemSpy, sinon.match.hasOwn('marked', true));
    });

    it('should retain the item in the grocery list collection', function() {
      var itemIndex = listController.getItemList().getItemIndex(item);

      item.marked = true;
      expect(listController.getItemList().getItemIndex(item)).toEqual(itemIndex);
    });

    it('should retain item in renderer listing regardless of marked-off status', function() {
      var itemRenderer = listController.getRendererFromItem(item),
          itemIndex = listController.getItemList().getItemIndex(item);

      item.marked = true;
      item.marked = false;
      expect(itemRenderer.model.marked).toEqual(false);
      expect(listController.getItemList().getItemIndex(item)).toEqual(itemIndex);
    });

    afterEach( function() {
      item = undefined;
    });

  });

});

Run the tests, and we’ll get failures related to the getRendererFromItem() method returning undefined with each call:

Good. That sort of assures us that getRendererFromItem() works as expected. This little mid-implementation failure won’t save us from writing proper tests for list-controller, but it’s a warm feeling for now

The reason that getRendererForItem() is returning undefined on each call is that we have not modified list-controller to add the list-item-controller renderer to the underlying rendererList collection. Let’s add the maintenance to the collection-change response on the model collection:

/script/controller/list-controller

$collection.on('collection-change', function(event) {
  var model, itemController, $itemView;
  switch( event.kind ) {
    case EventKindEnum.ADD:
      $itemView = $('<li>');
      model = event.items.shift();
      itemController = itemControllerFactory.create($itemView, model);

      $itemView.appendTo(listController.$view);
      rendererList.addItem(itemController);
      itemController.state = itemControllerFactory.state.EDITABLE;
      break;
    case EventKindEnum.REMOVE:
      break;
    case EventKindEnum.RESET:
      break;
  }
});

We’ve moved the variable declarations out of the switch..case for the ADD event type; they are hoisted by the interpreter, anyway, but I like a little more clarity. More importantly, we are adding the newly created list-item-controller to he renderList.

Run the tests and we’ll be back to green!

Hold on! Before you run out the door and down the street singing my praises… you need pants. I don’t know why you are reading this article without pants, but you probably will get a fine. Plus, we really need to add some tests for the list-controller.

list-controller Tests

The Mark Off Item specs we just got to pass are great in describing that feature and the usability, but they don’t necessarily test all the expectations we have of the list-controller and its API. Perhaps we should have wrote up the tests for list-controller and, specifically, the getRendererFromItem() method prior to modifying the Mark Off Item specs and getting them to pass. I would agree with that, but I am also not a stickler… as long as we get some integration tests in for list-controller, I won’t hold it against myself

There are more tests regarding the list-controller API in the repository tagged later in this article, but for now I wanted to create a new spec suite for list-controller and test the expectations we had previously described for the getRendererFromItem() method:

/test/jasmine/spec/list-controller.spec.js

define(['jquery', 'script/controller/list-controller', 'script/model/grocery-ls-item'],
        function($, listController, modelFactory) {

  describe('Grocery List list-controller', function() {

    describe('getRendererItem()', function() {

      it('should return renderer associated with model', function() {
        var itemModel, renderer;

        itemModel = listController.createNewItem();
        renderer = listController.getRendererFromItem(itemModel);
        expect(renderer).not.toBeUndefined();
        expect(renderer.model).toBe(itemModel);
      });

      it('should return undefined with no associated model', function() {
        var itemModel, renderer;

        itemModel = modelFactory.create();
        renderer = listController.getRendererFromItem(itemModel);
        expect(renderer).toBeUndefined();
      });

    });

  });

});

We have defined two tests for the getRendererFromItem() method on list-controller to ensure that it 1) does return the associated renderer when available and 2) does return undefined when an associated renderer is not available.

Let’s add that to the specrunner:
/test/jasmine/specrunner.html

require( ['spec/feature/additem.spec.js', 'spec/feature/markitem.spec.js',
          'spec/list-controller.spec.js', 'spec/list-item-controller.spec.js', 'spec/grocery-ls-item.spec.js',
          'spec/collection.spec.js'], function() {

  var jasmineEnv = jasmine.getEnv(),
      ...
  jasmineEnv.execute();

});

aside

You may be wondering why it seems like I am doubling up on tests; after all, we have verified that the getRendererFromItem() method does as expected from within the Mark Off Item specs. This is true. However, I think of this spec suite, list-controller.spec.js, as more unit tests in that we are verifying how the component behaves. Within the Mark Off Item specs, I feel it is closer to how the component behaves in the system and reveals more of an expectation of the features of the Grocery List application. If I was to do further work in modifying the list-controller, I would start with this spec, and if it impacted the Mark Off Item feature, get that passing afterward. Not stuck in my way of thinking on this, but it my current workflow. Let me know if you have any better strategies.

Actually, that brings up a good point. We should revisit the Add Item specs and add a test to ensure that the newly created item returned from createNewItem() will return an associated list-item-controller instance from getRendererFromItem()…

Add Item Feature Update

We’ll add a spec to the current suite that verifies that the new created grocery-ls-item is properly paired with the list-item-controller and that they associated view is the one made available on the Grocery List UI:

/test/jasmine/spec/feature/additem.spec.js

it('should enable associated item renderer as editable', function() {
  var newItem = listController.createNewItem(),
      itemRenderer = listController.getRendererFromItem(newItem);

    expect(itemRenderer).not.toBeUndefined();
    expect(itemRenderer.model).toBe(newItem);
    expect(itemRenderer.state).toEqual(itemControllerFactory.state.EDITABLE);
    expect($listView.children()[0]).toBe(itemRenderer.parentView.get(0));
});

The last expectation in there utilizes some of the access API from jQuery. If you are unfamiliar with it, it is basically testing that the first item in the parent list view is that of the parentView managed by the associated list-item-controller. If you take a look at the previous spec, we had already verified that the child list of the list view had been changed to include a new item; now we are ensuring that the new item is the correct one, accessible from getRendererFromItem().

I think that pretty much shores up the proper testing in describing the Add Item and Mark Off Item features. Run the tests and all are green!

Tagged 0.1.9 : https://github.com/bustardcelly/grocery-ls/tree/0.1.9

Conclusion

We got the Mark Off Item specs running green again after we had left the application in a failing state from the last article. Hooray! But, we are still only addressing half of the usability features I envision for the Grocery List application. Sometimes it is easy to forget that we are still building an application. If you ran it, you would see that it still works as expected, which I think is rather cool; I mean, we have been busying ourselves ensuring that our code will support our understanding of the system, and at the end of the day, it actually does. We have been running the test runner much more than the actual application. That is not to say that we shouldn’t be doing more User testing…

Anyway, in the next article I think we should address a new feature – Removal. Cheers for sticking around!

—

Link Dump

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

Introduction

The previous article was prefaced to be a refactoring effort to remove responsibilities of item management from the list-controller to instances of a list-item-controller. We designed the list-item-controller through specs, moved the factory to its own AMD and modified not only the grocery-ls-item model, but how the list-item-controller responded to changes of it.

All important and – in my view – much needed changes. However, we fell short on our goal. Sure, the tests still passed, but we modified nothing within the list-controller to reflect this transfer of responsibility. Part of the reason for this is my attempt at not overloading each article in this series with information. The other part is that I wanted a little time to stew over how I actually saw the revision of list-controller.

We still want to keep our feature specs of Add Item and Mark Item (and we have a few more features still to address), but I begin to question if it is really necessary to expose that functionality on the API of the list-controller. I am starting to see that those features are really part of a collection of grocery-ls-item models, and the controllers are just responders to changes on the collection and models themselves – the basis of MVC design.

Just as we implemented list-item-controller in the previous article with a design to respond to changes on a provided grocery-ls-item model and update its state accordingly, I propose so should we refactor the list-controller to respond to changes on a collection of grocery-ls-item models.

Collection

A generic collection is basically an object that provides a higher-level API to interact with an array of items. The API can provide a more readable way of adding and removing items on an underlying Array instance instead of using methods like push or splice – which are base level and don’t use a nomenclature that is best suited for the action taken – but more importantly, the API provides a facade to operations on an array of items from which it can internally have stricter rules over such actions.

There are various libraries and frameworks out there that support collections, and even different type of collections – ie, sets, linked lists, etc. As has been mentioned in previous posts, I am trying not to introduce new libraries into this series as it may add unnecessary noise to the task at hand. This also allows for us to keep the Collection implementation lean and customizable for the Grocery List application; we’re also going to support event notification from the collection, which is not inherent in the JavaScript Array object.

Tests

We will create the design of a Collection object piecemeal as we write the specs for it. To start, we know that it is to be a wrapper around an Array source:

/test/jasmine/spec/collection.spec.js

define( ['jquery'], function($) {

  var collectionImpl = {
        itemLength: function() {
          return this.list.length;
        }
      },
      collectionFactory = {
        create: function(source) {
          var instance = Object.create(collectionImpl, {
              "list": {
                  value: Array.isArray(source) ? source : [],
                  writable: true,
                  enumerable: true
          });
          return instance;
        }
      };

  describe('Collection', function() {

    describe('collection factory instance creation', function() {

      it('should create unique instances of collection from create()', function() {
        var collectionOne = collectionFactory.create(),
            collectionTwo = collectionFactory.create();
        expect(collectionOne).not.toBe(collectionTwo);
      });

      it('should create an empty collection without source array provided', function() {
        var collection = collectionFactory.create();
        expect(collection).not.toBeUndefined();
        expect(collection.itemLength()).toBe(0);
      });

      it('should create a collection from source array provided', function() {
        var items = ['apples', 'oranges'],
            collection = collectionFactory.create(items);
        expect(collection.itemLength()).toBe(2);
      });

    });

  });

});

We have defined two specs that involve testing the wrapped Array source for a collection. Upon creation, the array should be empty if no source array supplied or filled with items if source provided. Pretty straight forward.
Again, we are only concerned with the latest-and-greatest browsers, so you may notice the use of Array.isArray when the list property is defined within the check the source argument on the collectionFactory.create() call.

aside

We could get into a lengthy discussion about the design of collectionImpl, and in particular that the list property is publicly accessible – i mean, after all, are we not defeating the point of providing an API to manipulate the list if some developer could just come along and access it directly? A valid point, and one I struggle with often. We could – and I would recommend, at times – using the functional inheritance pattern to ‘privately’ hold the underlying list within the collection. For example:

var collectionImpl = (function(source) {
  var list = source;
  return {
    itemLength: function() {
      return list.length;
    }
  };
});
var instance = collectionImpl([]);

That would ‘conveniently‘ make the underlying array ‘private’, but there are an arguable list of pros and cons to this approach – the biggest con is the creation of a new object with new functions and new properties each call, rather then a shared inheritance. In essence, each new instance of collection created using this pattern could then modify, add and/or remove methods so that the API is not the same across all ‘instances’ of the collection – that’s a big con for me.

For our implementation, let’s just take it with a grain of salt that we don’t expect anyone to maliciously access the source array of the collection and use the API we are defining in our tests

end aside

Even though in the last spec, we aren’t concerned with the underlying list being strictly equal to the provided source, we should probably check that the list has the correct items and is in the correct order:

/test/jasmine/spec/collection.spec.js

var collectionImpl = {
  itemLength: function() {
    return this.list.length;
  },
  getItemAt: function( index ) {
    if( index < 0 || (index > this.itemLength() - 1) ) {
      return undefined;
    }
    return this.list[index];
  }
}

The getItemAt() method first verifies that the supplied index within the range of the wrapped array and returns undefined if not or the item held in the array at the supplied index. We can ensure that method works properly by adding a couple tests to the spec we already have for verifying the source provided on creation:

/test/jasmine/spec/collection.spec.js

it('should create a collection from source array', function() {
  var itemOne = 'apples',
      itemTwo = 'oranges',
      collection = collectionFactory.create([itemOne, itemTwo]);
  expect(collection.itemLength()).toBe(2);
  expect(collection.getItemAt(0)).toEqual(itemOne);
  expect(collection.getItemAt(1)).toEqual(itemTwo);
});

Let’s go ahead and add some useful methods that will aid in adding and removing items to and from the collection:

/test/jasmine/spec/collection.spec.js

  var collectionImpl = {
    itemLength: function() {
      return this.list.length;
    },
    addItem: function(item) {
      this.list.push(item);
      return item;
    },
    removeItem: function(item) {
      var index = this.list.indexOf(item);
      if( index > -1 ) {
        this.list.splice(index, 1);
        return item;
      }
      return undefined;
    },
    removeAll: function() {
      this.list.length = [];
    },
    getItemAt: function( index ) {
      if( index < 0 || (index > this.itemLength() - 1) ) {
        return undefined;
      }
      return this.list[index];
    }
  }

We could add some specs for addItem() to ensure that the list does grow with each item appended to the end:

/test/jasmine/spec/collection.spec.js

describe('collection item addition', function() {

  var collection;

  beforeEach( function() {
    collection = collectionFactory.create();
  });

  it('should append item to list from addItem()', function() {
    var item = 'grapes';
    collection.addItem(item);
    expect(collection.itemLength()).toBe(1);
    expect(collection.getItemAt(0)).toEqual(item);
  });

  it('should maintain order during multiple additions', function() {
    var itemOne = 'grapes',
        itemTwo = 'grapefruit';
    collection.addItem(itemOne);
    collection.addItem(itemTwo);
    expect(collection.itemLength()).toBe(2);
    expect(collection.getItemAt(1)).toEqual(itemTwo);
  });

  afterEach( function() {
    collection = undefined;
  });

});

… and throw in a spec suite for testing the removal API on the Collection:

/test/jasmine/spec/collection.spec.js

describe('collection item removal', function() {

  var collection,
      itemOne = 'pineapple',
      itemTwo = 'pear';

  beforeEach( function() {
    collection = collectionFactory.create();
    collection.addItem(itemOne);
  });

  it('should remove only specified item and report length of 0 from removeItem()', function() {
    collection.removeItem(itemOne);
    expect(collection.itemLength()).toBe(0);
  });

  it('should remove specified item from proper index', function() {
    collection.addItem(itemTwo);
    collection.removeItem(itemOne);
    expect(collection.itemLength()).toBe(1);
    expect(collection.getItemAt(0)).toEqual(itemTwo);
  });

  it('should retain items in collection if item provided to removeItem() is not found', function() {
    collection.addItem(itemTwo);
    collection.removeItem('watermelon');
    expect(collection.itemLength()).toBe(2);
  });

  it('should empty the list on removeAll()', function() {
    collection.addItem(itemTwo);
    collection.removeAll();
    expect(collection.itemLength()).toBe(0);
  });

  afterEach( function() {
    collection = undefined;
  });

});

With that, we have roughly designed and verified the API for our custom Collection object. Let’s add it to our list of specs to run:

/test/jasmine/specrunner.html

require( ['spec/newitem.spec.js', 'spec/markitem.spec.js',
          'spec/item-controller.spec.js', 'spec/grocery-ls-item.spec.js',
          'spec/collection.spec.js'], function() {

  var jasmineEnv = jasmine.getEnv(),
     ...
  jasmineEnv.execute();

});

Run it and all is green!

Whoa. Settle down… we’re not done yet

Collection Events

If we think back to why we even started down this path of creating a Collection object, we’ll remember that its role in the Grocery List application is to serve as the model for the list-controller. It is the intention to eventually modify the list-controller to not only offload the responsibility of managing the relationship and interaction between individual grocery-ls-item models to their views, but also to respond to changes on the collection of grocery-ls-items accordingly. As such, we will incorporate event notification into our Collection object, from which the list-controller can assign response delegates to changes on the collection.

Using jQuery Event as we have previously in the development of this application throughout this series, we’ll create a factory method that returns an event object based provided arguments. If you are familiar with collections from the Flex SDK, you might notice something similar :

/test/jasmine/spec/collection.spec.js

function createEvent(kind, items) {
  var event = new $.Event('collection-change');
  event.kind = kind;
  event.items = items;
  return event;
}

Basically, any event dispatched from the collection object will be of the same type, and its operation can be differentiated from the kind property. The items affected upon the associated operation (kind) are provided in an array as some operations may involve multiple items.

With the API we have defined for the collection, there are three operations that can modify the the list of items:

• add
• remove
• reset

The methods associated with add and remove are pretty self-explanatory and we will consider removeAll() as a reset on the collection. With this in mind, let’s append a couple tests to our spec suites for these event notifications:

/test/jasmine/spec/collection.spec.js

describe('collection item addition', function() {
...
    async.it('should notify on addition of item', function(done) {
      var item = 'grapes';
      $(collection).on('collection-change', function(event) {
        expect(event.kind).toBe('add');
        expect(event.items.length).toBe(1);
        expect(event.items[0]).toEqual(item);
        $(collection).off('collection-change');
        done();
      });
      collection.addItem(item);
    });
...
});
...
describe('collection item removal', function() {
...
  async.it('should notify on removal of item', function(done) {
    collection.addItem(itemTwo);
    $(collection).on('collection-change', function(event) {
      expect(event.kind).toBe('remove');
      expect(event.items.length).toBe(1);
      expect(event.items[0]).toEqual(itemOne);
      $(collection).off('collection-change');
      done();
    });
    collection.removeItem(itemOne);
  });

  async.it('should notify on reset of collection', function(done) {
    $(collection).on('collection-change', function(event) {
      expect(event.kind).toBe('reset');
      expect(event.items.length).toBe(0);
      $(collection).off('collection-change');
      done();
    });
    collection.removeAll();
  });

  afterEach( function() {
    collection = undefined;
  });
...
});

If you were to run the tests now, you would see a couple execute then hang intermittently as it waits for the async tests to timeout… because we haven’t implemented the dispatching of events from the collection yet

/test/jasmine/spec/collection.spec.js

var collectionImpl = {
  itemLength: function() {
    return this.list.length;
  },
  addItem: function(item) {
    this.list.push(item);
    $(this).trigger(createEvent('add', [item]));
    return item;
  },
  removeItem: function(item) {
    var index = this.list.indexOf(item);
    if( index > -1 ) {
      this.list.splice(index, 1);
      $(this).trigger(createEvent('remove', [item]));
      return item;
    }
    return undefined;
  },
  removeAll: function() {
    this.list.length = [];
    $(this).trigger(createEvent('reset', this.list));
  },
  getItemAt: function( index ) {
    if( index < 0 || (index > this.itemLength() - 1) ) {
      return undefined;
    }
    return this.list[index];
  }
}

Now, if you were to run the tests, all should be happy.

Collection Module Implementation

Just as we have done with the list-item-controller from the previous article, we are going to take the work we had done in implementing the collection object within our tests and move it to an AMD module. This way, if we ever get around to refactoring the list-controller, we’ll be able to utilize the collection module:

/script/collection/collection.js

define(['jquery'], function($) {

  function createEvent(kind, items) {
    var event = $.Event('collection-change');
    event.kind = kind;
    event.items = items;
    return event;
  }

  var _collectionEventKind = {
        ADD: 'add',
        REMOVE: 'remove',
        RESET: 'reset'
      },
      collection = {
        itemLength: function() {
          return this.list.length;
        },
        addItem: function(item) {
          this.list.push(item);
          $(this).trigger(createEvent(_collectionEventKind.ADD, [item]));
          return item;
        },
        removeItem: function(item) {
          var index = this.getItemIndex(item);
          if( index > -1 ) {
            this.list.splice(index, 1);
            $(this).trigger(createEvent(_collectionEventKind.REMOVE, [item]));
            return item;
          }
          return undefined;
        },
        removeAll: function() {
          this.list.length = 0;
          $(this).trigger(createEvent(_collectionEventKind.RESET, this.list));
        },
        getItemAt: function(index) {
          if( index < 0 || (index > this.itemLength() - 1) ) {
            return undefined;
          }
          return this.list[index];
        },
        getItemIndex: function(item) {
          return this.list.indexOf(item);
        },
        contains: function(item) {
          return this.getItemIndex(item) != -1;
        }
      };

  return {
    collectionEventKind: _collectionEventKind,
    create: function(source) {
      var instance = Object.create(collection);
      Object.defineProperty(instance, "list", {
          value: Array.isArray(source) ? source : [],
          writable: true,
          enumerable: true
      });
      return instance;
    }
  };

});

We have basically ripped the collection and factory out from our test implementation and dropped it into its own file, returning the event kind enumeration object and the create() factory method to generate new collections for this AMD module.

To verify that our Collection module works correctly, let’s replace the implementation in the test with this module reference and run our tests again:

/test/jasmine/spec/collection.spec.js

define( ['jquery', 'script/collection/collection'], function($, collectionFactory) {

  describe('Collection', function() {
     ...
  });

});

Tagged: 0.1.6 https://github.com/bustardcelly/grocery-ls/tree/0.1.6

list-controller Refactoring

Passing tests are great! But currently, they are lying to us. Well… not really, but we have gone about all these new additions to our application and have yet still to refactor list-controller to utilize them. However, before we just start chopping out and inserting code from list-controller, I want to go over the API and specs currently defined and see if they still hold water – meaning we might be able to cut some tests out. We might not. We might even add more. Let’s see…

newitem.spec

As we designed the list-controller from a previous article, it oversaw the state of list items, list item views, and sort of supported a quasi-state of ‘editability’. While this provided an API to create a new item, it was forced into exposing an editableItem that was then mutable based on other parts of its API – ie, editFocusedItem() and saveFocusedItem(). All well and good to support the feature requirements at the time, but we have now moved the item and item view management – as well as the editable state – to the latest list-item-controller as can be seen in the repo tagged at 0.1.5. As such, I feel not only the list-controller, itself, should change to reflect these modifications, but also its API.

We are going to stick with our feature request to be able to add a new item to the Grocery List application through the list-controller, but will revisit how that is done in accordance to the new functionality of both the list-item-controller and list-controller; mainly we want to keep in mind that both should be driven by their respective model: grocery-ls-item and collection.

Let’s first revisit the specs we defined for new item feature from the second post in this series:

// spec
—
Scenario 1: Item added to list
Given a user requests to add an item to the list
And has provided a name for the item
When she requests to save the item
Then the list has grown by one item
And the list contains the item appended at the end
—

// spec
—
Scenario 2: Item not added to list
Given the list has a single item
And a user requests to add an item to the list
And has not provided a name for the item
When she requests to save the item
Then the list has the same items as stored previously
And the list does not add an empty-named item
—

In looking at them now, I feel that the actual Add Item feature is hidden in the Givens. A slight oversight now that we have progressed – perhaps one at the time as well, but we were delivering to features using TDD, so I have no qualms with features and implementations revisited and revised as the functionality of the application is fleshed out. In any event, I feel like these feature specs are more for a Save Item story, especially seeing as a User can edit an existing item. We’ll tackle the Save Item specifications for a later post, for now I want to revise the specifications for the Add Item feature.

Tests

The original story does not change, but we want to ensure that a grocery-ls-item model is returned on the API to create a new item from list-controller . With such a drastic refactor to the functionality of list-controller, I tend to do my thinking and designing within the tests and move to implementation – just as I have done previously with other components. Let’s take a look at the change to newitem.spec.js as a whole and then discuss the specs singularly:

/test/jasmine/spec/feature.newitem.spec.js

define(['jquery', 'script/controller/list-controller', 'script/controller/list-item-controller',
        'script/collection/collection', 'script/model/grocery-ls-item'],
        function($, listController, itemControllerFactory, collectionFactory, modelFactory) {

  describe('New item creation from listController.createNewItem()', function() {

    var newModel,
        newItemController,
        listControllerStub,
        $listView = $('<ul/>'),
        itemCollection = collectionFactory.create();

    beforeEach( function() {
      var $itemView = $('<li>');

      newModel = modelFactory.create();
      newItemController = itemControllerFactory.create($itemView, newModel);

      listControllerStub = sinon.stub(listController, 'createNewItem', function() {
        listController.getItemList().addItem(newModel);
        $itemView.appendTo($listView);
        return newModel;
      });
      listController.getItemList = sinon.stub().returns(itemCollection);
      listController.setView($listView);
    });

    it('should return newly created model', function() {
      var newItem = listController.createNewItem();
      // loosely (duck-ly) verifying grocery-ls-item type.
      expect(newItem).toEqual(jasmine.any(Object));
      expect(newItem.hasOwnProperty('name')).toBe(true);
      expect(newItem.hasOwnProperty('id')).toBe(true);
      expect(newItem.id).not.toBeUndefined();
    });

    it('should add newly created item to collection', function() {
      var newItem = listController.createNewItem(),
          itemList = listController.getItemList();
      expect(itemList.itemLength()).not.toBe(0);
      expect(itemList.getItemAt(itemList.itemLength()-1)).toEqual(newItem);
    });

    it('should add new item controller to view', function() {
      listController.createNewItem();
      expect($listView.children().length).toBe(1);
    });

    afterEach( function() {
      $listView.empty();
      newModel = undefined;
      newItemController = undefined;
      itemCollection.removeAll();
      listController.createNewItem.restore();
    });

  });

});

First off, you may notice that we are pulling in, as dependencies, every component we have basically created up to this point. Then, within the beforeEach() of the spec suite, using SinonJS we stub out the redesign and addition(s) to the API of list-controller; we are redefining the functionality of createNewItem() (which currently exists on list-controller) to return a grocery-ls-item instance and stubbing the getItemList() method which will return the underlying collection model.

You may notice that i am using sinon.stub in two different ways:

listControllerStub = sinon.stub(listController, 'createNewItem', function() {

listController.getItemList = sinon.stub().returns(itemCollection);

The former allows for you to redefine the function invoked upon the public method – in this case ‘createNewItem‘. In order to properly define a stub in such a manner without being shown errors in executing the tests, the method must already be available on the object you are stubbing. The latter allows you to stub a method that is not currently on the object. As you may notice, the instantiation of the two different stubs are different in their assignment on the object being stubbed. The operations within these stubs shouldn’t be taken as set in stone – they may change once we get to implementation in list-controller – but they setup our expectations that will be verified in the specifications. The first of which ensures the return of a grocery-ls-item through property assertions:

/test/jasmine/spec/feature/newitem.spec.js

it('should return newly created model', function() {
  var newItem = listController.createNewItem();
  // loosely (duck-ly) verifying grocery-ls-item type.
  expect(newItem).toEqual(jasmine.any(Object));
  expect(newItem.hasOwnProperty('name')).toBe(true);
  expect(newItem.hasOwnProperty('id')).toBe(true);
  expect(newItem.id).not.toBeUndefined();
});

The second spec tests that the newly created item is added to the collection exposed on list-controller:
/test/jasmine/spec/feature/newitem.spec.js

it('should add newly created item to collection', function() {
  var newItem = listController.createNewItem(),
      itemList = listController.getItemList();
  expect(itemList.itemLength()).not.toBe(0);
  expect(itemList.getItemAt(itemList.itemLength()-1)).toEqual(newItem);
});

And the third spec… well, it starts to address some of the expectations a User may have when using the Grocery List application, something we really haven’t tested for as of yet – you have to start somewhere, though, right? We are testing that in addition to a new model added to the collection, there is an associated view in the UI (or at least presumably):
/test/jasmine/spec/feature/newitem.spec.js

it('should add new item controller to view', function() {
  listController.createNewItem();
  expect($listView.children().length).toBe(1);
});

I think we will start to see more of these type of tests as we start fleshing out the features more.

Actually, I have started taking steps in moving the separation of integration tests from feature tests, if you haven’t already noticed the update to the location of newitem.spec.js. In my mind, the difference is between what I consider tests of how a component behaves itself (and with others) and test which describe the actual use of the application, respectively.

Run the tests just as you have before with the updates to the feature spec locations:
/test/jasmine/specrunner.html

require( ['spec/feature/additem.spec.js', 'spec/feature/markitem.spec.js',
          'spec/item-controller.spec.js', 'spec/grocery-ls-item.spec.js',
          'spec/collection.spec.js'], function() {

  var jasmineEnv = jasmine.getEnv(),
       ...
  jasmineEnv.execute();

});

And all is green!

Tagged 0.1.7 – https://github.com/bustardcelly/grocery-ls/tree/0.1.7

list-controller Revisted

It’s great that the tests still pass, but we have yet to still modify list-controller. I can’t put it off any longer. If you have put up with the last couple posts and promises to get somewhere, you are very kind. The wait is over! … but it is also just the tip of the iceberg. sorry to be a downer

In looking at the API on list-controller we stubbed out from the beforeEach() of the newitem.spec and the expectations of its functionality verified in the specs, we are basically boiling down the responsibilities of the list-controller to:

• Create a new item
• Add item views to a provided element
• Manage and respond to changes on a collection of grocery-ls-item

As a start, we can include the new dependencies and refactor the list-controller component to support these requirements:
/script/controller/list-controller.js

define(['jquery', 'script/controller/list-item-controller', 'script/collection/collection', 'script/model/grocery-ls-item'],
        function($, itemControllerFactory, collectionFactory, modelFactory) {

  var collection = collectionFactory.create(),
      listController = {
        $view: undefined,
        getItemList: function() {
          return collection;
        },
        createNewItem: function() {
          var model = modelFactory.create();
          collection.addItem(model);
          return model;
        },
        setView: function(view) {
          this.$view = (view instanceof $) ? view : $(view);
        }
      };

  return listController;

});

Differing from the stub created for createNewItem() in the newitem.spec, the list-controller is only concerned with updating the collection model here. This is because the change to the collection will drive updates to the UI and we don’t want to have the UI operations within the createNewItem() method – that will basically create a doubling-up of efforts. It will be the responsibility of this module to observe changes to the collection and update state. That is done by adding an event handler to collection-change and operating accordingly based on event kind:

/script/controller/list-controller.js

define(['jquery', 'script/controller/list-item-controller', 'script/collection/collection', 'script/model/grocery-ls-item'],
        function($, itemControllerFactory, collectionFactory, modelFactory) {

  var collection = collectionFactory.create(),
      listController = {
        $view: undefined,
        getItemList: function() {
          return collection;
        },
        createNewItem: function() {
          var model = modelFactory.create();
          collection.addItem(model);
          return model;
        },
        setView: function(view) {
          this.$view = (view instanceof $) ? view : $(view);
        }
      };

  (function assignCollectionHandlers($collection) {

    var EventKindEnum = collectionFactory.collectionEventKind;

    $collection.on('collection-change', function(event) {
      switch( event.kind ) {
        case EventKindEnum.ADD:
          var model = event.items.shift(),
              $itemView = $('<li>'),
              itemController = itemControllerFactory.create($itemView, model);

          $itemView.appendTo(listController.$view);
          itemController.state = itemControllerFactory.state.EDITABLE;
          break;
        case EventKindEnum.REMOVE:
          break;
        case EventKindEnum.RESET:
          break;
      }
    });

  }($(collection)));

  return listController;

});

We are calling an IIFE with the jQuery wrapped collection object and assigning an event handler to collection-change on the collection. Depending on the kind of collection-change event that has occurred, defined clauses with specified operations are entered – for the purposes of the current task and tests at hand, that is only the ADD event.

In the EventKindEnum.ADD switch..case you will see the UI modification, with the addition of the list item view and the editability state of its associated list-item-controller set to allow the User to edit the new item.

Now, with the implementation of the Add Item feature moved to list-controller, we can clean up our newitem.spec.js:
/test/jasmine/spec/feature/newitem.spec.js

define(['jquery', 'script/controller/list-controller'],
        function($, listController) {

  describe('New item creation from listController.createNewItem()', function() {

    var $listView = $('<ul/>');

    beforeEach( function() {
      listController.setView($listView);
    });

    it('should return newly created model', function() {
      var newItem = listController.createNewItem();
      // loosely (duck-ly) verifying grocery-ls-item type.
      expect(newItem).toEqual(jasmine.any(Object));
      expect(newItem.hasOwnProperty('name')).toBe(true);
      expect(newItem.hasOwnProperty('id')).toBe(true);
      expect(newItem.id).not.toBeUndefined();
    });

    it('should add newly created item to collection', function() {
      var newItem = listController.createNewItem(),
          itemList = listController.getItemList();
      expect(itemList.itemLength()).not.toBe(0);
      expect(itemList.getItemAt(itemList.itemLength()-1)).toEqual(newItem);
    });

    it('should add new item controller to view', function() {
      listController.createNewItem();
      expect($listView.children().length).toBe(1);
    });

    afterEach( function() {
      $listView.empty();
    });

  });

});

And we’ll modify the main application module to reflect the change to the list-controller now only governing over a list DOM element and not to manage events from the add button on the DOM:

/script/grocery-ls.js

(function(window, require) {

  require.config({
    baseUrl: ".",
    paths: {
      "lib": "./lib",
      "script": "./script",
      "jquery": "./lib/jquery-1.8.3.min"
    }
  });

  require( ['jquery', 'script/controller/list-controller', 'script/collection/collection'],
            function($, listController, collectionFactory) {

    listController.setView($('section.groceries ul'));
    $('section.groceries #add-item-button').on('click', function(event) {
      listController.createNewItem();
    });

  });

}(window, requirejs));

Run the tests… and it will fail! Yay!

wait, what?!

Actually, most will pass – including the newitem.spec tests. It is the markitem.spec tests that will fail. We have modified the list-controller to accomodate the changes to the Add Item feature, but have not addressed the Mark Off Item feature in our refactoring.

However, run the application and it will be just as usable as it was before – no change will be perceived by the end-user. The only thing that will change is now I have a nagging feeling knowing my tests are failing. Some naysayers may interject here and half-heartedly tell me to get rid of the tests, then. To them I say, ‘pfffft‘

I hate to see the tests in such a state, but this post is rather long as it is. Also, I like to joke that sometimes having failing tests to look at first thing in the morning is the best way to pick up from where you left off. I promise we’ll get these to go green in the next article of this series, and invite you to get them to pass if you are for it.

Tagged 0.1.8 – https://github.com/bustardcelly/grocery-ls/tree/0.1.8

Conclusion

We finally got around to refactoring the list-controller to relieve it of item model management and state. In the course of doing so, we created a Collection object that will serve as the model for the list-controller.

This post was a lengthy one, and I appreciate you sticking through my yackity-yack. I think we are in fine shape now to approach previously defined and new features, get our tests passing again, and finalize the Grocery List application… in as far as first iteration deliverables go

‘Til next time…

—

Link Dump

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

Introduction

In the previous article we developed a new feature for the Grocery List application: Mark Off Item. In the process of doing so, or at least when we went from the tests to implementation, we added more responsibility to the list-controller as it pertained to individual view and model items.

In this article, we are going to refactor out that responsibility into its own list-item-controller that will be responsible for managing the relationship of a list item view to a single grocery-ls-item model.

Refactoring

As it stands , I think the design of the list-controller is fine: exposing an API to modify the list. It’s the internals that are starting to bug me. If the current behaviour and responsibilities were all that was needed, I suppose we could walk away and feel confident about our application as is. However, in forward thinking other operations that could involve list items – such as deletion – I feel the responsibilities of the list-controller will quickly outgrow its intent.

I suppose, some would argue, that if the responsibilities of the list-controller grow to more operations that are tightly coupled with singular pieces of data, then we could just write more tests to verify its soundness. Not entirely a bad argument – i mean that is what we are trying to justify in this series, essentially. But it is not a 1:1 correlation of more tests to better design. It is preferred to separate concerns as much as possible in order to properly test. The maintenance of complex tests can be a bigger burden than the maintenance of complex code – so much so that testing stops all together.

list-item-controller

Before we dive in to creating a list-item-controller, let’s take a look at what concerns within list-controller we want to move out. Looking from the 0.1.3 tagged list-controller, we mainly want to cut out the item view creation – so the following node declarations and any associated item creation and item management:

/script/controller/list-controller.js tagged at 0.1.3

itemFragment          = '<li class="grocery-item" />',
editableItemFragment  = '<li class="editable-grocery-item">' +
                                           '<input id="editableItem" name="editableItem" ' +
                                               'class="editable-item" placeholder="Enter item name...">' +
                                          '</input>' +
                                        '</li>'

These declarations and management of view will be moved to the list-item-controller. The UI and usability of a list item will be driven by the model and should provide an API that is a level of abstraction from the model for any outside parties (ie, the list-controller). As well, the model drives the internal state of edit-ability and marked-off-ed-ness (they’re words, alright!), and the list-item-controller will dispatch events related to its change of state. Lofty goals, but let’s see if we can’t address them.

a bit of uncertainty

We currently created specs for Add Item and Mark Off Item features. These were a little high-level in that they described features using the BDD syntax of Jasmine but did involve tests around how to interact with the list-controller API; so they do involve integration to some respect – we kind of ignore the whole UI and User Interaction aspect within the tests.

Now here is where I have an internal struggle with writing specs: should the tests we need for the list-item-controller be added to these specs? Or should a new spec focused on list-item-controller API and usability be born? I ask, because from outside-looking-in, the creation, editability and mark-off of an item will still be feasible through the list-controller and to any other third parties – that API provides a facade to modifying a grocery list. So, the current specs we have serve as a nice example of how to interact with the application from the outside… and if they are passing, we know that from higher-level things should* work

When we get down to the implementation of the list-item-controller, from a design perspective we know that a dependency will be introduced: list-controller will have n-number of list-item-controller instances, and will be responsible for the creation and maintenance of each list-item-controller. The state and grocery-ls-item model maintenance which we established in the previous articles as the responsibility of the list-controller will, as well, become the responsibility of the list-item-controller.

Knowing this, I start to feel that this is closer to testing the implementation and behaviour of a component, rather then one of the ’system’, and would push for its own spec. But I am very much open to ideas, so please leave a comment.

list-item-controller design

In my bit of uncertainty, I basically described the design of the list-item-controller. Now, we’ll flesh out its behaviour and API in a spec and eventually move it to its own AMD implementation. To start out slowly we’ll create a new spec suite and define the list-item-controller attributes:

/test/jasmine/spec/list-item-controller.spec.js

define(['jquery', 'script/model/grocery-ls-item'], function($, modelFactory) {

  describe('list-item-controller', function() {

    function createStateEvent(oldState, newState) {
        var event = new $.Event('state-change');
        event.oldState = oldState;
        event.newState = newState;
        return event;
    }

    var itemControllerFactory = {
        create: function(node, model) {
          var itemController = Object.create(Object.prototype);

          (function(controller, stateEventCreator) {
            var _state = 'normal';
            Object.defineProperties(controller, {
              "model": {
                value: model,
                writable: false,
                enumerable: true
              },
              "parentView": {
                value: node,
                writable: false,
                enumerable: true
              },
              "state": {
                set: function(value) {
                  var event = stateEventCreator.call(this, this.state, value);
                  _state = value;
                  $(this).trigger(event);
                },
                get: function() {
                  return _state;
                }
              }
            });
          }(itemController, createStateEvent));

          return itemController;
        }
      };
  });
});

The object declared – itemControllerFactory – is a factory instance that will generate new instances of a list-item-controller. The factory pattern should be familiar to you if you look at the grocery-ls-item AMD we created in the second article in the series. When creating an instance of a list-item-controller, we have defined that a parent DOM node and a model should be passed in during creation, as can be seen in itemControllerFactory:create(). If we look at the defineProperties, we have also defined a few characteristics of the list-item-controller here. It has:

• Parent Node reference – DOM instance of which to modify view state.
• Model reference – Model of which the View is driven by.
• State – State of View within the DOM representing the Model.

We have designed the state property a little differently than you may have seen before, at least in this series. We declared the implicit getter/setters so as to keep track of state internally and dispatch an event of ’state-change’. By ‘internally‘, I mean I used an IIFE to enclose a ‘private‘ member storing state.

If you know of event-driven design – whether or not you are familiar with jQuery Events, which the state property employs – then this will look familiar. Essentially, we want to allow any client who wants to know about the change of state to a list-item-controller instance to be notified through an event of ’state-change’. This will become more apparent later on in development, but just keep in mind that it is the responsibility of the list-controller to maintain n-number of list-item-controllers; and part of that maintenance is being aware of each list-item-controller’s state – and since binding is not inherently available in JavaScript, and I don’t want to introduce any new libraries that could handle binding, listening on events is an easy way to go about tracking state. You feel adventurous enough, we can build a binding mechanism on top of this event system… just make sure it’s got tests

Tests

Before we begin creating the tests for the list-item-controller, you may be wondering where the feature stories and scenarios are. We could definitely define those, however – and of course, I can always be wrong – I feel those are more business-facing… well, stories at least. They are used to define some type of behaviour that is accepted as part of the software, with scenarios describing the various outcomes of a behaviour. Still valid for the case in hand of integrating the list-item-controller, but I tend to think this closer to testing on the implementation of behaviour. It’s a gray area to me, as well, if this all sounds confusing – I invite someone to step in and either clarify my understanding to set me straight.

Basically, our goal here is to verify the design and implementation of list-item-controller. If done properly this will pass, as well as the specs for the Add Item and Mark Off Item features we created in previous articles.

That said, let’s flesh out some tests that verify:

1. Factory generates unique instances of list-item-controller
2. Model is preserved and immutable on list-item-controller
3. State is mutable through implicit getter/setters
4. Change to state is dispatched

/test/jasmine/spec/list-item-controller.spec.js

describe('Grocery list-item-controller', function() {

  var model,
      newController,
      async = new AsyncSpec(this);

  beforeEach( function() {
    model = modelFactory.create();
    newController = itemControllerFactory.create(parentNode, model);
  });

  describe('list-item-controller factory creation', function() {

    it('should return a new instance of list-item-controller', function() {
      expect(newController).not.toBeUndefined();
    });

    it('should return unique instances of list-item-controllers', function() {
      var nextController = itemControllerFactory.create(parentNode, model);
      nextController.state = 'testing';
      expect(nextController).not.toBe(newController);
      expect(nextController.state).not.toBe(newController.state);
    });

  });

  describe('new list-item-controller instance', function() {

    it('should expose model provided in creation', function() {
      expect(newController.model).not.toBeUndefined();
      expect(newController.model).toBe(model);
    });

    it('should expose non-writable model', function() {
      var newModel = modelFactory.create();
      newController.model = newModel;
      expect(newController.model).not.toBe(newModel);
      expect(newController.model).toBe(model);
    });

  describe('list-item-controller notifies on state-change', function() {

    async.it('should provide old and new state values on state-change', function(done) {
      var previousState = newController.state,
          newState = 'editable';

      $(newController).on('state-change', function(event) {
        $(newController).off('state-change');

        expect(event.oldState).toBe(previousState);
        expect(event.newState).toBe(newState);
        expect(newController.state).toBe(newState);
        done();
      });
      newController.state = newState;
    });

  });

  });

  afterEach( function() {
    model = undefined;
    newController = undefined;
  });

});

The last spec declared, as you may notice, runs asynchronously in order to test the state notification:

async.it('should provide old and new state values on state-change', function(done) {

The AsyncSpec object comes from the jasmine.async library we’ve previously included in the specrunner page. By invoking the spec (it()) through an instance of AsyncSpec, the spec is suspended until either it fails or the done delegate method is invoked. Since notification of state change is event-based, we use it in the spec to verify that the list-item-controller does dispatch that event.

Add that spec to the list:
/test/jasmine/specrunner.html

require( ['spec/newitem.spec.js', 'spec/markitem.spec.js', 'spec/list-item-controller.spec.js'], function() {

  var jasmineEnv = jasmine.getEnv(),
     ...
  jasmineEnv.execute();

});

list-item-controller implementation

We’ve verified our design for the list-item-controller with passing tests, but we have yet to incorporate it into our system and offload the responsibilities (addressed earlier in this article) from the list-controller to it. Before we get there, however, let’s move the implementation of the list-item-controller (and the factory) out into its own AMD module. To start we’ll just move the itemControllerFactory declaration into a new file:

/script/controller/list-item-controller.js

define(['jquery'], function($) {

  function createStateEvent(oldState, newState) {
    var event = new $.Event('state-change');
    event.oldState = oldState;
    event.newState = newState;
    return event;
  }

  return {
    create: function(node, model) {
      var itemController = Object.create(Object.prototype);

      (function(controller, stateEventCreator) {
        var _state;
        Object.defineProperties(controller, {
          "model": {
            value: model,
            writable: false,
            enumerable: true
          },
          "parentView": {
            value: node,
            writable: false,
            enumerable: true
          },
          "state": {
            set: function(value) {
              var event = stateEventCreator.call(this, this.state, value);
              _state = value;
              $(this).trigger(event);
            },
            get: function() {
              return _state;
            }
          }
        });
      }(itemController, createStateEvent));

      return itemController.init();
    }
  };

});

With that in place, we could modify the list-item-controller.spec.js file to include the list-item-controller dependency for testing:

/test/jasmine/spec/list-item-controller.spec.js

define(['jquery', 'script/model/grocery-ls-item', 'script/controller/list-item-controller'],
          function($, modelFactory, itemControllerFactory) {
  // moved to script/controller/list-item-controller.js

  describe('Grocery list-item-controller', function() {
    ...
  });
});

And our tests still pass! But… we want to move all the view and item management out of list-controller and have that handled by a list-item-controller. So let’s transfer over those view fragments and flesh out the list-item-controller object that is generated from the factory:

/script/controller/list-item-controller.js

define(['jquery'], function($) {

  function createStateEvent(oldState, newState) {
    var event = new $.Event('state-change');
    event.oldState = oldState;
    event.newState = newState;
    return event;
  }

   var stateEnum = {
        UNEDITABLE: 0,
        EDITABLE: 1
      },
      uneditableItemFragment  = '<p class="grocery-item" />',
      editableItemFragment    = '<p class="editable-grocery-item">' +
                                                  '<input name="editableItem" ' +
                                                      'class="editable-item" placeholder="Enter item name...">' +
                                                  '</input>' +
                                               '</p>',
      listItemController = {
        $editableView: undefined,
        $uneditableView: undefined,
        init: function() {
          this.$editableView = $(editableItemFragment);
          this.$uneditableView = $(uneditableItemFragment);

          // default to undeditable state.
          this.state = stateEnum.UNEDITABLE;
          return this;
        }
      };

  return {
    state: stateEnum,
    create: function(node, model) {
      var itemController = Object.create(listItemController);

      (function(controller, stateEventCreator) {
        var _state = 'normal';
        Object.defineProperties(controller, {
          "model": {
            value: model,
            writable: false,
            enumerable: true
          },
          "parentView": {
            value: node,
            writable: false,
            enumerable: true
          },
          "state": {
            set: function(value) {
              var event = stateEventCreator.call(this, this.state, value);
              _state = value;
              $(this).trigger(event);
            },
            get: function() {
              return _state;
            }
          }
        });
      }(itemController, createStateEvent));

      return itemController.init();
    }
  };

});

The init() method of a new list-item-controller is invoked upon creation and return in order to define the view references and default state. The fragment declarations have changed slightly as well – the list item wrappers have been removed. Basically, even though the name suggest that the view will reside in a list, we don’t want to tie the idea that they need to be li DOM elements since they also have no concept of what type of DOM element the parentView is.

As it stands with our current work from the previous article, the list-controller was responsible for listening on UI events of a list item – such as ‘blur’ on input and ‘click’. It is the intent to relive the list-controller of such responsibility so we’ll transfer that over, as well:

/script/controller/list-item-controller.js

listItemController = {
  $editableView: undefined,
  $uneditableView: undefined,
  init: function() {
    this.$editableView = $(editableItemFragment);
    this.$uneditableView = $(uneditableItemFragment);

    // view handlers.
    this.$uneditableView.on('click', (function(controller) {
      return function(event) {
        var toggled = controller.$uneditableView.css('text-decoration') === 'line-through';
        controller.model.marked = !toggled;
      };
    }(this)));
    $('input', this.$editableView).on('blur', (function(controller) {
      return function(event) {
        controller.model.name = $(this).val();
        controller.state = stateEnum.UNEDITABLE;
      };
    }(this)));

    // default to undeditable state.
    this.state = stateEnum.UNEDITABLE;
    return this;
  }
};

Again, we are using an IIFE, and in this case to pass in a reference to the controller instance. I could have easily defined a new variable like

var self = this;

but that always makes me cry a little inside. Anyway, so we are listening on click of the uneditable view item in order to update value of the marked property on the model and we have assigned a blur handler on the input of the editable view item that updates the value of the name property of the model and flips the state. Now we have to respond to those changes

/script/controller/list-item-controller.js

init: function() {
  this.$editableView = $(editableItemFragment);
  this.$uneditableView = $(uneditableItemFragment);

  // view handlers.
  this.$uneditableView.on('click', (function(controller) {
    return function(event) {
      var toggled = controller.$uneditableView.css('text-decoration') === 'line-through';
      controller.model.marked = !toggled;
    };
  }(this)));
  $('input', this.$editableView).on('blur', (function(controller) {
    return function(event) {
      controller.model.name = $(this).val();
      controller.state = stateEnum.UNEDITABLE;
    };
  }(this)));
  // state & model handlers.
  $(this).on('state-change',  (function(controller) {
    return function(event) {
      handleStateChange.call(null, controller, event);
    };
  }(this)));
  $(this.model).on('property-change', (function(controller) {
    return function(event) {
      handlePropertyChange.call(null, controller, event);
    };
  }(this)));
  // default to undeditable state.
  this.state = stateEnum.UNEDITABLE;
  return this;
}

The handleStateChange delegate is responsible for updating the view based on a change to state: either EDITABLE or UNEDITABLE from the stateEnum object:

function handleStateChange(controller, event) {
  // remove state-based item.
  if( typeof event.oldState !== 'undefined') {
    if(event.oldState === stateEnum.UNEDITABLE) {
      controller.$uneditableView.detach();
    }
    else if(event.oldState === stateEnum.EDITABLE) {
      controller.$editableView.detach();
    }
  }
  // append state-based item.
  if(event.newState === stateEnum.UNEDITABLE) {
    controller.parentView.append(controller.$uneditableView);
  }
  else if(event.newState === stateEnum.EDITABLE) {
    var inputTimeout = setTimeout( function()  {
      clearTimeout(inputTimeout);
      $('input', controller.$editableView).focus();
    }, 100);
    controller.parentView.append(controller.$editableView);
  }
}

The handlePropertyChange delegate is responsible for updating the views based on the model property values:

function handlePropertyChange(controller, event) {
  if(event.property === "name") {
    // update view based on model change.
    $('input', controller.$editableView).val(controller.model.name);
    controller.$uneditableView.text(event.newValue);
  }
  else if(event.property === "marked") {
    // update view based on model change.
    controller.$uneditableView.css('text-decoration', (event.newValue) ? 'line-through' : 'none');
  }
}

That pretty much shores up the implementation for the list-item-controller taking on the responsibilities of view creation and management based on state and model updates. But running the tests from this point will fail. The reason being a change to design on the model.

grocery-ls-item Modification

One particular change to design introduced in the implementation for list-item-controller is response to ‘property-change’ event from the model. In our work up to this point, the grocery-ls-item is a basic object; we’ll use the same paradigm that we implemented for notification of state for the grocery-ls-item in order to respond to changes on model properties. Although a simple change, we need to first test our design before modifying the code for the grocery-ls-item. Lets create a new spec file for our model:

/test/jasmine/spec/grocery-ls-item.spec.js

define(['jquery', 'script/model/grocery-ls-item'], function($, modelFactory) {

  describe('Grocery grocery-ls-item model', function() {

    var model,
        name = 'grapes',
        async = new AsyncSpec(this);

    beforeEach( function() {
      model = modelFactory.create();
      model.name = name;
      model.marked = false;
    });

    describe('grocery-ls-item factory model creation', function() {

      it('should generate unique instances of model', function() {
        var newModel = modelFactory.create();
        expect(model).not.toBeUndefined();
        expect(newModel).not.toBeUndefined();
        expect(model).not.toBe(newModel);
      });

      async.it('should auto generate unique ids on models', function(done) {
        var newModel,
            creationTimeout;

        // Offload creation because ids are generated based on time.
        // This allows for timestamp to progess.
        creationTimeout = setTimeout(function() {
          clearTimeout(creationTimeout);
          newModel = modelFactory.create();
          expect(model.id).not.toBeUndefined();
          expect(typeof model.id).toBe('number');
          expect(model.id).not.toEqual(newModel.id);
          done();
        }, 100);
      });

    });

    describe('grocery-ls-item properties', function() {

      it('should contain an immutable id property, created at instantiation', function() {
        var newID = 1234567;
        model.id = newID;

        expect(model.id).not.toEqual(newID);
      });

    });

    describe('grocery-ls-item property change notification', function() {

      async.it('should notify with \'property-change\' upon change to name property', function(done) {
        var oldName = model.name,
            newName = 'apples';
        $(model).on('property-change', function(event) {
          expect(event.property).toEqual('name');
          expect(event.oldValue).toEqual(oldName);
          expect(event.newValue).toEqual(newName);
          $(model).off('property-change');
          done();
        });
        model.name = newName;
      });

      async.it('should notify with \'property-change\' upon change to marked property', function(done) {
        var oldValue = model.marked,
            newValue = true;
        $(model).on('property-change', function(event) {
          expect(event.property).toEqual('marked');
          expect(event.oldValue).toEqual(oldValue);
          expect(event.newValue).toEqual(newValue);
          $(model).off('property-change');
          done();
        });
        model.marked = newValue;
      });

    });

    afterEach( function() {
      model = undefined;
    });

  });

});

We have a few suites there to verify:

1. Model generation from factory produces unique items
2. Model property immutability for auto-assigned IDs
3. Event notification on property change

We add that to our spec runner:

require( ['spec/newitem.spec.js', 'spec/markitem.spec.js',
          'spec/item-controller.spec.js', 'spec/grocery-ls-item.spec.js'], function() {

  var jasmineEnv = jasmine.getEnv(),
     ...
  jasmineEnv.execute();

});

… and it fails. Whoopee! It’s supposed to. Now we just take the knowledge we know of wiring up event notification on state of the list-item-controller, and apply it to property-change on the model:

/script/model/grocery-ls-item.js

define(['jquery'], function($) {

  var propertyEvent = {
      create: function(property, oldValue, newValue) {
        var event = $.Event('property-change');
        event.property = property;
        event.oldValue = oldValue;
        event.newValue = newValue;
        return event;
      }
    },
    properties = function(id) {
      return {
        "id": {
          value: id,
          writable: false,
          enumerable: true
        },
        "name": {
          enumerable: true,
          set: function(value) {
            var oldValue = this._name;
            this._name = value;
            $(this).trigger(propertyEvent.create('name', oldValue, value));
          },
          get: function() {
            return this._name;
          }
        },
        "marked": {
          enumerable: true,
          set: function(value) {
            var oldValue = this._marked;
            this._marked = value;
            $(this).trigger(propertyEvent.create('marked', oldValue, value));
          },
          get: function() {
            return this._marked;
          }
        }
      };
    };

  return {
    create: function() {
      return Object.create(Object.prototype, properties(new Date().getTime()));
    }
  };

});

The modification to grocery-ls-item was perhaps our first introduction to writing failing tests due to a change in design prior to actually modifying the implementation. That feeling you’re feeling right now… that’s what makes this all worth it

Anyway… hold on to that feeling until the next post, because we are not done and it will go away quickly… just kidding

Tagged: 0.1.5 https://github.com/bustardcelly/grocery-ls/tree/0.1.5

Blinders

If you were to run the tests again… they still pass!

That is because we have not changed list-controller at all

Our list-item-controller.spec.js is happily oblivious to our recent additions and modifications, and the tests we wrote previously for the Add Item and Mark Off Item features still pass.

Before we just start chopping out and inserting code from list-controller, I want to go over the API and specs currently defined and see if they still hold water – meaning we might be able to cut some tests out. We might not. We might even add more… That’s what i plan to address in the next article of this series.

—

Link Dump

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
Immediately-Invoked Function Expression (IIFE) by Ben Alman
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

Introduction

In the previous article, I addressed adding the first feature to the Grocery List application: Add Item. Trying my best to adhere to the TDD/BDD philosophy, a story and a couple scenarios were drummed up prior to implementation development using language similar to that described in Dan Worth’s Introducing BDD article. Once passing, the code written within the test was moved to its own file(s) with dependencies updated in the specs and tests run again to confirm passing against the implementations.

I will take the same approach in adding a new feature in this article: Mark-Off Item.

I suspect, however, that I may actually end up creating stories for more of what can be considered integration. Since the last post, I stumbled upon a great blog from Chris Parsons that covers BDD (with a bend toward Cucumber), and in particular the article Cucumber: the integration test trap provided some great insight into the difference between acceptance and integration testing. In the previous article, I suppose more of what was done could be considered acceptance testing. Some implementation details are testing against in the Add-Item feature (for instance, the item API on the list-controller), but I sort of threw in extra code and UX/UI implementation details at the end just so I could make sure the code was actually usable in a real-life scenario. At the time, I felt that writing specs for the integration of features – what i consider more fine-grained in testing that an element is added to the DOM upon an API call – would muddle down the intent of this series. I might take back that assumption. That may lead to longer posts… you have been forewarned

Mark-Off Feature

There are basically 3 states to an item in the grocery store:

1. unpossessed
2. unpurchased
3. owned

Once owned… well it either gets eaten or is freed into the wild – through those seemingly impenetrable automatic doors of unpurchased state, into the world of natural lighting. As well, prior to own-ed-ship, the item is in limbo as to whether or not it can reach that state – it might be placed back on the shelf to be forever unpossessed again. (You don’t want me to go over the possessed state.) Not unlike the life a a loaf of bread in a store, so too are the states of the grocery list items of the Grocery List application.

By adding an item – the feature completed in the previous article – a User has essentially identified an item not in possession, with the end goal of being owned. As a User of the application, we want to be able to denote the item as being in possession, but not purchased. The unpurchased state will notify other Users of the list that it no longer needs to be obtained. However, it will still be allowed to be unmarked and back to unpossessed – say if someone got Miracle Whip mayo instead of Helmann’s (whole ‘nother argument).

So we have essentially defined the feature for this post in the series: being able to mark and unmark an item added to the grocery list.

// story
—
Story: Item is marked off on grocery list

In order to remember what items have already made it to the cart
As a grocery shopper
I want to mark an item as being attained on the grocery list.
—

Similarly, since the item will still be available from the Grocer List application and only considered marked off, we could write up another story of being able to unmark an item from the list. For brevity’s sake, I should probably do that and if we were actually incorporating DSLs and tools that would facilitate in BDD testing, I probably would. But for the sake of this article, we’ll leave that as an added scenario to this feature.

// spec
—
Scenario 1: Item is marked off on grocery list
Given a user has saved an item to the list
When she requests to mark off the item
Then the item is presented differently to the user, denoting in possession
And the item is not removed from the list
—

Okay. I’ll admit. The desired outcome from that scenario is a little vague. But the scenarios I am writing – as discussed before, after having read this article from Chris Parsons – are more loosely acceptance criteria. As a developer, it makes me squirm a little because I know there is much more that can be described in this scenario, especially as it pertains to UI and UX. Aspects such as those can be considered more as integration points and I may circle back for more scenarios involving more of what we, as developers, are affirming in our tests (ie, design and functionality).

Anyway, undoing as well:

// spec
—
Scenario 2: Item is un-marked off on grocery list
Given a user has saved an item to the list
And she has marked off an item
When she requests to un-mark off the item
Then the item is presented to the user as not being in possession
And the item is not removed from the list
—

Basically, we are defining an item of the Grocery List application as a toggle control. Now, I can sum that up in a tiny single sentence and wave my hand, but I think we will find that there is a lot more to that statement as we start writing our tests and ultimately will change the design of the application – fo the better, I hope!

Test

To start, the story in question and described above adds to the API of the list-controller we defined and created in the previous article. The list-controller will need to expose a way to mark off an item that is saved to the list, and a way to unmark an item that was previously marked. As I see it, that’s two new methods – let’s call them markOffItem and unmarkOffItem. Let’s flesh them out and their signatures in a new spec for this feature:

/test/jasmine/spec/markitem.spec.js

define(['script/controller/list-controller'], function(listController) {

  describe('User Requests to mark-off existing item', function() {

    var name = 'apples',
        savedItem,
        markOffSpy,
        unmarkOffSpy;

    beforeEach( function() {
      listController.createNewItem();
      listController.editFocusedItem(name);
      listController.saveFocusedItem();

      savedItem = listController.itemList[listController.itemList.length-1];

      markOffSpy = spyOn(listController, "markOffItem").andCallThrough();
      unmarkOffSpy = spyOn(listController, "unmarkOffItem").andCallThrough();
    });

    ...

    afterEach( function() {
      savedItem = undefined;
      markOffSpy.reset();
      unmarkOffSpy.reset();
      listController.itemList = [];
      listController.editableItem = undefined;
    });

  });

});

I wanted to start off this test example with just showing to setup and teardown for the feature as it introduces the concept of spies. The beforeEach() of the above specification suite starts off similarly to the other spec we created for the Add Item feature – create, edit and save an item on the list-controller. Following that, and specifically on line 17 and 18, we create spies for the API modifications we are making on the list-controller in order to add the Mark Off Item feature – markOffItem() and unmarkOffItem(). Spies, in as far as they are used in this instance, are essentially wrappers on a function that can record invocation calls and provide another API to facilitate in affirming expectations of how a method should be used. If you are unfamiliar with spies, both Jasmine and Sinon have some great documentation.

The spies are defined to “call through” to the function implementation on the list-controller, as well. This will allow for the benefit of recording invocation and defining expectations of the actual implementation. Before we get into the real implementation, let’s take a look at the first spec for this test – marking off an item:

/test/jasmine/spec/markitem.spec.js

    it('should denote item as being in possession', function() {
      var previouslySavedItem = savedItem,
          savedItemID = savedItem.id,
          savedItemSpy = sinon.spy();

      savedItemSpy(previouslySavedItem);
      listController.markOffItem(savedItemID);

      // spy expectations.
      expect(markOffSpy).toHaveBeenCalled();
      expect(markOffSpy).toHaveBeenCalledWith(savedItemID);

      // model expectations.
      expect(previouslySavedItem.hasOwnProperty('marked')).toBe(true);
      expect(previouslySavedItem.marked).toBe(true);
      // OR >
      sinon.assert.calledWith(savedItemSpy, sinon.match.hasOwn('marked', true));
    });

With this spec, we are affirming the signature of markOffItem() method on the list-controller, as well as revealing the need for modifications to the attributes on the model of a grocery list item. I wanted to highlight how the markOffSpy() is being used in expectations, and – though not technically needed – also maybe provide some intrigue (hopefully not confusion) in using spies from SinonJS as well.

The following expectations, taken from the above spec, facilitate more in describing how listController.markOffItem() is to be used in the application, particularly that the method should be called with only one argument and that being an ID of an item from the list :

  expect(markOffSpy).toHaveBeenCalled();
  expect(markOffSpy).toHaveBeenCalledWith(savedItemID);

Some may say that such expectations are superfluous, and in some ways I do agree. Essentially, this line already defines its usage:

  listController.markOffItem(savedItemID);

If the test didn’t cough at that line, that we can relatively assume the expectations called into question. To each his own, however. In fact, part of me thinks I should go even more overboard – ensuring only one argument was called, that it was of the same type as the id attribute on the model, etc. Anyway, after the expectations on the spy, we verify an update to the model on an attribute we have yet to define as well. From this test, we have defined it as being a boolean value and accessible on the marked property. I included a spy created using SinonJS as well, just to show off it’s capabilities and compare and contrast testing on the new attribute of the model:

var previouslySavedItem = savedItem,
      savedItemSpy = sinon.spy();
savedItemSpy(previouslySavedItem);
...
sinon.assert.calledWith(savedItemSpy, sinon.match.hasOwn('marked', true));

A spy is created on the model object, and after marking it off through the list-controller API, it is verified as being of type boolean and value of true using a sinon assert. Neat stuff. In this case, I probably would have just stuck with the Jasmine expectations, but I wanted to show you the power of SinonJS as it can provide a more robust testing API.

Rambling on. There’s still two other specifications we need to cover in this suite:

/test/jasmine/spec/markitem.spec.js

    it('should retain the item in the grocery list', function() {
      listController.markOffItem(savedItem.id);

      expect(listController.itemList.length).toBe(1);
      expect(listController.itemList.indexOf(savedItem)).toBe(0);
    });

    it('should have marked-off item available to unmark-off', function() {
      var previouslySavedItem = savedItem,
          savedItemID = savedItem.id;

      listController.markOffItem(savedItem.id);
      listController.unmarkOffItem(savedItem.id);

      // stubbed expectations.
      expect(unmarkOffSpy).toHaveBeenCalled();
      // model expectations.
      expect(previouslySavedItem.marked).not.toBe(true);
    });

These specs define the expectations of the list remaining unmodified when marking off an item, and that the model is updated appropriately when unmarking off an item through the list-controller API, respectively.

[note]
I am using Array.prototype.indexOf in the first spec from the previous example. That didn’t make an appearance until JavaScript 1.6 and as such is not implemented in some older browsers (i have no <3 for IE<9). As I mentioned in the first article of this series, I am taking for granted that the application will be viewed on modern browsers, and in particular modern mobile browsers.

Failing

If you added this spec to the spec runner like so:

/test/jasmine/specrunner.html

require( ['spec/newitem.spec.js', 'spec/markitem.spec.js'], function() {
  var jasmineEnv = jasmine.getEnv(),
       ...
  jasmineEnv.execute();
});

> it will fail. miserably. But that’s okay! That’s expected. Spies require an actual implementation on the object you are spying, and if you recall from the first spec described, we actually request a call through on the implementation in order to verify expected functionality.

Let’s get to the list-controller and grocery-ls-item model, as those are the two items addressed in the latest spec suite as needing modifications to pass.

Implementation

In our Mark Off Item spec suite, we identified two additions to the API of the list-controller. Those methods are:

• + markOffItem( itemID )
• + unmarkOffItem( itemID )

The first instinct is to just add these to the list-controller object and add an internal method that traverses the held itemList array to locate models that have the passed itemID value. Not a bad instinct, and something of the following would get the tests passing:

/script/controller/list-controller.js

markOffItem: function(itemID) {
  var item = findItemByID(itemID, this.itemList),
        renderer = findRendererByItem(item, $itemList.children());
  item.marked = true;
  $(renderer).css('text-decoration', 'line-through');
},
unmarkOffItem: function(itemID) {
  var item = findItemByID(itemID, this.itemList),
        renderer = findRendererByItem(item, $itemList.children());
  item.marked = false;
  $(renderer).css('text-decoration', 'none');
}

> where findByItemID() locates the model associated with the itemID within the itemList array and findRendererByItem() locates the DOM element associated with the model.

If you were to run that, the tests would pass. Well, technically, if you left that bit in there where a SinonJS spy was asserting on the model, it would not pass. But if you took that out, all green. Even without modifying the grocery-ls-item model… such is the dynamic nature of JavaScript. For brevities sake, let’s add the marked property to the Object.defineProperties object upon creation of a new model:

/script/model/grocery-ls-item.js

var properties = function(id) {
    return {
      "id": {
        value: id,
        writable: false,
        enumerable: true
      },
      "name": {
        value: '',
        writable: true,
        enumerable: true
      },
      "marked": {
        value: false,
        writable: true,
        enumerable: true
      }
    };
  };

Tagged: 0.1.3 https://github.com/bustardcelly/grocery-ls/tree/0.1.3

Before you leave!

I am not satisfied with the current state of the list-controller; it has far too much responsibility in managing list item renderers and models and lacks the finer details to properly keep the 1:1 relationship that renderers have to their models. We could just throw more code in there, more tests and let it grow into this gross beast, but I really think it is up for a good refactor.

So, that is what I have planned for the next article. We’ll refactor the list-controller to have less responsibility in managing each grocery-ls-item model and pass that off to a new list-item-controller. In fact, I already have started upon such a refactor and had included most of it in this article, but I felt it was getting too long (as usual) and taking away from the Mark Off Item feature presented here.

Until then, you have passing tests and a functioning Grocery List application to play with if you check it out of the repo.

—

Link Dump

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
Cucumber: the integration test trap by Crhis Parsons
Testing spies for Jasmine and Sinon
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async
the infamous eye-roller

Introduction

In the previous article, I covered the intent of developing a Test-Driven Grocery List application using Jasmine, the BDD testing framework for JavaScript.

In this article, I want to address a single User Story with a couple scenarios, using language similar to that describe in Dan Worth’s Introducing BDD article, that will describe the specifications and expectations of one piece of the Grocery List application: adding an item.

Requirements

Instead of starting with code and project setup, let’s take a bite off the requirements of the Grocery List application and discuss a single usability point to start with.

The intended use of the Grocery List application is to be able to add, check-off and delete items from a list. We’ll address the difference of checking-off items vs. deleting items in later posts, so for now we’ll be concerned with only adding an item. Let’s start with a simple story:

// story
—
Story: Item is added to grocery list

In order to remember what to pick up at the grocery store
As a grocery shopper
I want to add an item to a grocery list accessible when at the store.
—

With this story, we can define some specification for the application as far as User Requirements. Now, this is where I often have a struggle with my inner ‘lets-get-to-it!‘ developer attitude and I have to keep concrete implementations in check for a bit.

// spec
—
Scenario 1: Item added to list
Given a user requests to add an item to the list
And has provided a name for the item
When she requests to save the item
Then the list has grown by one item
And the list contains the item appended at the end
—

A pretty basic scenario. It is hard for me to not go overboard here and cover every single aspect and moving piece at this stage – ie, how does this all happen? What is involved upon the first request? What UI has changed? How is a name provided? Shouldn’t all these be defined as well? All good questions. In my head, this scenario can be broken out into a handful of other scenarios. But I have to stand back and say that this is the scenario that I consider to be the business requirement at hand. This can be read and agreed upon by a third-party who is unfamiliar with the technology that will fulfill this requirement. If I can prove that this expectation is met successfully, the implementation is a by-product and can have additional test if seen fit. We can also add another scenario to this:

// spec
—
Scenario 2: Item not added to list
Given the list has a single item
And a user requests to add an item to the list
And has not provided a name for the item
When she requests to save the item
Then the list has the same items as stored previously
And the list does not add an empty-named item
—

Now we are covering the requirements involved in adding an item to the Grocery List… and I always like to fill in a scenario of what it doesn’t do, because sometimes what it doesn’t do tells you more about what the system is supposed to do. Again, we can get exhaustive with UI and device event tests, but we don’t want to meddle down the specs at this point with concrete implementations.

What I do find interesting from just these basic scenarios is that it does reveal some aspects of the application that will need to be addressed while creating the tests – mainly, a starter on the grocery item model schema and the API in conversing with a view controller to add and edit an item.

design note

It should be noted that I do prefer the design concept of Supervising Presenter and will employ it within the tests and application, so you are forewarned If you are unfamiliar, a Supervising Presenter is knowledgable of the view and model and provides an API that allows for an outside party to affect each, but mostly in affecting the attributes on the model that are observed by the view. Consequently, it will also allow us to not worry to much about the view implementation and User-based events when resolving logical requirements. I don’t plan to incorporate any application framework that provides such a pattern, so a basic view controller (supervising presenter) will essentially be in charge of modifying the view and model in the Grocery List application that will be built.

Architecture, design patterns and the pros and cons of frameworks are things I am more than willing to discuss over beers I just wanted to give you a heads up.

Test

I suppose we should address some set-up as this is the first post. Jasmine tests are described in a JavaScript file related to a (typically, single) specification of the application requirements, and those specs are run in what is considered a spec-runner. The browser-based Jasmine library comes with support for reporting in an HTML document.

Here is an example of the specrunner.html from /test/jasmine directory of the github repo for grocery-ls:

<!DOCTYPE html">
<html>
  <head>
    <title>grocery-ls Spec Runner</title>
    <link rel="stylesheet" type="text/css" href="lib/jasmine-1.2.0/jasmine.css">
    <script src="../../lib/require-2.1.1.min.js"></script>
    <script src="lib/jasmine-1.2.0/jasmine.js"></script>
    <script src="lib/jasmine-1.2.0/jasmine-html.js"></script>
    <script src="lib/jasmine.async.min.js"></script>
    <script src="lib/sinon-1.5.0.js"></script>

    <script>
      (function( window, require ) {

        require.config({
          baseUrl: "../..",
          paths: {
            "spec": "./test/jasmine/spec",
            "script": "./script",
            "jquery": "./lib/jquery-1.8.3.min.js"
          }
        });

        require( ['spec/newitem.spec.js'], function() {

          var jasmineEnv = jasmine.getEnv(),
              htmlReporter = new jasmine.HtmlReporter();

          jasmineEnv.updateInterval = 1000;
          jasmineEnv.addReporter(htmlReporter);
          jasmineEnv.execute();

        });  

      }(window, requirejs));
    </script>

</head>
<body></body>
</html>

In the spec runner, we have included the library scripts described previously in the previous post. One thing to note, is the use of RequireJS. In order to support AMD, we instruct RequireJS to load the Jasmine specs defined in JavaScript files prior to setting the environment and executing the specs. Normally, when not incorporating RequireJS, you would just add the specs as script tags in the head. An important part of using RequireJS is setting the proper paths in the configuration. This allows RequireJS to find the proper dependencies not only in the spec itself, but in any concrete implementations separate from the specs. In this example we have set the baseURL to the root of the project directory and define the keyword “spec” as pointing to the Jasmine spec directory we have set up. If you checkout the project from the repo, the directory structure and the RequireJS configuration paths hopefully will make things clearer.

That’s just a quick introduction to the spec runner. I may not discuss it further in later posts aside from appending specs to the require() invocation. Without additional headless tooling (which may be covered later), when I run the tests I will simply load the spec runner in a browser.

New-Item Specifications

Back to the task at hand… we have to verify the adding of an item to our Grocery List. The make up of a spec file should be addressed, especially when incorporating RequireJS in our application and tests. We need to start off with a define(), which is a RequireJS method to define an AMD module – what we are loading from the spec runner are Jasmine spec modules, essentially. Within the Jasmine spec file itself, we will be primarily concerned with 3 methods:

• describe : encapsulates a suite of specifications
• it : defines a specification
• expect : executes a test against matchers that verify expectations

That list is hierarchical – expectations are defined in a suite of specifications. I will start off using the basic matchers that come with Jasmine, but may cover creating custom ones if need be while I develop the Grocery List application. It is also important to note that suites can be nested and Jasmine is knowledgable enough to execute the tree of specifications appropriately.

Along with those methods that involve expectations of a suite of specifications, there are also two helper methods that I will employ often: beforeEach() and afterEach(). If you are already familiar with unit testing, these are the setup and teardown methods and will be executed before and after each specification, respectively. They aide in performing common tasks across a suite of specifications that basically setup and teardown dependencies for expectations.

Again all of this is a basic overview to actually get to the spec file itself. Definitely checkout the Jasmine documentation for finer detail.

Failing

With this knowledge, we can create a basic skeleton of the spec file to cover the scenarios described before:
/test/jasmine/spec/newitem.spec.js

define( function() {

  describe('User requests to add new item', function() {

    it('should save new item when name supplied', function() {
        expect(false).toBe(true);
    });

    it('should not save new item when name not supplied', function() {
        expect(false).toBe(true);
    });

  });

});

This spec encompasses the story and specifications we defined previously in this post, and has two failing expectations – typically, when setting up a suite of specifications and just defining specifications that I will return to in order to complete, I throw in a failing expectation. We are describing our ‘add item to grocery list’ story with the two specifications: 1) allowing an item to be added that has a valid name and 2) not allowing an item to be added without a valid name.

Now, just working through the employment of a view controller/presenter and the API to expose in order to properly define the requirement of adding an item to the list in the specification, we can come to a handful of requirements in order to successfully fulfill these specs:

• A grocery item model that exposes a “name” property
• A list view controller/presenter that exposes an API to:

• add/create a new item
• modify a newly added/created item
• save an item to the list

Additionally, we will want to run the request to add at least one item to the list in order to meet expectations in each specification defined. As such, and without any concrete implementations or stubs, we can modify the spec to include the setup and teardown of the controller that will get us to the expectations of the spec:

/test/jasmine/spec/newitem.spec.js

describe('User requests to add new item', function() {

    var listController = {
              editableItem: undefined,
              itemList: []
          };

    beforeEach( function() {
      listController.createNewItem();
      listController.editFocusedItem('apples');
      listController.saveFocusedItem();
    });

    it('should save new item when name supplied', function() {
      expect(false).toBe(true);
    });

    it('should not save new item when name not supplied', function() {
      expect(false).toBe(true);
    });

    afterEach( function() {
      listController.itemList = [];
      listController.editableItem = undefined;
    });

  });

Before each spec is entered, the list controller is requested to create a new item, modify it and save it to the list. After each spec, reference to the newly created item is returned to an undefined value and the list is emptied. All this will fail if you run it – even before getting to the specifications; the listController variable only exposes the item and list properties and does not provide the API we have defined in the beforeEach() method.

Now we could go about stubbing the listController out with an API, like such:

sinon.stub(listController, "createNewItem", function() {
    listController.editableItem = {};
});

… but, in instances like such, I’d rather just modify the object directly and then move the implementation to its own AMD module. We will get into stubbing and mocking in later posts – as it is very useful – but for now, to keep things a little more simpler, I will define the makeup of the listController on itself directly:

/test/jasmine/spec/newitem.spec.js

var itemProperties = function(id) {
      return {
        "id": {
          value: id,
          writable: false,
          enumerable: true
        },
        "name": {
          value: '',
          writable: true,
          enumerable: true
        }
      };
    },
    listController = {
      itemList: [],
      editableItem: undefined,
      createNewItem: function() {
        this.editableItem = Object.create(Object.prototype, itemProperties(new Date().getTime()));
      },
      editFocusedItem: function(name) {
        this.editableItem.name = name;
      },
      saveFocusedItem: function() {
        if( this.editableItem.name.length !== 0 ) {
          this.itemList.push(this.editableItem);
        }
        this.editableItem = undefined;
      }
    };

The listController now exposes the methods for creation, edit and save of an item and internally updates the property values of itemList and editableItem. As well, you will notice how a new item is generated using the Object.create() method and supplying a defineProperties object with an immutable “id” property and a mutable “name” property. With the listController fleshed out a bit more, we can return to the specs and defined some expectations. Remembering that we instruct the listController to create, modify and save an item to the list in the beforeEach() method fo the spec suite, we can modify the first spec that pertains to the successful add of an item:

/test/jasmine/spec/newitem.spec.js

    it('should save new item when name supplied', function() {
      expect(listController.itemList.length).toBe(1);
      expect(listController.itemList[0]).not.toBe(undefined);
      expect(listController.itemList[0].hasOwnProperty('name')).toBe(true);
      expect(listController.itemList[0].name).toBe('apples');
    });

It can be debated about the number of expectations per spec and whether each expectation should be split into their respective spec. I see pros and cons with both styles, but I mainly strive to keep “noise” to a minimum in my tests – meaning i will sacrifice listing a handful of expectations around a single specification in order for the progression and specification suite to be more “readable”. In this case, I am just verifying that an item has been added and retained by the list exposed on listController, and that the item that resides in the list matches that which was added.

Likewise, to complete the other specification of not being able to add an item that does not have an name attributed to it:
/test/jasmine/spec/newitem.spec.js

    it('should not save new item when name not supplied', function() {
      listController.createNewItem();
      listController.saveFocusedItem();
      expect(listController.itemList.length).toBe(1);
      expect(listController.itemList[0].name).toBe('apples');
    });

In this specification, we are requesting to create and save a new item through the listController API. Remembering that an item has already been added from the beforeEach() method, after the saveFocusedItem() request, the list should only contain the item added previously.

Passing

If we ran the spec runner, we would see our specifications pass:

Whoopee! The following is the whole spec file:

/test/jasmine/spec/newitem.spec.js

define( function() {

  var itemProperties = function(id) {
        return {
          "id": {
            value: id,
            writable: false,
            enumerable: true
          },
          "name": {
            value: '',
            writable: true,
            enumerable: true
          }
        };
      },
      listController = {
        itemList: [],
        editableItem: undefined,
        createNewItem: function() {
          this.editableItem = Object.create(Object.prototype, itemProperties(new Date().getTime()));
        },
        editFocusedItem: function(name) {
          this.editableItem.name = name;
        },
        saveFocusedItem: function() {
          if( this.editableItem.name.length !== 0 ) {
            this.itemList.push(this.editableItem);
          }
          this.editableItem = undefined;
        }
      },
      itemName = 'apples';

  describe('List Controller creates a new item', function() {

    beforeEach( function() {
      listController.createNewItem();
    });

    it('should expose the editableItem upon creation', function() {
      var createdItem = listController.editableItem;
      expect(createdItem).not.toBeUndefined();
      expect(typeof createdItem.name).toBe('string');
      expect(createdItem.name.length).toBe(0);
    });

    afterEach( function() {
      listController.editableItem = undefined;
    });

  });

  describe('User requests to add new item', function() {

    beforeEach( function() {
      listController.createNewItem();
      listController.editFocusedItem(itemName);
      listController.saveFocusedItem();
    });

    it('should save new item when name supplied', function() {
      expect(listController.itemList.length).toBe(1);
      expect(listController.itemList[0]).not.toBe(undefined);
      expect(listController.itemList[0].hasOwnProperty('name')).toBe(true);
      expect(listController.itemList[0].name).toBe(itemName);
    });

    it('should not save new item when name not supplied', function() {
      listController.createNewItem();
      listController.saveFocusedItem();
      expect(listController.itemList.length).toBe(1);
      expect(listController.itemList[0].name).toBe(itemName);
    });

    afterEach( function() {
      listController.itemList = [];
      listController.editableItem = undefined;
    });

  });

});

You may notice that I snuck in another little specification revolved around the creation and exposure of a new item through the listController – that is because I am anal and additionally wanted to ensure that the listController responded properly as I saw fit upon creation of a new item.

Of course, at this point the design of the controller can be debated – and it is a much welcome discussion. I setup listController as it is with the following requirements:

• View implementation is abstracted away. In fact there is absolutely no communication with the DOM to make these specifications pass. It will be the controller’s responsibility on how the view is updated based on the exposed API.
• Only one item will be editable at any given time within the application session. This may be later determined as an oversight, but that is the requirement I have set at the moment… and if we need multiple editable items, we’ll modify our tests and refactor!
• The list of items is accessible and mutable on the controller. This is a requirement that will likely change as the addition and removal of items will have some impact on the supervised view, likely leading to the an API to modify the list replacing the direct access.

Tagged 0.1.0: https://github.com/bustardcelly/grocery-ls/tree/0.1.0

Implementation

Typically, after having passed specifications, I like to move the work to actual implementations of the application. It is similar to the concept of TDD like you mean it, but I don’t think I strictly adhere to that principle. In any event, we can move the implementation of the listController from the newitem.spec to its own AMD module define that as a dependency for our spec.

Very simply, we could rip the object declarations from newitem.spec.js and drop them into a new AMD module and define the listController export for dependency reference in the spec:

/script/controller/list-controller.js

define(function() {
  var itemProperties = function(id) {
        return {
          "id": {
            value: id,
            writable: false,
            enumerable: true
          },
          "name": {
            value: '',
            writable: true,
            enumerable: true
          }
        };
      },
      listController = {
        itemList: [],
        editableItem: undefined,
        createNewItem: function() {
          this.editableItem = Object.create(Object.prototype, itemProperties(new Date().getTime()));
        },
        editFocusedItem: function(name) {
          this.editableItem.name = name;
        },
        saveFocusedItem: function() {
          if( this.editableItem.name.length !== 0 ) {
            this.itemList.push(this.editableItem);
          }
          this.editableItem = undefined;
        }
      };

  return listController;
});

/test/jasmine/spec/newitem.spec.js

define( ['script/controller/list-controller'], function(listController) {

  var itemName = 'apples';

  describe('List Controller creates a new item', function() {

    beforeEach( function() {
      listController.createNewItem();
    });

    it('should expose the editableItem upon creation', function() {
      expect(listController.editableItem).not.toBeUndefined();
    });

    afterEach( function() {
      listController.editableItem = undefined;
    });

  });

  describe('User requests to add new item', function() {

    beforeEach( function() {
      listController.createNewItem();
      listController.editFocusedItem(itemName);
      listController.saveFocusedItem();
    });

    it('should save new item when name supplied', function() {
      expect(listController.itemList.length).toBe(1);
      expect(listController.itemList[0]).not.toBe(undefined);
      expect(listController.itemList[0].hasOwnProperty('name')).toBe(true);
      expect(listController.itemList[0].name).toBe(itemName);
    });

    it('should not save new item when name not supplied', function() {
      listController.createNewItem();
      listController.saveFocusedItem();
      expect(listController.itemList.length).toBe(1);
      expect(listController.itemList[0].name).toBe(itemName);
    });

    afterEach( function() {
      listController.itemList = [];
      listController.editableItem = undefined;
    });

  });

});

In the modified newitem.spec.js, we have defined the dependency on the list-controller module which is then referenced using listController. Running that will result in the same successful expectations as before. You may notice that the dependency for the listController is defined as ’script/controller/list-controller’. The ’script’ directory is defined in the RequireJS configuration in the spec runner file discussed previously in this post – it will know how to resolve its location and load the controller file.

Now is where, typically, as modifications to list-controller are made in response to new requirements and specifications, stubbing comes into play within my specs more. If an addition or change to the API of list-controller is required for a new story, then in the specification test I would implement that API using stubs, then move the implementation to the list-controller module once they pass.

Tagged, 0.1.1: https://github.com/bustardcelly/grocery-ls/tree/0.1.1

Usability

Because I can’t leave well-enough alone, I want to hook up this functionality to User response

Available in the repo at the current revision up to this point (tagged 0.1.1), there is a main index file that I have not addressed in this post:

/index.html

<!DOCTYPE html>
<html>
  <head>
    <title>grocery-ls</title>
  </head>
  <body>
    <header>
      <h1>grocery-ls</h1>
    </header>
    <section class="groceries">
      <ul class="grocery-list"></ul>
      <button id="add-item-button">add item</button>
    </section>
    <script src="lib/require-2.1.1.min.js"></script>
    <script src="script/grocery-ls.js"></script>
  </body>
</html>

The page just defines an unordered list to display grocery items (editable & uneditable) and a button to add an item to the list. As well, we have included the RequireJS library and a main JS file for the Grocery List application:

/script/grocery-ls.js

(function(window, require) {

  require.config({
    baseUrl: ".",
    paths: {
      "lib": "./lib",
      "script": "./script",
      "jquery": "./lib/jquery-1.8.3.min"
    }
  });

  require( ['jquery', 'script/controller/list-controller'], function($, listController) {
    listController.setView($('section.groceries'));
  });

}(window, requirejs));

The configuration paths, you are familiar with when we set up the specrunner for our Jasmine tests. Additionally, we are asking RequireJS to load the ‘jquery‘ and ‘list-controller‘ dependencies, after which, the list-controller is given a reference to the DOM element it will supervise: the section element with the class attribute value of ‘groceries‘.

The list-controller will now have more responsibility in updating the view based on invocations of the API we have previously defined for our specifications:

/script/controller/list-controller.js

define(['jquery', 'script/model/grocery-ls-item'], function($, itemModel) {

  var $view,
      $item,
      $itemList,
      itemFragment              = '<li class="grocery-item" />',
      editableItemFragment  = '<li class="editable-grocery-item">' +
                                '<input id="editableItem" name="editableItem" ' +
                                  'class="editable-item" placeholder="Enter item name...">' +
                                '</input>' +
                              '</li>',
      findItemList = function() {
        if( typeof $itemList === 'undefined' ) {
          $itemList = $('.grocery-list', $view);
        }
        return $itemList;
      },
      listController = {
        itemList: [],
        editableItem: undefined,
        setView: function(value) {
          var controller = this;
          $view = $(value);
          $('#add-item-button', this.$view).on( 'click', function(event) {
            controller.createNewItem();
          });
        },
        createNewItem: function() {
          var $list = findItemList(),
              $input,
              controller = this;

          this.editableItem = itemModel.create();
          $item = $(editableItemFragment);
          $input = $('input', $item);
          $input.first().bind( 'blur', function(event) {
            var $this = $(this);

            $this.unbind('blur');
            controller.editFocusedItem( $this.val() );
            controller.saveFocusedItem();
          });

          $item.data('gls-item', this.editableItem);
          $list.append($item);
          $input.first().focus();
        },
        editFocusedItem: function(name) {
          this.editableItem.name = name;
        },
        saveFocusedItem: function() {
          var $list = findItemList();
              $itemFragment = $(itemFragment);

          $item.remove();
          if( this.editableItem.name.length > 0 ) {
            $itemFragment.append('p').text(this.editableItem.name);
            $itemFragment.data('gls-item', this.editableItem);
            $list.append($itemFragment);
            this.itemList.push(this.editableItem);
          }
          this.editableItem = undefined;
        }
      };

  return listController;

});

/script/model/grocery-ls-item.js

define(function() {

  var properties = function(id) {
    return {
      "id": {
        value: id,
        writable: false,
        enumerable: true
      },
      "name": {
        value: '',
        writable: true,
        enumerable: true
      }
    };
  };

  return {
    create: function() {
      return Object.create(Object.prototype, properties(new Date().getTime()));
    }
  };

});

The modifications to the list-controller from it’s previous implementation mainly involve access and modification of the DOM in response to requests on its API. If we ran the Jasmine spec we previously created – newitem.spec.js – it would still pass. If the main index.html file is loaded in a browser, you will be able to add an item by clicking the button and as long as you provide a name in the input field, it will be added to the list.

We could (and perhaps some readers would say that I should have) created more specs that defined the usability and expectations of DOM manipulation on response to API invocations on the list-controller. It is a valid point and I totally agree. At this point I don’t want to add noise with the user interface implementations in the specifications; the view implementation is subject to change and the API on the list-controller currently supports the modification of the grocery list. We can be assured at the current moment that the list-controller knows how to manage the list and we should not worry about what User impetus invokes the API.

Perhaps in later posts I will see the error of my ways in letting this go…

Tagged, 0.1.2: https://github.com/bustardcelly/grocery-ls/tree/0.1.2

Conclusion

We went through the first story, scenarios and specifications of the Grocery List application that will be built throughout this series. A tonne of information was covered and if you stayed with me, I appreciate it. In the end we have a passing spec suite for the creation and add of a grocery item through a list view controller. We moved the implementation of the controller and model from the spec to their respective AMD modules and allowed for user interaction with the application to perform the creation and add operations.

Thanks for sticking around. I hope this series proves to be helpful in some way.

—-

Link Dump

Post Series

grocery-ls github repo
Part I – Introduction
Part II – Feature: Add Item
Part III – Feature: Mark-Off Item
Part IV – Feature: List-Item-Controller
Part V – Feature: List-Controller Refactoring
Part VI – Back to Passing
Part VII – Remove Item
Part VIII – Bug Fixing
Part IX – Persistence
Part X – It Lives!

Reference

Test-Driven JavaScript Development by Christian Johansen
Introducing BDD by Dan North
TDD as if you Meant it by Keith Braithwaite
RequireJS
AMD
Jasmine
Sinon
Jasmine.Async