How to unit-test a directive with templateURL

It’s best practice to place the HTML of a directive’s partial within its own file, and reference it in the directive’s definition object via the templateUrl property. However, this causes problems in testing, as most testing frameworks provide no access to the local file. This article shows you how to get around this limitation, and provide any partial file you need in order to test your directive fully.

Tl;dr

To provide the directive’s file to your tests, either:

• 1. RECOMMENDED: Use the ng-html2js preprocessor to serve your actual partial’s HTML; or
• 2. Use $httpBackend to serve a mock partial; or
• 3. Use $templateCache to serve a mock partial

1. Use the ng-html2js preprocessor

By far the best approach is to use the ng-html2js preprocessor, which will convert a partial’s HTML into a JavaScript string, and make it accessible to your unit tests via AngularJS’s $templateCache.

It performs this feat of magic by reading your partial’s HTML, converting it into a JavaScript string, and placing it into Angular’s $templateCache. It does this within the run() function of a new module it creates for you.

When you declare this module as a dependency within your tests, the run() function is executed and the partial’s HTML is placed within the $templateCache, which the directive then accesses automatically as part of the $compile process.

For example, consider the following simple directive:

(function(){
    'use strict';

    angular
        .module('app')
        .directive('untangledHeader', untangledHeader);

    function untangledHeader(){

        var directive = {
            restrict: 'E',
            templateUrl: 'scripts/app/layout/header/header.tpl.html',
        };

        return directive;
})();

Suppose its partial looks as follows:

// defined in scripts/app/layout/header/header.tpl.html
Header Title

When you run karma, the ng-html2js preprocessor will:

• create a module with a name you’ve defined in karma.conf.js (in this example, I’ve called it partials);
• read the partial’s HTML file;
• convert it into a JavaScript string;
• place it in $templateCache with the name 'scripts/app/layout/header/header.tpl.html' in the module’s run() function.

For this example, the output of all this will see the partial transformed into the following auto-generated module:

(function(module) {
try {
  module = angular.module('partials');
} catch (e) {
  module = angular.module('partials', []);
}
module.run(['$templateCache', function($templateCache) {
  $templateCache.put('scripts/app/layout/header/header.tpl.html',
     '
Header Title
');
  }]);
})();

You can now simply include this partial’s module in your tests like so:

beforeEach(module('partials'));

…and the directive will automatically use the JavaScript string that the partials module placed into the $templateCache.

Example test

Putting this altogether, your test will look like this:

describe('Header Directive: untangledHeader', function() {

    beforeEach(module('app'));
    // declare ng-html2js's auto-generated partials module as a dependency
    beforeEach(module('partials'));

    var element,
        scope,
        isolateScope;

    beforeEach(inject(function($rootScope, $compile) {
        scope = $rootScope.$new();
        element = angular.element('');

        // element will enable you to test your directive's element on the DOM
        element = $compile(element)(scope);

        // Digest needs to be called to set any values on the directive's scope
        scope.$digest();

        // If the directive uses isolate scope, we need to get a reference to it 
        // explicitly
        isolateScope = element.isolateScope();
    }));

   it('Should...', function(){
      expect(scope.x).toBe(y);
      expect(isolateScope.a).toBe(b);
   });
});

Pros

The chief advantage of this approach is that you’re actually using the production HTML of the directive that will be used in your application. This is important, as a complex directive may depend on the correct HTML elements and attributes being present. Using a mocked partial will only test the HTML you provide for the test – not the actual HTML used in your app.

A second advantage is the simplicity of this approach once you have it up and running. Simply include the partials module, and you can forget about worrying whether or not you’ve correctly mocked your HTML partials.

Finally, your partial’s HTML is guaranteed never to be out of sync with that of the app. You can make as many changes as you need to your partial’s HTML, without updating the HTML in your tests.

Cons

The (marginal) downside to using the ng-html2js preprocessor is that it doesn’t let you change the partial’s HTML in your unit tests, which you may want to do if you need to test how your directive handles errors (e.g. missing attributes).

It can also be a bit fiddly to setup, but hopefully the following sub-section will help you solve some of the more common issues.

Troubleshooting ng-html2js

Some common errors people (well, me, you might make different ones!) make include:

Not setting the path to your partials correctly

If the ng-html2js preprocessor can’t find the partial’s HTML, it can’t transform it into JavaScript for you.

To check if this is your problem, run the Karma tests in Chrome, and try to find your partials module. By default, it’ll be named the same as the partial’s HTML file, but with .js appended, and will be in the same folder as the existing partial.

For example, a partial called scripts/app/layout/header/header.tpl.html will be replaced with a file called scripts/app/layout/header/header.tpl.html.js (note: the JavaScript version of your partial’s HTML will only replace the original HTML in the browser – the HTML file itself remains unchanged on your filesystem).

If it doesn’t exist, your filepaths are wrong in karma.conf.js.

You can see what files the ng-html2js preprocessor is trying to process by running karma from the command line with the debug log-level switched on:

karma start --log-level debug

This will output the HTML files that ng-html2js has found and is converting. For example, with the header.tpl.html partial used above, you might see the following output:

:DEBUG [preprocessor.html2js]: Processing "/dev/untangled-angular-seed/scripts/app/layout/header/header.tpl.html".

If you don’t see the files you expect, again, your filepaths are wrong in karma.conf.js

Inadvertently changing the partial’s path name that’s placed in the $templateCache

ng-html2s gives you the opportunity to change the name of the partials with the stripPrefix, stripSuffix and appendSuffix configuration options.

However, it’s easy to misuse these. Just remember that the name of your partial that ng-html2js uses must match the value used in the directive’s templateUrl property.

This is because the value used in the directive’s templateUrl property is used by the $compile function to locate the directive’s partial. $compile will use this this value to query $templateCache to see if it’s been loaded into the cache.

If you change the pathname of the partial by incorrectly configuring the ng-html2js preprocessor in karam.conf.js, the partial’s pathname used in $templateCache will no longer match that in the directive’s templateUrl property, and so the $compile function will not be able to find it in the cache.

Here’s an example of a correctly-configured karma.conf.js module.exports = function(config) { config.set({ basePath: ”, frameworks: [‘jasmine’], // Load third-party libraries first, then modules, // then all other components, then // your tests, then your partials’ HTML files: [ ‘dist/lib.min.js’, ‘scripts/app/app.module.js’, ‘scripts/app/*.js’, ‘scripts/app/**/*.module.js’, ‘scripts/app/**/*.js’, ‘scripts/app/**/*.spec.js’, ‘scripts/app/**/*.html’ ], // Tell karma to use ng-html2js preprocessors: { ‘scripts/app/**/*.html’: [‘ng-html2js’] }, // configure ng-html2js ngHtml2JsPreprocessor: { // create a single module that contains templates from all the files moduleName: ‘partials’ } }) };

Useful Links

Pablo Villoslada Puigcerber has a good article on configuring and using ng-html2js, which will help you install and configure this handy preprocessor.

describe('Header Directive: untangledHeader', function() {

    beforeEach(module('app'));

    var element,
        scope,
        isolateScope;

    beforeEach(inject(function($rootScope, $compile, $httpBackend) {

       // scripts/app/layout/header/header.tpl.html is the same path listed in your 
       // directive's templateUrl property
       $httpBackend.whenGET('scripts/app/layout/header/header.tpl.html')
           .respond(‘
your mock partial
');

       scope = $rootScope.$new();
       element = angular.element('')(scope);

       mockScope.$digest();
       $httpBackend.flush();

       // elem now contains your compiled directive as an Angular element. 
       // If the directive defines an isolate scope, and you need to test any 
       // of its properties, you can access the isolate scope as follows:
       var compiledElementScope = elem.isolateScope();
   });
});

afterEach($httpBackend.verifyNoOutstandingExpectation);

beforeEach(inject(function($templateCache) {
   // When directive is called, return template's html as templateUrl 
   $templateCache.put('/path/to/yourDirectiveTemplate.tpl.html', template);
});