turnerjs v1.0.276

Angular Components Test Kit

Post

A detailed post with examples and explanations can be found in the following Medium article:

Testing angular components — you don’t know what you’re missing

Overview

Component tests allows testing the UI (provided that it is build as components/directives of course) in order to get instant feedback and minimize the use of protractor.

The test kit provides a base driver utility class - TurnerComponentDriver, which allows writing tests using typescript in order to test components in a more readable, maintainable and quicker manner, It provides basic methods to allow rendering a template, accessing underlying elements and ability to maintain drivers' hierarchy, in order to be able to reuse drivers in parent components.

The best practice implemented by TurnerJS in regards to elements' selectors is by using a 'data-hook' attribute in order to mark elements which are accessed by your code. It implements the approach demonstrates in this article, but it is not mandated by the framework, one can use any other data selectors approach.

Installation - Bower

1. install using bower
   bower install --save turnerjs
2. Include the following reference in your Karma configuration file
   '<path to your app>/bower_components/turnerjs/dist/test/lib/turnerjs-driver.js'
3. Optional - if you are using TypeScript (recommended) add reference to the d.ts file in your tsconfig file:
   "bower_components/turnerjs/dist/test/lib/turnerjs-driver.d.ts"

Installation - NPM

1. install using node package manager
   npm install -S turnerjs
2. Include the following reference in your Karma configuration file
   'node_modules/turnerjs/module/generated/turnerjs-driver.js' or
   require(turnerjs) (when window is supported)
3. Optional - if you are using TypeScript (recommended) add reference to the d.ts file in your tsconfig file:
   "../node_modules/turnerjs/module/generated/turnerjs-driver.d.ts"

Usage

• Create a driver that extends the base driver and implement the methods that are required for your tests, for example (in the spec file or elsewhere):

   class ExampleComponentDriver extends TurnerComponentDriver {
           
        constructor() {
          super();
        }
      
        render(param1, param2) {
          //renders the template and adds the input parameters as scope params (second argument to renderFromTemplate method)
          //passing a selector is needed when the element containing the directive is not the first element in the template or when there is more than one driver
          this.renderFromTemplate('<example-component another-attribute="param2"><div data-hook="inner-element">{{param1}}</div></example-component>', {param1, param2}, 'example-component');
        }
      
        isInnerElementValid(): boolean {
           return this.findByDataHook('inner-element').text() === 'valid';
        }
      }

• Write tests that utilizes the driver

    let driver: ExampleComponentDriver;
    beforeEach(() => {
       driver = new ExampleComponentDriver();
       driver.render('valid', 'yada yada');
       driver.connectToBody();
    });
   
    afterEach(() => {
        driver.disconnectFromBody();
    });
    
    it('should contain a valid element value', () => {
        expect(driver.isInnerElementValid()).toBeTruthy();
    });

Global Methods added by the test kit

Base Driver Methods/ Members

Nested drivers

In order to allow reuse of drivers, the base driver supports initializing any child element (member) that extends TurnerComponentDriver For example, assuming 3 components are defined:

   angular.module('myModule', []);
   class ItemComponentCtrl {
     public item: {value: number};

     isValid():  boolean {
       return this.item.value > 1;
     }
   }
   
   angular
     .module('myModule')
     .component('itemComponent', {
       template: `<div data-hook="item-element" ng-class="{'valid': $ctrl.isValid()}"/>`,
       controller: ItemComponentCtrl,
       bindings: {
         item: '='
       }
     });
   
   class IndividualComponentCtrl {
     public item: {value: number};

     getText():  string {
       return this.item.value > 1 ? 'valid' : 'invalid';
     }
   }
   
   angular
     .module('myModule')
     .component('individualComponent', {
       template: `<div data-hook="inner-element">{{$ctrl.getText()}}</div>`,
       controller: IndividualComponentCtrl,
       bindings: {
         item: '='
       }
     });
   
   class ParentComponentCtrl {
     public items: {value: number}[];
   
     constructor() {
       this.items = [];
       for (let i = 0; i < 5; i++) {
         //push either 1 or 2
         this.items.push({
           value: Math.floor((Math.random() * 2) + 1)
         });
       }
     }
   }
   
   angular
     .module('myModule')
     .component('parentComponent', {
       template: `<div>
                    <individual-component item="$ctrl.items[0]"/>
                    <item-component ng-repeat="item in $ctrl.items" item="item"/>
                  </div>`,
       controller: ParentComponentCtrl
     });

