README
This utility library is unstable and experimental. You don't have to use it for all of your test suites. Give it a try for testing one of your services/controllers/directives!
tentacle.js
Auto-mock dependencies for angular.js tests. See integration tests for examples.
Injecting or mocking dependencies is supported for services/factories, controllers and directives.
Filters and providers currently are not supported. However services returned by providers can be tested using tentacle.js.
Table of Contents
tentacle.injectAll
tentacle.service
tentacle.factory
tentacle.controller
tentacle.controller.run
tentacle.directive
tentacle.directive.run
tentacle.reset
1. Installation
npm:
npm install tentacle.js
bower:
bower install tentacle.js
2. First steps
node.js:
var tentacleInit = require('tentacle');
var angular = require('angular');
var globalScope = {}; // you can use global too,
// similar to window object
// in browsers
tentacleInit(global, angular)
// You can use globalScope.tentacle
describe('test', function () {
it('should have tentacle', function () {
expect(globalScope.tentacle).to.be.an.object;
// if you use 'global' object:
// expect(tentacle).to.be.an.object;
});
});
browsers (karma):
Add dist/tentacle.js to your files list in karma config. tentacle
object is put into window
global variable:
describe('test', function () {
it('should have tentacle', function () {
expect(tentacle).to.be.an.object;
});
});
3. API and examples:
tentacle.injectAll
Injects all dependencies given a module name and a service, factory, controller or directive name.
Arguments
Param | Type | Details |
---|---|---|
moduleName | string | name of angular module |
name | string | name of service/factory/ctrl/directive |
tentacle.service
tentacle.factory
Mocks all dependencies of an angular service, except those defined in tentacle.mockExceptions
.
Usage
// a simple service
angular.module('myModule').factory('myService', [
'anotherService',
function (anotherService) {
return {
myMethod: function () {
anotherService.anotherMethod();
};
}
}]);
// ----------------
// test
var mocks = tentacle.service('myModule', 'myService');
mocks.anotherService.anotherMethod = function () {
return 'HELLO';
};
expect(myService.myMethod()).to.equal('HELLO');
Arguments
Param | Type | Details |
---|---|---|
moduleName | string | name of angular module |
serviceName | string | name of service |
customMocks | object | (optional) string-value pairs for overriding default mock object. defaults to an empty object |
defaultMock | any | (optional) value to inject for mocked dependencies. provided values are deeply cloned before each injection. defaults to an empty object |
Returns
object{string: any}
: string-value pairs of mocked dependency names and their values
tentacle.controller
Mocks all dependencies of an angular controller, except those defined in tentacle.mockExceptions
.
Usage
// a simple controller
angular.module('myModule').controller('myCtrl', [
'$scope',
'anotherService',
function ($scope, anotherService) {
this.myMethod = function () {
anotherService.anotherMethod();
}
$scope.myValue = this.myMethod();
}]);
// ----------------
// test
var mocks = tentacle.controller('myModule', 'myCtrl');
mocks.anotherService.anotherMethod = function () {
return 'HELLO';
};
var ctrl = tentacle.controller.run();
expect(ctrl.myMethod()).to.equal('HELLO');
expect($scope.myValue).to.equal('HELLO');
Arguments
Param | Type | Details |
---|---|---|
moduleName | string | name of angular module |
ctrlName | string | name of controller |
customMocks | object | (optional) string-value pairs for overriding default mock object. defaults to an empty object |
defaultMock | any | (optional) value to inject for mocked dependencies. provided values are deeply cloned before each injection. defaults to an empty object |
Returns
object{string: any}
: string-value pairs of mocked dependency names and their values
tentacle.controller.run
Executes the last controller that was initialized using tentacle.controller
.
Returns
`object : instance of controller
tentacle.directive
Mocks all dependencies of an angular controller, except those defined in tentacle.mockExceptions
.
Usage
// a simple directive
angular.module('myModule').directive('myDir', [
'anotherService',
function (anotherService) {
function link ($scope) {
$scope.myValue = anotherService.anotherMethod();
}
return {
restrict: 'EA',
scope: {
'myParam': '='
},
template: '<p>{{myParam}}</p>'
}
}]);
// ----------------
// test
var mocks = tentacle.directive('myModule', 'myDir');
mocks.anotherService.anotherMethod = function () {
return 'HELLO';
};
var elem = tentacle.directive.run('<my-dir my-param="param"></my-dir');
expect(isolateScope.myValue).to.equal('HELLO');
$scope.param = 'tentacle.js';
$scope.$digest();
var isolateScope = elem.isolateScope();
expect(isolateScope.myParam).to.equal('tentacle.js');
Arguments
Param | Type | Details |
---|---|---|
moduleName | string | name of angular module |
dirName | string | name of directive |
customMocks | object | (optional) string-value pairs for overriding default mock object. defaults to an empty object |
defaultMock | any | (optional) value to inject for mocked dependencies. provided values are deeply cloned before each injection. defaults to an empty object |
Returns
object{string: any}
: string-value pairs of mocked dependency names and their values
tentacle.directive.run
Executes the last controller that was initialized using tentacle.controller
.
Param | Type | Details |
---|---|---|
html | string | html to use for initializing directive. it must have an element that resolves to tested directive at root |
Returns
object
: an instance of angular.element
. the following methods are especially important for testing:
scope()
: returns scopeisolateScope()
: returns isolate scope if directive is defined to have onecontroller('directiveName')
: returns controller that was set in directive definition usingcontroller
property.
4. Advanced
You can read the following for more advanced information on tentacle.js.
How it works
When dependencies are injected or mocked using tentacle.js, dependencies for given service, controller or directive are searched in angular._invokeQueue
, a private/undocumented property of angular.
Dependencies in tentacle.globalInjects
are always injected in the global scope while dependencies in tentacle.mockExceptions
are never mocked.
tentacle.globalInjects
You can push more dependencies into this array. It is defined as follows:
tentacle.globalInjects = [
'$rootScope',
'$q',
'$httpBackend',
'$templateCache',
'$compile'
];
tentacle.mockExceptions
You can push more dependencies into this array. It is defined as follows:
tentacle.mockExceptions = [
'$http',
'$httpBackend',
'$rootScope',
'$q',
'$scope',
'$filter'
];