mattfreer/counterfeit

An AngularJS module, that provides test doubles for asynchronous promises.

Counterfeit

Counterfeit is an AngularJS module, that provides test doubles for asynchronous promises.

This library facilitates the stubbing of functions that return promises. Providing users with easy access to resolve/reject fake promises.

Installation

Install the module via npm

$ npm install counterfeit --save-dev

If you are using the Karma test runner then you will need to add counterfeit to the files list in your Karma configuration:

module.exports = function(config) {
  config.set({
    files: [
      'node_modules/counterfeit/dist/counterfeit.js'
    ],

    ...
  });
}

Example Usage

To demonstrate how counterfeit can be used to facilitate testing, consider the following AngularJS module called starWars:

var starWars = angular.module("starWars", ["ngResource"]);

starWars.service('DeflectorShield', function($resource) {
  return $resource({}, null, {
    "reboot": {
      method: "PUT",
      url: "/starwars/deflector_shield/reboot"
    }
  });
});

starWars.factory('DeathStar', function(DeflectorShield) {
  var status, shieldStatus;

  shieldStatus = function(msg) {
    status = msg;
  };

  return {
    rebootDeflectorShield: function() {
      DeflectorShield.reboot().$promise.then(
        shieldStatus, shieldStatus, shieldStatus);
    },

    shieldStatus: function() {
      return status;
    },
  }
});

As can be seen the DeathStar factory uses the DeflectorShield service, that exposes one public method called reboot. This method returns a promise. This presents a challenge for the testing of the DeathStar factory because the rebootDeflectorShield method relies upon an asynchronous operation that returns a promise.

In order to test the functionality of DeathStar.rebootDeflectorShield we need a way of controlling when the promise returned from DeflectorShield.reboot is resolved/rejected. This is where counterfeit comes into play.

The following DeathStar test (using mocha, chai and sinon) is setup to decorate the DeflectorShield service so that the reboot method is a CounterfeitStub. This stub is configured to return a CounterfeitPromise, which can be conveniently resolved within the test, allowing assertions to be made against DeathStar behaviour that is asynchronous.

describe('DeathStar', function() {
  var promise, deathStar;

  beforeEach(function() {
    module("counterfeit");
    module("starWars");

    module(function($provide) {
      $provide.decorator("DeflectorShield", function($delegate, counterfeit) {
        promise = counterfeit.promise();
        $delegate.reboot = counterfeit.stub(promise);
        return $delegate;
      });
    });

    inject(function(DeathStar) {
      deathStar = DeathStar;
    });
  });

  describe("#rebootDeflectorShield", function() {
    describe("when reboot in progress", function() {
      it("sets shield status", function() {
        deathStar.rebootDeflectorShield();
        promise.notify("Shield rebooting");
        expect(deathStar.shieldStatus()).to.eql("Shield rebooting");
      });
    });

    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");
      });
    });

    describe("when reboot fails", function() {
      it("sets shield status", function() {
        deathStar.rebootDeflectorShield();
        promise.reject("Shield malfunction");
        expect(deathStar.shieldStatus()).to.eql("Shield malfunction");
      });
    });
  });
});

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

This project rocks and uses MIT-LICENSE.