3 Drivers that corresponds to each are defined:
(When there is a list of child drivers - e.g. when using ng-repeat, defineChildren method should be used in order to declare an array of child drivers)

  
class IndividualComponentDriver extends TurnerComponentDriver {

  constructor() {
    super();
  }

  render(item) {
    this.renderFromTemplate('<individual-component item="item"/>', {item});
  }

  isValid(): boolean {
    return this.findByDataHook('inner-element').text() === 'valid';
  }
}

class ItemComponentDriver extends TurnerComponentDriver {

  constructor() {
    super();
  }

  render(item) {
    this.renderFromTemplate('<item-component item="item"/>', {item}, 'item-component');
  }

  isValid(): boolean {
    return this.findByDataHook('item-element').hasClass('valid');
  }
}

class ParentComponentDriver extends TurnerComponentDriver {
  public innerComponent: IndividualComponentDriver;
  public itemComponents: ItemComponentDriver[];

  constructor() {
    super();
    this.innerComponent = this.defineChild(new IndividualComponentDriver(), 'individual-component');
    this.itemComponents = this.defineChildren(() => new ItemComponentDriver(), 'item-component');
  }

  render() {
    this.renderFromTemplate(`<parent-component>`);
  }

  isIndividualValid(): boolean {
    return this.innerComponent.isValid();
  }

  isItemsValid(): boolean {
    let result = true;
    this.itemComponents.forEach(itemDriver => {
      result = result && itemDriver.isValid();
    });
    return result;
  }
}

TurnerComponentDriver will initialize the member's scope & element automatically as soon as the renderFromTemplate method is invoked. The above drivers will allow testing each component separately and also testing the parent component that wraps the two:

describe('Usage Examples when there are repeatable drivers', () => {
    let parentComponentDriver: ParentComponentDriver;
    beforeEach(() => {
      module('myModule');
      parentComponentDriver = new ParentComponentDriver();
    });

    it('should be valid when the random values are above 1', () => {
      spyOn(Math, 'random').and.returnValue(0.9);
      parentComponentDriver.render();
      expect(parentComponentDriver.isIndividualValid()).toBe(true);
      expect(parentComponentDriver.isItemsValid()).toBe(true);
    });
  });

Non TypeScript usage

Though the recommendation is to use TypeScript with turnerjs, if you are not using it, you can create the driver using prototypical inheritance. There are various ways to implement it, but the test kits includes a test spec for ES5 usage (see app/test/spec/components/es5-name-formatter.js) The below provides the basic implementation of such driver:

/* globals TurnerComponentDriver */ //for jshint
function ES5Driver() {
  TurnerComponentDriver.call(arguments);
}

ES5Driver.prototype = new TurnerComponentDriver();
ES5Driver.constructor = ES5Driver;

ES5Driver.prototype.render = function () {
  this.renderFromTemplate('<es5-component-template></es5-component-template>');  
};
//other driver methods

describe('your tests are here', function () {
    var es5driver;
    
    beforeEach(function () {
        angular.mock.module('turnerjsAppInternal');
        driver = new ES5Driver();
    });
    
    it('...', function () {
        driver.render();
        //test e
    });
});

Contribution

Via pull requests,

After cloning the repository please run npm install and bower install in order to fetch dependencies

Running/Building the project is done by using grunt:
grunt serve:clean - will start the server, there is no real UI for it, but it will run the unit tests on each save grunt build - build the project to make sure that changes are valid and meeting all code style definitions

Credits

Alon Yehezkel
Shahar Talmi
Boris Litvinski
Amit Shvil

License

The MIT License.

See LICENSE