feat(counterfeit): add api for creating promises and stubs

A factory called `counterfeit` has been added. This factory facilitates
the testing of methods that use asynchronous promises, by providing an
api to generate fake promises and stub functions that return a promise.

An integration test has been added for the `DeathStar` test fixture.
Within this test the `DeflectorShield` class is decorated so that the
`reboot` method is a `CounterfeitStub`. This stub is configured to
return a `CounterfeitPromise`, which can be conveniently resolved within
the test.

Behind the scenes `CounterfeitPromise` are built using the AngularJs
`$q` service.

Gruntfile.js

@@ -8,15 +8,15 @@ module.exports = function (grunt) {
 
     concat: {
       basic: {
-        src: ['src/counterfeit.js'],
+        src: ['src/counterfeit.js', 'src/promise.js', 'src/stub.js', 'src/counterfeit_fac.js'],
         dest: 'dist/counterfeit.js'
       }
     },
 
     uglify: {
       basic: {
         files: {
-          'dist/counterfeit.min.js': ['src/counterfeit.js']
+          'dist/counterfeit.min.js': ['src/counterfeit.js', 'src/promise.js', 'src/stub.js', 'src/counterfeit_fac.js']
         }
       }
     },

src/counterfeit_fac.js

@@ -0,0 +1,11 @@
+counterfeit.factory("counterfeit", function(CounterfeitPromise, CounterfeitStub) {
+  return {
+    promise: function () {
+      return CounterfeitPromise.create();
+    },
+
+    stub: function(promise) {
+      return CounterfeitStub.create(promise);
+    }
+  }
+});

src/promise.js

@@ -0,0 +1,38 @@
+counterfeit.factory("CounterfeitPromise", function() {
+  var $timeout, $q;
+
+  function CounterfeitPromise() {
+    this._injectDependecies();
+    this.reset();
+  }
+
+  // Public
+  // ------------------------------
+  CounterfeitPromise.prototype.resolve = function(value) {
+    this._complete(this.deferred.resolve, value);
+  };
+
+  CounterfeitPromise.prototype.reset = function() {
+    this.deferred = $q.defer();
+    return this.deferred.promise;
+  };
+  // ------------------------------
+
+  CounterfeitPromise.prototype._injectDependecies = function() {
+    inject(function(_$q_, _$timeout_) {
+      $q = _$q_;
+      $timeout = _$timeout_;
+    });
+  };
+
+  CounterfeitPromise.prototype._complete = function(fn, value) {
+    $timeout(function(){fn(value);});
+    $timeout.flush();
+  };
+
+  return {
+    create: function () {
+      return new CounterfeitPromise();
+    }
+  }
+});

src/stub.js

@@ -0,0 +1,13 @@
+counterfeit.service("CounterfeitStub", function() {
+  return {
+    create: function(promise) {
+      var p = promise.reset();
+
+      return function() {
+        return {
+          $promise: p
+        }
+      };
+    }
+  };
+});

test/counterfeit_spec.js

@@ -31,4 +31,41 @@
     }
   });
 
+  describe('DeathStar', function() {
+    var counterfeit, promise, deathStar;
+
+    beforeEach(function() {
+      module("counterfeit");
+      module("starWars");
+
+      module(function($provide) {
+        $provide.decorator("DeflectorShield", function($delegate) {
+          $delegate.reboot = counterfeit.stub(promise);
+          return $delegate;
+        });
+      });
+
+      inject(function(_counterfeit_) {
+        counterfeit = _counterfeit_;
+        promise = counterfeit.promise();
+      })
+
+      // DeathStar has to be injected after counterfeit and promise have
+      // been setup to ensure that all the dependencies are available
+      // for the decoration of DeflectorShield
+      inject(function(DeathStar) {
+        deathStar = DeathStar;
+      });
+    });
+
+    describe("#rebootDeflectorShield", function() {
+      describe("when successfully rebooted", function() {
+        it("sets shield status", function() {
+          deathStar.rebootDeflectorShield();
+          promise.resolve("All systems are operational");
+          expect(deathStar.shieldStatus()).to.eql("All systems are operational");
+        });
+      });
+    });
+  });
 })(chai.expect, describe, it, angular, sinon);