Setup

If unsure how to set up Angular with Jest please refer to the article: https://barcioch.pro/angular-with-jest-setup

Component

Create a component with one input and one output:

• the component takes a title value and displays it in div

• when user clicks button the value from the title field is emitted through buttonClick EventEmitter.

// test.component.ts

import { Component, EventEmitter, Input, Output } from '@angular/core';

@Component({
  selector: 'app-test',
  templateUrl: './test.component.html',
  styleUrls: ['./test.component.css']
})
export class TestComponent {
  @Input() title = '';
  @Output() buttonClick = new EventEmitter<string>();

  click(): void {
    this.buttonClick.emit(this.title);
  }
}

<!-- test.component.html -->

<div class="title">{{ title }}</div>
<button
    type="button"
    (click)="click()"
    class="button">Button</button>

Test

To test a component I'll wrap it in the wrapper component, so it will work as used in the real application. It will also make it easy to pass the values and validate outputs.

@Component({
  selector: 'app-dummy',
  template: `<app-test [title]="title" (buttonClick)="buttonClicked($event)"></app-test>`,
  styleUrls: ['./test.component.css']
})
export class DummyComponent {
  title?: string;

  click(): void {  }

  buttonClicked(value: string): void {  }
}

The test works as follows:

• declare all needed components

declarations: [
  TestComponent,
  DummyComponent,
],

• create the fixture and component reference

fixture = TestBed.createComponent(DummyComponent);
component = fixture.componentInstance;

• spy on buttonClicked method

jest.spyOn(component, 'buttonClicked');

• test component default settings

describe('when no title is passed ', () => {
  it('should display empty title', () => {
    expect(getTitle().nativeElement.innerHTML).toBe('');
  });

  describe('and user clicks button', () => {
    beforeEach(() => {
      getButton().nativeElement.click();
      fixture.detectChanges();
    });

    it('should emit empty string', () => {
      expect(component.buttonClicked).toHaveBeenCalledTimes(1);
      expect(component.buttonClicked).toHaveBeenCalledWith('');
    });
  });
});

Note that I'm clicking the HTML Button element

getButton().nativeElement.click();

and validating the wrapper's method call

expect(component.buttonClicked).toHaveBeenCalledTimes(1);
expect(component.buttonClicked).toHaveBeenCalledWith('');

Test the passed value and output

  describe('when "my title" value is passed as "title"', () => {
    beforeEach(() => {
      component.title = 'my title';
      fixture.detectChanges();
    });

    it('should display "my title"', () => {
      expect(getTitle().nativeElement.innerHTML).toBe('my title');
    });

    describe('and user clicks button', () => {
      beforeEach(() => {
        getButton().nativeElement.click();
        fixture.detectChanges();
      });

      it('should emit empty string', () => {
        expect(component.buttonClicked).toHaveBeenCalledTimes(1);
        expect(component.buttonClicked).toHaveBeenCalledWith('my title');
      });
    });
  });

Set value directly on the wrapper and run change detection

component.title = 'my title';
fixture.detectChanges();

The rest is similar to the previous test.

Full test:

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { TestComponent } from './test.component';
import { Component, DebugElement } from '@angular/core';
import { By } from '@angular/platform-browser';

describe('TestComponent', () => {
  let fixture: ComponentFixture<DummyComponent>;
  let component: DummyComponent;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [
        TestComponent,
        DummyComponent,
      ],
    }).compileComponents();

    fixture = TestBed.createComponent(DummyComponent);
    component = fixture.componentInstance;
    jest.spyOn(component, 'buttonClicked');
  });


  describe('when no title is passed ', () => {
    it('should display empty title', () => {
      expect(getTitle().nativeElement.innerHTML).toBe('');
    });

    describe('and user clicks button', () => {
      beforeEach(() => {
        getButton().nativeElement.click();
        fixture.detectChanges();
      });

      it('should emit empty string', () => {
        expect(component.buttonClicked).toHaveBeenCalledTimes(1);
        expect(component.buttonClicked).toHaveBeenCalledWith('');
      });
    });
  });

  describe('when "my title" value is passed as "title"', () => {
    beforeEach(() => {
      component.title = 'my title';
      fixture.detectChanges();
    });

    it('should display "my title"', () => {
      expect(getTitle().nativeElement.innerHTML).toBe('my title');
    });

    describe('and user clicks button', () => {
      beforeEach(() => {
        getButton().nativeElement.click();
        fixture.detectChanges();
      });

      it('should emit empty string', () => {
        expect(component.buttonClicked).toHaveBeenCalledTimes(1);
        expect(component.buttonClicked).toHaveBeenCalledWith('my title');
      });
    });
  });

  const getTitle = (): DebugElement => {
    return fixture.debugElement.query(By.css('.title'));
  }

  const getButton = (): DebugElement => {
    return fixture.debugElement.query(By.css('.button'));
  }
});

@Component({
  selector: 'app-dummy',
  template: `
    <app-test [title]="title" (buttonClick)="buttonClicked($event)"></app-test>`,
  styleUrls: ['./test.component.css']
})
export class DummyComponent {
  title: string = '';

  buttonClicked(value: string): void { }
}

Source code

https://gitlab.com/barcioch-blog-examples/series-angular-testing-07-component-input-output-testing

• no methods, setters or getters, only properties

• properties can be nested (arrays, objects)

• all properties are "cloneable", i.e. they can't be Error, Promise, Function, undefined and some other types

• no circular references

I'll show three ways to do so. There are of course hundreds of other ways but these three should be more than enough for data objects. In the end, I'll write some tests in Jest to verify the objects' equality.

Setup

Requirements:

• node 17

• npm 8

• npx

Initialize npm with default settings

npm init -y

Install dependencies

npm i jest@29 @types/jest@29 ts-jest@29 typescript@5 fast-copy

Initialize the default configuration of ts-jest

npx ts-jest config:init

Simple examples

JSON.stringify, JSON.parse

Documentation:

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify

• https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse

These methods do exactly what the names suggest. First, we call JSON.stringify() method that converts a value to plain JSON format (the returned value is a string). Then we call JSON.parse() method to parse the JSON string into a plain javascript object. In this process, all the references and class types are lost. In terms of speed that's the slowest solution and should only be used when performance is not a big deal.

Usage:

const variable = { myProp: [1, 'two'] };
console.log('original:', variable);
const clone = JSON.parse(JSON.stringify(variable));
console.log('cloned:  ', clone);

fast-copy

Documentation: https://github.com/planttheidea/fast-copy

This library has a few methods, but I'll focus on copy(). This method takes a single argument and returns a cloned value. One of the advantages this library has is that it tries to retain the source class type which the other two libraries don't.

Usage

import copy from 'fast-copy';

const variable = { myProp: [1, 'two'] };
console.log('original:', variable);
const clone = copy(variable)
console.log('cloned:  ', clone);

structuredClone

Documentation: https://developer.mozilla.org/en-US/docs/Web/API/structuredClone

This built-in function is available only in the newest browsers (https://caniuse.com/?search=structuredClone) and by default in Node 17+. Its usage is very simple: just call the function and pass a value to clone it.

const variable = { myProp: [1, 'two'] };
console.log('original:', variable);
const clone = structuredClone(variable)
console.log('cloned:  ', clone);

The result

All the previous examples were quite simple. Each time the result should be the same:

original: { myProp: [ 1, 'two' ] }
cloned:   { myProp: [ 1, 'two' ] }

Complex example

Create an example to check multiple values

// index.js 

import copy from 'fast-copy';

class TestClass {
  number: number;
  string: string;
  array: unknown[];
  object: object;
  class: TestClass;
}

const simpleObject = { propNumber: 256, propString: 'a string prop' };

const otherTestClass = new TestClass();
otherTestClass.array = [2, '3', 'five', [], simpleObject, null, undefined];
otherTestClass.string = 'a new string';
otherTestClass.number = -88;
otherTestClass.object = { prop2: 'val2' };

const myTestClass = new TestClass();
myTestClass.array = [1, '2', 'three', [], simpleObject, null, undefined];
myTestClass.string = 'a string';
myTestClass.number = 99;
myTestClass.object = { prop: 'val' };
myTestClass.class = otherTestClass;

const values = [
  { key: 'null', value: null },
  { key: 'false', value: false },
  { key: 'true', value: true },
  { key: '0', value: 0 },
  { key: '-10', value: -10 },
  { key: '99', value: 99 },
  { key: '0.1', value: 0.1 },
  { key: '-1.0009', value: -1.0009 },
  { key: 'Infinity', value: Infinity },
  { key: '\'\'', value: '' },
  { key: 'a string', value: 'a string' },
  { key: '[]', value: [] },
  { key: '[1,\'2\',\'three\', [], {prop: \'val\'}]', value: [1, '2', 'three', [], { prop: 'val' }] },
  { key: '{}', value: {} },
  { key: 'myTestClass', value: myTestClass }
]

class Result {

  constructor(input: any, jsonStringifyParse: any, fastCopy: any, structuredClone: any) {
    this.input = input;
    this.jsonStringifyParse = jsonStringifyParse;
    this.fastCopy = fastCopy;
    this.structuredClone = structuredClone;
  }

  input: any;
  jsonStringifyParse: any;
  fastCopy: any;
  structuredClone: any;
}

const group = {};

values.forEach(value => {
  group[value.key] = new Result(
    value.value,
    JSON.parse(JSON.stringify(value.value)),
    copy(value.value),
    structuredClone(value.value)
  );
})

console.table(group, ['jsonStringifyParse', 'fastCopy', 'structuredClone'])
console.dir(group, {depth: null})

Run it

npx tsc index.ts && node index.js

The output of console.table()

┌────────────────────────────────────┬───────────────────────────────────────┬───────────────────────────────────────┬───────────────────────────────────────┐
│              (index)               │          jsonStringifyParse           │               fastCopy                │            structuredClone            │
├────────────────────────────────────┼───────────────────────────────────────┼───────────────────────────────────────┼───────────────────────────────────────┤
│                 0                  │                   0                   │                   0                   │                   0                   │
│                 99                 │                  99                   │                  99                   │                  99                   │
│                null                │                 null                  │                 null                  │                 null                  │
│               false                │                 false                 │                 false                 │                 false                 │
│                true                │                 true                  │                 true                  │                 true                  │
│                -10                 │                  -10                  │                  -10                  │                  -10                  │
│                0.1                 │                  0.1                  │                  0.1                  │                  0.1                  │
│              -1.0009               │                -1.0009                │                -1.0009                │                -1.0009                │
│              Infinity              │                 null                  │               Infinity                │               Infinity                │
│                 ''                 │                  ''                   │                  ''                   │                  ''                   │
│              a string              │              'a string'               │              'a string'               │              'a string'               │
│                 []                 │                  []                   │                  []                   │                  []                   │
│ [1,'2','three', [], {prop: 'val'}] │ [ 1, '2', 'three', ... 2 more items ] │ [ 1, '2', 'three', ... 2 more items ] │ [ 1, '2', 'three', ... 2 more items ] │
│                 {}                 │                  {}                   │                  {}                   │                  {}                   │
│            myTestClass             │               [Object]                │              [TestClass]              │               [Object]                │
└────────────────────────────────────┴───────────────────────────────────────┴───────────────────────────────────────┴───────────────────────────────────────┘

A quick look can tell if the values match and where the class types were retained. Since console.table() does not expand objects, the console.dir() can be used. To expand variables without the nesting limit pass {depth: null} as the second argument.

The output of console.dir()

{
  '0': Result {
    input: 0,
    jsonStringifyParse: 0,
    fastCopy: 0,
    structuredClone: 0
  },
  '99': Result {
    input: 99,
    jsonStringifyParse: 99,
    fastCopy: 99,
    structuredClone: 99
  },
  null: Result {
    input: null,
    jsonStringifyParse: null,
    fastCopy: null,
    structuredClone: null
  },
  false: Result {
    input: false,
    jsonStringifyParse: false,
    fastCopy: false,
    structuredClone: false
  },
  true: Result {
    input: true,
    jsonStringifyParse: true,
    fastCopy: true,
    structuredClone: true
  },
  '-10': Result {
    input: -10,
    jsonStringifyParse: -10,
    fastCopy: -10,
    structuredClone: -10
  },
  '0.1': Result {
    input: 0.1,
    jsonStringifyParse: 0.1,
    fastCopy: 0.1,
    structuredClone: 0.1
  },
  '-1.0009': Result {
    input: -1.0009,
    jsonStringifyParse: -1.0009,
    fastCopy: -1.0009,
    structuredClone: -1.0009
  },
  Infinity: Result {
    input: Infinity,
    jsonStringifyParse: null,
    fastCopy: Infinity,
    structuredClone: Infinity
  },
  "''": Result {
    input: '',
    jsonStringifyParse: '',
    fastCopy: '',
    structuredClone: ''
  },
  'a string': Result {
    input: 'a string',
    jsonStringifyParse: 'a string',
    fastCopy: 'a string',
    structuredClone: 'a string'
  },
  '[]': Result {
    input: [],
    jsonStringifyParse: [],
    fastCopy: [],
    structuredClone: []
  },
  "[1,'2','three', [], {prop: 'val'}]": Result {
    input: [ 1, '2', 'three', [], { prop: 'val' } ],
    jsonStringifyParse: [ 1, '2', 'three', [], { prop: 'val' } ],
    fastCopy: [ 1, '2', 'three', [], { prop: 'val' } ],
    structuredClone: [ 1, '2', 'three', [], { prop: 'val' } ]
  },
  '{}': Result {
    input: {},
    jsonStringifyParse: {},
    fastCopy: {},
    structuredClone: {}
  },
  myTestClass: Result {
    input: TestClass {
      array: [
        1,
        '2',
        'three',
        [],
        { propNumber: 256, propString: 'a string prop' },
        null,
        undefined
      ],
      string: 'a string',
      number: 99,
      object: { prop: 'val' },
      class: TestClass {
        array: [
          2,
          '3',
          'five',
          [],
          { propNumber: 256, propString: 'a string prop' },
          null,
          undefined
        ],
        string: 'a new string',
        number: -88,
        object: { prop2: 'val2' }
      }
    },
    jsonStringifyParse: {
      array: [
        1,
        '2',
        'three',
        [],
        { propNumber: 256, propString: 'a string prop' },
        null,
        null
      ],
      string: 'a string',
      number: 99,
      object: { prop: 'val' },
      class: {
        array: [
          2,
          '3',
          'five',
          [],
          { propNumber: 256, propString: 'a string prop' },
          null,
          null
        ],
        string: 'a new string',
        number: -88,
        object: { prop2: 'val2' }
      }
    },
    fastCopy: TestClass {
      array: [
        1,
        '2',
        'three',
        [],
        { propNumber: 256, propString: 'a string prop' },
        null,
        undefined
      ],
      string: 'a string',
      number: 99,
      object: { prop: 'val' },
      class: TestClass {
        array: [
          2,
          '3',
          'five',
          [],
          { propNumber: 256, propString: 'a string prop' },
          null,
          undefined
        ],
        string: 'a new string',
        number: -88,
        object: { prop2: 'val2' }
      }
    },
    structuredClone: {
      array: [
        1,
        '2',
        'three',
        [],
        { propNumber: 256, propString: 'a string prop' },
        null,
        undefined
      ],
      string: 'a string',
      number: 99,
      object: { prop: 'val' },
      class: {
        array: [
          2,
          '3',
          'five',
          [],
          { propNumber: 256, propString: 'a string prop' },
          null,
          undefined
        ],
        string: 'a new string',
        number: -88,
        object: { prop2: 'val2' }
      }
    }
  }
}

Now, you can visually compare all the outputs and tell if that's the desired output.

Testing

Nevertheless, a solid test case is surely needed. I'll use the same input data.

// index.spec.ts

import copy from 'fast-copy';

class TestClass {
  number: number;
  string: string;
  array: unknown[];
  object: object;
  class: TestClass;
}

const simpleObject = { propNumber: 256, propString: 'a string prop' };

const otherTestClass = new TestClass();
otherTestClass.array = [2, '3', 'five', [], simpleObject, null, undefined];
otherTestClass.string = 'a new string';
otherTestClass.number = -88;
otherTestClass.object = { prop2: 'val2' };

const myTestClass = new TestClass();
myTestClass.array = [1, '2', 'three', [], simpleObject, null, undefined];
myTestClass.string = 'a string';
myTestClass.number = 99;
myTestClass.object = { prop: 'val' };
myTestClass.class = otherTestClass;

const values = [
  { key: 'null', value: null },
  { key: 'false', value: false },
  { key: 'true', value: true },
  { key: '0', value: 0 },
  { key: '-10', value: -10 },
  { key: '99', value: 99 },
  { key: '0.1', value: 0.1 },
  { key: '-1.0009', value: -1.0009 },
  { key: 'Infinity', value: Infinity },
  { key: '\'\'', value: '' },
  { key: 'a string', value: 'a string' },
  { key: '[]', value: [] },
  { key: '[1,\'2\',\'three\', [], {prop: \'val\'}]', value: [1, '2', 'three', [], { prop: 'val' }] },
  { key: '{}', value: {} },
  { key: 'myTestClass', value: myTestClass }
]

const jsonStringifyParseDatasets = values.map(value => {
  return {
    key: value.key,
    input: value.value,
    result: JSON.parse(JSON.stringify(value.value))
  };
});

const fastCopyDatasets = values.map(value => {
  return {
    key: value.key,
    input: value.value,
    result: copy(value.value)
  };
});


const structuredCloneDatasets = values.map(value => {
  return {
    key: value.key,
    input: value.value,
    result: structuredClone(value.value)
  };
});

describe('jsonStringifyParse', () => {
  it.each(jsonStringifyParseDatasets)('value: $key', ({key, input, result}) => {
    expect(result).toEqual(input)
  });
});

describe('fastCopy', () => {
  it.each(fastCopyDatasets)('value: $key', ({key, input, result}) => {
    expect(result).toEqual(input)
  });
});

describe('structuredClone', () => {
  it.each(structuredCloneDatasets)('value: $key', ({key, input, result}) => {
    expect(result).toEqual(input)
  });
});

Run it

npx jest index.spec.ts

The result is

 FAIL  ./index.spec.ts
  jsonStringifyParse
    ✓ value: null (2 ms)
    ✓ value: false
    ✓ value: true (1 ms)
    ✓ value: 0
    ✓ value: -10
    ✓ value: 99
    ✓ value: 0.1
    ✓ value: -1.0009 (1 ms)
    ✕ value: Infinity (1 ms)
    ✓ value: '' (1 ms)
    ✓ value: a string
    ✓ value: [] (1 ms)
    ✓ value: [1,'2','three', [], {prop: 'val'}]
    ✓ value: {} (1 ms)
    ✕ value: myTestClass (5 ms)
  fastCopy
    ✓ value: null
    ✓ value: false (1 ms)
    ✓ value: true
    ✓ value: 0
    ✓ value: -10
    ✓ value: 99
    ✓ value: 0.1
    ✓ value: -1.0009
    ✓ value: Infinity
    ✓ value: '' (1 ms)
    ✓ value: a string
    ✓ value: []
    ✓ value: [1,'2','three', [], {prop: 'val'}]
    ✓ value: {} (1 ms)
    ✓ value: myTestClass
  structuredClone
    ✓ value: null
    ✓ value: false (1 ms)
    ✓ value: true
    ✓ value: 0
    ✓ value: -10
    ✓ value: 99
    ✓ value: 0.1
    ✓ value: -1.0009
    ✓ value: Infinity
    ✓ value: ''
    ✓ value: a string (1 ms)
    ✓ value: []
    ✓ value: [1,'2','three', [], {prop: 'val'}]
    ✓ value: {}
    ✓ value: myTestClass (1 ms)

  ● jsonStringifyParse › value: Infinity

    expect(received).toEqual(expected) // deep equality

    Expected: Infinity
    Received: null

      69 | describe('jsonStringifyParse', () => {
      70 |   it.each(jsonStringifyParseDatasets)('value: $key', ({key, input, result}) => {
    > 71 |     expect(result).toEqual(input)
         |                    ^
      72 |   });
      73 | });
      74 |

      at index.spec.ts:71:20

  ● jsonStringifyParse › value: myTestClass

    expect(received).toEqual(expected) // deep equality

    - Expected  - 4
    + Received  + 4

    @@ -1,30 +1,30 @@
    - TestClass {
    + Object {
        "array": Array [
          1,
          "2",
          "three",
          Array [],
          Object {
            "propNumber": 256,
            "propString": "a string prop",
          },
    +     null,
          null,
    -     undefined,
        ],
    -   "class": TestClass {
    +   "class": Object {
          "array": Array [
            2,
            "3",
            "five",
            Array [],
            Object {
              "propNumber": 256,
              "propString": "a string prop",
            },
            null,
    -       undefined,
    +       null,
          ],
          "number": -88,
          "object": Object {
            "prop2": "val2",
          },

      69 | describe('jsonStringifyParse', () => {
      70 |   it.each(jsonStringifyParseDatasets)('value: $key', ({key, input, result}) => {
    > 71 |     expect(result).toEqual(input)
         |                    ^
      72 |   });
      73 | });
      74 |

      at index.spec.ts:71:20

Test Suites: 1 failed, 1 total
Tests:       2 failed, 43 passed, 45 total

As you can see the 2 tests failed while using json stringify / parse method:

• the undefined value was converted to null

• the Infinity value was converted to null

• the TestClass type was converted back to Object type

These errors are caused due to the lack of support of these types by JSON format.

Setup

If unsure how to set up Angular with Jest please refer to the article: https://barcioch.pro/angular-with-jest-setup

Permissions

Define available permissions in the Permission enum.

// permission.enum.ts

export enum Permission {
  login = 'login',
  dashboard = 'dashboard',
  orders = 'orders',
  users = 'users',
  admin = 'admin',
}

Create a simple service for permission validation. The service takes as a first argument in the constructor the current users' permissions.

// permission.service.ts

import { Injectable } from '@angular/core';
import { Permission } from './permission.enum';

@Injectable()
export class PermissionService {
  constructor(private readonly permissions: Permission[]) {
  }

  hasPermission(permission: Permission): boolean {
    return this.permissions.includes(permission);
  }
}

Directive

Start with creating an empty directive with required dependencies.

// has-permission.directive.ts

import { Directive, TemplateRef, ViewContainerRef } from '@angular/core';
import { PermissionService } from './permission.service';

@Directive({
  selector: '[hasPermission]',
})
export class HasPermissionDirective {
  constructor(
    private readonly viewContainer: ViewContainerRef,
    private readonly templateRef: TemplateRef<unknown>,
    private readonly permissionService: PermissionService
  ) {
  }
}

There are 3 dependencies required for this directive to work:

• ViewContainerRef - a reference to the parent view

• TemplateRef<unknown> - a reference to the element's view that the directive is connected to

• PermissionService - service for checking users' permissions

The user needs to pass permission directly to the directive in the following manner:

// component
...
readonly permissions = Permission;
...

<!-- view -->

<div *hasPermission="permissions.login"></div>

To handle directive inputs use @Input() decorator. The input methods should be prefixed with directive selector (hasPermission in this case). The default input should be named exactly as the directive selector.

private hasCurrentPermission = false;

@Input() set hasPermission(permission: Permission) {
  this.hasCurrentPermission = this.permissionService.hasPermission(permission);
  this.displayTemplate();
}

private displayTemplate(): void {
  this.viewContainer.clear();

  if (this.hasCurrentPermission) {
    this.viewContainer.createEmbeddedView(this.templateRef);
  }
}

I created a setter hasPermission. It uses the PermissionService to check the permission and stores the result in the private property hasCurrentPermission. Next, the displayTemplate method is called. First, it clears the current view (removes the content) this.viewContainer.clear(). Then, it checks the hasCurrentPermission property and if it's true then it renders the element that the directive is attached to this.viewContainer.createEmbeddedView(this.templateRef).

Next, let's support the else keyword. The else should point to the ng-template reference.

<div *hasPermission="permissions.login; else noPermission"></div>

<ng-template #noPermission>
  <span>Access denied</span>
</ng-template>

To handle the else functionality we need to add the new input called hasPermissionElse. It's argument's type is the TemplateRef because we will be passing the template reference. Note, that the name consists of two parts:

• prefix: directive selector hasPermission

• suffix: the name used in the view else

private elseTemplateRef: TemplateRef<unknown>;

@Input() set hasPermissionElse(templateRef: TemplateRef<unknown>) {
  this.elseTemplateRef = templateRef;
  this.displayTemplate();
}

private displayTemplate(): void {
  this.viewContainer.clear();

  if (this.hasCurrentPermission) {
    this.viewContainer.createEmbeddedView(this.templateRef);
    return;
  }

  if (this.elseTemplateRef) {
    this.viewContainer.createEmbeddedView(this.elseTemplateRef);
  }
}

The hasPermissionElse setter takes and stores the else template reference and then it calls displayTemplate() method. The displayTemplate method has the following modifications:

• added return to this.hasCurrentPermission condition check

• added this.elseTemplateRef condition check. If the user has no permission and the else template reference was passed we render this template

The whole directive looks as follows:

// has-permission.directive.ts

import { Directive, Input, TemplateRef, ViewContainerRef } from '@angular/core';
import { PermissionService } from './permission.service';
import { Permission } from './permission.enum';

@Directive({
  selector: '[hasPermission]',
})
export class HasPermissionDirective {
  private elseTemplateRef: TemplateRef<unknown>;
  private hasCurrentPermission = false;

  constructor(
    private readonly viewContainer: ViewContainerRef,
    private readonly templateRef: TemplateRef<unknown>,
    private readonly permissionService: PermissionService
  ) {
  }

  @Input() set hasPermissionElse(templateRef: TemplateRef<unknown>) {
    this.elseTemplateRef = templateRef;
    this.displayTemplate();
  }

  @Input() set hasPermission(permission: Permission) {
    this.hasCurrentPermission = this.permissionService.hasPermission(permission);
    this.displayTemplate();
  }

  private displayTemplate(): void {
    this.viewContainer.clear();

    if (this.hasCurrentPermission) {
      this.viewContainer.createEmbeddedView(this.templateRef);
      return;
    }

    if (this.elseTemplateRef) {
      this.viewContainer.createEmbeddedView(this.elseTemplateRef);
    }
  }
}

Testing

A simple test that checks all possible combinations of directive inputs.

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { Component } from '@angular/core';
import { Permission } from './permission.enum';
import { CommonModule } from '@angular/common';
import { HasPermissionModule } from './has-permission.module';
import { PermissionService } from './permission.service';
import { By } from '@angular/platform-browser';

describe('HasPermissionDirective', () => {
  let fixture: ComponentFixture<TestComponent>;

  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [
        CommonModule,
        HasPermissionModule
      ],
      declarations: [TestComponent],
      providers: [
        {
          provide: PermissionService,
          useValue: new PermissionService([Permission.dashboard, Permission.users])
        }
      ]
    });

    fixture = TestBed.createComponent(TestComponent);
    fixture.detectChanges()
  });

  describe('when the test component is initialized', () => {
    describe('and user has set "dashboard" and "users" permissions', () => {
      it('should not display "orders" element', () => {
        const element = fixture.debugElement.query(By.css('#orders'));
        expect(element).toBeFalsy();
      });

      it('should display "dashboard" element', () => {
        const element = fixture.debugElement.query(By.css('#dashboard'));
        expect(element).toBeTruthy();
      });

      it('should not display "admin" element', () => {
        const element = fixture.debugElement.query(By.css('#admin'));
        expect(element).toBeFalsy();
      });

      it('should display "no-access-admin" element', () => {
        const element = fixture.debugElement.query(By.css('#no-access-admin'));
        expect(element).toBeTruthy();
      });

      it('should display "no-access-dashboard" element', () => {
        const element = fixture.debugElement.query(By.css('#admin'));
        expect(element).toBeFalsy();
      });


      it('should display "users" element', () => {
        const element = fixture.debugElement.query(By.css('#users'));
        expect(element).toBeTruthy();
      });

      it('should display "no-access-users" element', () => {
        const element = fixture.debugElement.query(By.css('#no-access-users'));
        expect(element).toBeFalsy();
      });

    });
  });
});


@Component({
  selector: 'app-test',
  template: `
    <div id="orders" *hasPermission="permissions.orders"></div>

    <div id="dashboard" *hasPermission="permissions.dashboard"></div>

    <div id="admin" *hasPermission="permissions.admin; else noAccessAdmin"></div>

    <ng-template #noAccessAdmin>
      <div id="no-access-admin"></div>
    </ng-template>

    <div id="users" *hasPermission="permissions.users; else noAccessUsers"></div>

    <ng-template #noAccessUsers>
      <div id="no-access-users"></div>
    </ng-template>
  `,
})
export class TestComponent {
  readonly permissions = Permission;
}

Run jest

npx jest

and you should see all tests passed

PASS  src/app/permissions/has-permission.spec.ts
  HasPermissionDirective
    when the test component is initialized
      and user has set "dashboard" and "users" permissions
        ✓ should not display "orders" element (52 ms)
        ✓ should display "dashboard" element (8 ms)
        ✓ should not display "admin" element (6 ms)
        ✓ should display "no-access-admin" element (6 ms)
        ✓ should display "no-access-dashboard" element (5 ms)
        ✓ should display "users" element (5 ms)
        ✓ should display "no-access-users" element (4 ms)

Test Suites: 1 passed, 1 total
Tests:       7 passed, 7 total
Snapshots:   0 total
Time:        0.836 s, estimated 2 s

Source code

https://gitlab.com/barcioch-blog-examples/008-angular-custom-ngif

Setup

If unsure how to set up Angular with Jest please refer to the article: https://barcioch.pro/angular-with-jest-setup

Clone element directive

The directive works as follows (everything happens in ngOnChanges method):

• clear the view of created elements

this.viewContainer.clear();

• check if the passed value is a valid number

if (this.appCloneElement == null) {
  return;
}

if (!Number.isFinite(this.appCloneElement)) {
  return;
}

if (this.appCloneElement < 1) {
  return;
}

• render the elements

for (let i = 1; i <= this.appCloneElement; i++) {
  this.viewContainer.createEmbeddedView(this.templateRef)
}

Full implementation:

import { Directive, Input, OnChanges, SimpleChanges, TemplateRef, ViewContainerRef } from '@angular/core';

@Directive({
  selector: '[appCloneElement]'
})
export class CloneElementDirective implements OnChanges {
  @Input() appCloneElement: number | null | undefined;

  constructor(
    private templateRef: TemplateRef<any>,
    private viewContainer: ViewContainerRef
  ) {
  }

  ngOnChanges(changes: SimpleChanges): void {
    this.viewContainer.clear();

    if (this.appCloneElement == null) {
      return;
    }

    if (!Number.isFinite(this.appCloneElement)) {
      return;
    }

    if (this.appCloneElement < 1) {
      return;
    }

    for (let i = 1; i <= this.appCloneElement; i++) {
      this.viewContainer.createEmbeddedView(this.templateRef)
    }
  }
}

Testing

To test a directive you need a component that passes properties to the directive. In the following example, it's TestComponent. The directive itself is declared in a separate module CloneElementModule so it has to be imported. The testing scenarios are quite simple:

• pass the value to the component

• detect changes

• validate the number of displayed, cloned elements

The first scenario to check is the default view - without passing any values.

describe('when component with directive is initialized', () => {

it('should not render any element', () => {
  expect(getClones().length).toBe(0);
});
...

The directive takes the number of elements to clone. If the number is less that 1 it shouldn't render any element. Since you can pass some values that are not valid numbers but the compiler won't complain about them, we're also going to test them. These values are: null, undefined, NaN, Infinity.

describe.each([
  {input: -1, inputText: '-1'},
  {input: -581, inputText: '-581'},
  {input: 0, inputText: '0'},
  {input: null, inputText: 'null'},
  {input: undefined, inputText: 'undefined'},
  {input: Infinity, inputText: 'Infinity'},
  {input: NaN, inputText: 'NaN'},
])('and $inputText value is passed', ({input}) => {
  beforeEach(() => {
    component.cloneNumber = input;
    fixture.detectChanges();
  });

  it('should not render any element', () => {
    expect(getClones().length).toBe(0);
  });
});

Also, you have to verify that multiple changes to the directive input will produce a valid number of cloned elements. The scenario will look like this:

• pass 5 number

• detect changes

• validate there are 5 elements

• pass 9 number

• detect changes

• validate there are 9 elements

• pass undefined value

• detect changes

• validate there are no elements

describe('and 5 value is passed', () => {
  beforeEach(() => {
    component.cloneNumber = 5;
    fixture.detectChanges();
  });

  it(`should render 5 elements`, () => {
    expect(getClones().length).toBe(5);
  });

  describe('and 9 value is passed', () => {
    beforeEach(() => {
      component.cloneNumber = 9;
      fixture.detectChanges();
    });

    it(`should render 9 elements`, () => {
      expect(getClones().length).toBe(9);
    });
  });

  describe('and undefined value is passed', () => {
    beforeEach(() => {
      component.cloneNumber = undefined;
      fixture.detectChanges();
    });

    it(`should not render any element`, () => {
      expect(getClones().length).toBe(0);
    });
  });
});

Full implementation:

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { Component, DebugElement } from '@angular/core';
import { CommonModule } from '@angular/common';
import { CloneElementModule } from './clone-element.module';
import { By } from '@angular/platform-browser';

describe('CloneElementDirective', () => {
  let fixture: ComponentFixture<TestComponent>;
  let component: TestComponent;

  beforeEach(() => {
    TestBed.configureTestingModule({
      imports: [
        CommonModule,
        CloneElementModule
      ],
      declarations: [TestComponent],
    });

    fixture = TestBed.createComponent(TestComponent);
    component = fixture.componentInstance;
  });

  describe('when component with directive is initialized', () => {

    it('should not render any element', () => {
      expect(getClones().length).toBe(0);
    });

    describe.each([
      {input: -1, inputText: '-1'},
      {input: -581, inputText: '-581'},
      {input: 0, inputText: '0'},
      {input: null, inputText: 'null'},
      {input: undefined, inputText: 'undefined'},
      {input: Infinity, inputText: 'Infinity'},
      {input: NaN, inputText: 'NaN'},
    ])('and $inputText value is passed', ({input}) => {
      beforeEach(() => {
        component.cloneNumber = input;
        fixture.detectChanges();
      });

      it('should not render any element', () => {
        expect(getClones().length).toBe(0);
      });
    });

    describe.each([
      {input: 1},
      {input: 99},
      {input: 19},
    ])('and $input value is passed', ({input}) => {
      beforeEach(() => {
        component.cloneNumber = input;
        fixture.detectChanges();
      });

      it(`should render ${ input } element(s)`, () => {
        expect(getClones().length).toBe(input);
      });
    });

    describe('and 5 value is passed', () => {
      beforeEach(() => {
        component.cloneNumber = 5;
        fixture.detectChanges();
      });

      it(`should render 5 elements`, () => {
        expect(getClones().length).toBe(5);
      });

      describe('and 9 value is passed', () => {
        beforeEach(() => {
          component.cloneNumber = 9;
          fixture.detectChanges();
        });

        it(`should render 9 elements`, () => {
          expect(getClones().length).toBe(9);
        });
      });

      describe('and undefined value is passed', () => {
        beforeEach(() => {
          component.cloneNumber = undefined;
          fixture.detectChanges();
        });

        it(`should not render any element`, () => {
          expect(getClones().length).toBe(0);
        });
      });
    });
  });

  const getClones = (): DebugElement[] => {
    return fixture.debugElement.queryAll(By.css('.clone'));
  }
});


@Component({
  selector: 'app-test',
  template: `
    <div class="clone" *appCloneElement="cloneNumber">I'm a clone</div>
  `,
})
export class TestComponent {
  cloneNumber: number | null | undefined;
}

Run the tests and you should see the results:

 PASS  src/app/directives/clone-element.directive.spec.ts
  CloneElementDirective
    when component with directive is initialized
      ✓ should not render any element
      and -1 value is passed
        ✓ should not render any element
      and -581 value is passed
        ✓ should not render any element
      and 0 value is passed
        ✓ should not render any element 
      and null value is passed
        ✓ should not render any element 
      and undefined value is passed
        ✓ should not render any element 
      and Infinity value is passed
        ✓ should not render any element 
      and NaN value is passed
        ✓ should not render any element
      and 1 value is passed
        ✓ should render 1 element(s) 
      and 99 value is passed
        ✓ should render 99 element(s) 
      and 19 value is passed
        ✓ should render 19 element(s) 
      and 5 value is passed
        ✓ should render 5 elements 
        and 9 value is passed
          ✓ should render 9 elements 
        and undefined value is passed
          ✓ should not render any element 

Test Suites: 1 passed, 1 total
Tests:       14 passed, 14 total

Source code

https://gitlab.com/barcioch-blog-examples/series-angular-testing-06-angular-directive-testing

• short hash

• long hash

• branch name

• commit date

Set up the app

Init the test app with default settings:

ng new app --defaults=true

Navigate to the app directory:

cd app

Install the dependencies. I'll be using the git-rev-sync library.

npm i git-rev-sync

Implement the solution

Create a .gitignore file the src/assets directory and add the following content. This will prevent the file from being included in the repository.

version.json

Create the script file dump-git-info.js in the app's main directory. The flow is quite simple:

• import the libraries

• read git data

• write file

// dump-git-info.js

const git = require('git-rev-sync');
const { writeFileSync } = require('fs');

const version = {
  short: git.short(),
  long: git.long(),
  branch: git.branch(),
  date: git.date(),
};

writeFileSync('./src/assets/version.json', JSON.stringify(version));

You can run the script with the following command:

npm i git-rev-sync

Check the file ./src/assets/version.json and you should see output similar to:

{"short":"386e4a5","long":"386e4a55e9e96018465754de172c351c68f7ff1f","branch":"master","date":"2023-04-15T13:45:30.000Z"}

Add the script to package.json:

{
  "scripts": {
    "dump-git-info": "node dump-git-info.js",
...

Also, add prebuild hook to run it automatically:

{
  "scripts": {
    "prebuild": "npm run dump-git-info",
...

From now on, whenever you run npm run build the version.json will be also created and accessible through /assets/version.json url in the browser.

$ npm run build

> app@0.0.0 prebuild
> npm run dump-git-info


> app@0.0.0 dump-git-info
> node dump-git-info.js


> app@0.0.0 build
> ng build

> Generating browser application bundles (phase: setup)...

Source code

https://gitlab.com/barcioch-blog-examples/007-angular-include-git-info

To mark a video as not interesting you need to click the menu button and click I'm not interested every single time. This becomes tedious very quickly, so I created a quick and dirty solution. Assuming you are currently viewing YouTube's main page, it iterates over all loaded videos and marks them as not interesting.

By default, the script assumes that 6th option in the menu is the I'm not interested option. Before copying/pasting make sure it's the same since in your region/language it can be located in a different position. If needed alter the notInterstedMenuItemIndex value.

If the script encounters only one option in the menu it assumes it's the YouTubeMix and clicks it.

const sleep = (ms) => {
    return new Promise(resolve => setTimeout(resolve, ms));
}

async function main() {
    const notInterstedMenuItemIndex = 4;
    const menuButtons = Array.from(document.querySelectorAll('#details button#button'));

    for (let i = 0; i < menuButtons.length; i++) {
        menuButtons[i].click();
        await sleep(50);

        const menuItems = document.querySelectorAll('#items ytd-menu-service-item-renderer');
        const menuItemIndex = menuItems.length === 1 ? 0 : notInterstedMenuItemIndex;
        menuItems[menuItemIndex].click();
        await sleep(50);
    }
}

main();

• directly create pipe and test output

• use the pipe in the component and test HTML

In the example there will be created two simple pipes:

• trim - for trimming strings

• ucFirst - for changing the first character to uppercase

The environment is initialized with the following libraries:

• Angular 15

• Jest 29

The pipes

TrimPipe

The pipe works as follows:

• take the input string

• if it's null or undefined or an empty string - return an empty string

• otherwise - return trimmed value

// trim.pipe.ts

import { Pipe, PipeTransform } from '@angular/core';

@Pipe({
  name: 'appTrim',
})
export class TrimPipe implements PipeTransform {

  transform(input: string | null | undefined): string {
    if (input == null || input.length === 0) {
      return '';
    }

    return input.trim();
  }
}

Test it:

// trim.pipe.spec.ts

import { TrimPipe } from './trim.pipe';

describe('TrimPipe', () => {
  describe('when pipe is created', () => {
    let pipe: TrimPipe;

    beforeAll(() => {
      pipe = new TrimPipe();
    });

    it.each([
      {input: undefined, text: 'undefined'},
      {input: null, text: 'null'},
      {input: '', text: 'empty string'},
      {input: '\n   \n', text: '"\\n   \\n"'},
    ])('should transform $text to empty string', ({input, text}) => {
      expect(pipe.transform(input)).toBe('');
    });

    it.each([
      {input: '  text', text: 'text', expectedText: 'text', expected: 'text'},
      {input: 'text  ', text: 'text', expectedText: 'text', expected: 'text'},
      {input: 'text text', text: 'text text', expectedText: 'text text', expected: 'text text'},
      {input: '   text text  ', text: 'text text', expectedText: 'text text', expected: 'text text'},
      {input: '   text \n text  ', text: 'text \\n text', expectedText: 'text \\n text', expected: 'text \n text'},
      {
        input: '\n   text \n text  \n',
        text: '\\n   text \\n text  \\n',
        expectedText: 'text \\n text',
        expected: 'text \n text'
      },
    ])('should transform "$text" to "$expectedText"', ({input, expected, expectedText}) => {
      expect(pipe.transform(input)).toBe(expected);
    });
  });
});

UcFirstPipe

The pipe works as follows:

• take the input string

• if it's null or undefined or an empty string - return an empty string

• otherwise - make the first letter upper case and return the string

// uc-first.pipe.ts

import { Pipe, PipeTransform } from '@angular/core';

@Pipe({
  name: 'appUcFirst',
})
export class UcFirstPipe implements PipeTransform {

  transform(input: string | null | undefined): string {
    if (input == null || input.length === 0) {
      return '';
    }

    return input[0].toUpperCase() + input.substring(1, input.length);
  }
}

Test it:

// uc-first.pipe.spec.ts

import { UcFirstPipe } from './uc-first.pipe';

describe('UcFirstPipe', () => {
  describe('when pipe is created', () => {
    let pipe: UcFirstPipe;

    beforeAll(() => {
      pipe = new UcFirstPipe();
    });

    it.each([
      {input: undefined, text: 'undefined'},
      {input: null, text: 'null'},
      {input: '', text: 'empty string'},
    ])('should transform $text to empty string', ({input, text}) => {
      expect(pipe.transform(input)).toBe('');
    });

    it.each([
      {input: ' ', expected: ' '},
      {input: ' text', expected: ' text'},
      {input: 'text', expected: 'Text'},
      {input: 'Text', expected: 'Text'},
      {input: 'a', expected: 'A'},
      {input: '1a', expected: '1a'},
      {input: 'TEXT ', expected: 'TEXT '},
    ])('should transform "$input" to "$expected"', ({input, expected}) => {
      expect(pipe.transform(input)).toBe(expected);
    });
  });
});

Testing in component

To properly test components without worrying about change detection it's a good practice to wrap them in the wrapper component and update only the wrapper's values. An example, of how the final HTML structure will look like:

<app-wrapper>
    <app-test>
        <span class="result">{{ title | appTrim | appUcFirst}}</span>
    </app-test>
</app-wrapper>

The test suite contains two extra definitions:

• AppWrapperComponent - wrapper component for setting values

• AppTestComponent - the right component that uses the pipe and takes data by input. Usually, these kinds of components don't need to be defined inside tests since we want to use already existing components or modules.

The test procedure is quite straightforward:

• create testing module

TestBed.configureTestingModule()

• prepare test data using

describe.each()

• pass the data to the component and run change detection

beforeEach(() => {
  component.title = input;
  fixture.detectChanges();
});

• test the title element

it(`should display "${ expectedText }"`, () => {
  expect(title().nativeElement.textContent).toBe(expected);
});

// pipes.spec.ts

import { ComponentFixture, TestBed } from '@angular/core/testing';
import { TrimPipe } from './pipes/trim.pipe';
import { UcFirstPipe } from './pipes/uc-first.pipe';
import { Component, DebugElement, Input } from '@angular/core';
import { By } from '@angular/platform-browser';

describe('Test Pipes', () => {
  let fixture: ComponentFixture<AppWrapperComponent>;
  let component: AppWrapperComponent;

  beforeEach(async () => {
    await TestBed.configureTestingModule({
      declarations: [
        TrimPipe,
        UcFirstPipe,
        AppTestComponent,
        AppWrapperComponent
      ],
    }).compileComponents();

    fixture = TestBed.createComponent(AppWrapperComponent);
    component = fixture.componentInstance;
  });

  describe.each([
    {input: '', inputText: '', expected: '', expectedText: ''},
    {input: 'article', inputText: 'article', expected: 'Article', expectedText: 'Article'},
    {input: '  article  ', inputText: '  article  ', expected: 'Article', expectedText: 'Article'},
    {input: '  new article  ', inputText: '  new article  ', expected: 'New article', expectedText: 'New article'},
    {
      input: '  \n new article \n  ',
      inputText: '  \\n new article \\n  ',
      expected: 'New article',
      expectedText: 'New article'
    },
    {
      input: '  \n new \n article \n  ',
      inputText: '  \\n new \\n article \\n  ',
      expected: 'New \n article',
      expectedText: 'New \\n article'
    },
  ])('when "$inputText" is passed', ({input, inputText, expected, expectedText}) => {
    beforeEach(() => {
      component.title = input;
      fixture.detectChanges();
    });

    it(`should display "${ expectedText }"`, () => {
      expect(title().nativeElement.textContent).toBe(expected);
    });
  });

  const title = (): DebugElement => {
    return fixture.debugElement.query(By.css('.title'));
  }
});


@Component({
  selector: 'app-test',
  template: '<span class="title">{{ title | appTrim | appUcFirst }}</span>',
})
export class AppTestComponent {
  @Input() title: string | null | undefined;
}

@Component({
  selector: 'app-wrapper',
  template: '<app-test [title]="title"></app-test>',
})
export class AppWrapperComponent {
  title: string | null | undefined;
}

Run npx jest --coverage and make sure that all the code paths you're interested in were tested.

 PASS  src/app/pipes/trim.pipe.spec.ts
 PASS  src/app/pipes/uc-first.pipe.spec.ts
 PASS  src/app/pipes.spec.ts
------------------|---------|----------|---------|---------|-------------------
File              | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
------------------|---------|----------|---------|---------|-------------------
All files         |     100 |      100 |     100 |     100 |                   
 trim.pipe.ts     |     100 |      100 |     100 |     100 |                   
 uc-first.pipe.ts |     100 |      100 |     100 |     100 |                   
------------------|---------|----------|---------|---------|-------------------

Test Suites: 3 passed, 3 total
Tests:       26 passed, 26 total
Snapshots:   0 total
Time:        1.945 s, estimated 3 s
Ran all test suites.

Summary

The pipes are implemented and thoroughly tested. In this example, the pipes were defined directly in the testing module. In the real application, the pipe will be probably defined in a separate module that you're going to import. As always, try to cover as many cases as you can imagine.

Source code

https://gitlab.com/barcioch-blog-examples/series-angular-testing-05-angular-pipe-testing

• Jest - https://jestjs.io

• jest-preset-angular - https://thymikee.github.io/jest-preset-angular

The setup is based on Angular 15 and Jest 29. Make sure you have globally installed Angular CLI 15 and npx.

Create the app (optional)

Create the new application with the defaults using Angular CLI.

ng new app --defaults=true

Navigate to the app directory:

cd app

Set up the Jest

Install required dependencies

npm i jest@29 @types/jest@29 jest-preset-angular ts-jest

Create setup-jest.ts file the application root and insert contents:

import 'jest-preset-angular/setup-jest';

Create jest.config.js file in the application root and insert contents:

module.exports = {
  preset: 'jest-preset-angular',
  setupFilesAfterEnv: ['<rootDir>/setup-jest.ts'],
  globalSetup: 'jest-preset-angular/global-setup',
};

Update tsconfig.spec.json file to match the following contents. There are two differences between the original and the changed file:

• added "module": "CommonJs"

• changed "types": ["jasmine"] to "types": ["jest"]

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
    "module": "CommonJs",
    "types": ["jest"]
  },
  "include": ["src/**/*.spec.ts", "src/**/*.d.ts"]
}

Remove karma and jasmine dependencies.

npm remove @types/jasmine jasmine-core karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter

Verify

Use the following command to run the tests. In the default app, there is one test suite for the AppComponent with 3 tests.

npx jest

The tests were run successfully.

 PASS  src/app/app.component.spec.ts
  AppComponent
    ✓ should create the app (183 ms)
    ✓ should have as title 'app' (36 ms)
    ✓ should render title (34 ms)

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   0 total
Time:        3.577 s, estimated 5 s
Ran all test suites.

Actions

The old way of creating actions.

• an enum CountriesActionTypes with action types

• each action as a class implementing Action interface

• union type CountriesActions with action class' references

import { Action } from '@ngrx/store';

export enum CountriesActionTypes {
  LoadCountries = '[Countries] Load Countries',
  LoadCountriesSuccess = '[Countries] Load Countries Success',
  LoadCountriesFailure = '[Countries] Load Countries Failure',
}

export class LoadCountries implements Action {
  readonly type = CountriesActionTypes.LoadCountries;
}

export class LoadCountriesSuccess implements Action {
  readonly type = CountriesActionTypes.LoadCountriesSuccess;

  constructor(public payload: string[]) {
  }
}

export class LoadCountriesFailure implements Action {
  readonly type = CountriesActionTypes.LoadCountriesFailure;
}

export type CountriesActions = LoadCountries | LoadCountriesSuccess | LoadCountriesFailure;

To migrate:

• remove the enum with action types

• replace action classes with createAction() functions

  • use props() function to define action payload

import { createAction, props } from '@ngrx/store';


export const requestCountries = createAction('[Countries] Request countries');
export const requestCountriesSuccess = createAction('[Countries] Request countries success', props<{ response: string[] }>());
export const requestCountriesError = createAction('[Countries] Request countries error', props<{ error: unknown }>());

Reducer

The old reducer uses switch instruction to update state according to supported action type (taken from action's class type property).

import { CountriesActions, CountriesActionTypes } from './countries.actions';


export const STATE_NAME = 'countries';

export interface CountriesState {
  loading?: boolean;
  error?: boolean;
  list?: string[];
}

export function countriesReducer(state: CountriesState = {}, action: CountriesActions): CountriesState {
  switch (action.type) {
    case CountriesActionTypes.LoadCountries:
      return {
        ...state,
        loading: true,
        error: false,
      };
    case CountriesActionTypes.LoadCountriesSuccess:
      return {
        ...state,
        list: action.payload,
        loading: false,
        error: false,
      };
    case CountriesActionTypes.LoadCountriesFailure:
      return {
        ...state,
        loading: false,
        error: true,
      };
    default:
      return state;
  }
}

To migrate:

• (minor) update state key names to be more verbose

• introduce initialState

• update createReducer function:

  • pass initialState

  • replace switch with on() functions (state change function)

    • the on(actionCreator, reducer) function takes 2 arguments

      • actionCreator - the reference to the created action

      • reducer - a function that takes the current state and current action and returns the updated state (state, action) => ({...})

import { Action, createReducer, on } from '@ngrx/store';
import {
  requestCountries,
  requestCountriesError,
  requestCountriesSuccess,
} from './countries.actions';

export const STATE_NAME = 'countries';

export interface State {
  countriesResponse?: string[];
  countriesLoading: boolean;
  countriesError: unknown;
}

const initialState: State = {
  countriesResponse: undefined,
  countriesLoading: false,
  countriesError: undefined,
};

const reducer = createReducer(
  initialState,

  on(requestCountries, (state) => ({
    ...state,
    countriesResponse: undefined,
    countriesLoading: true,
    countriesError: undefined,
  })),
  on(requestCountriesError, (state, {error}) => ({
    ...state,
    countriesLoading: false,
    countriesError: error,
  })),
  on(requestCountriesSuccess, (state, action) => ({
    ...state,
    countriesResponse: action.response,
    countriesLoading: false,
  })),
);

export function countriesReducer(state: State | undefined, action: Action) {
  return reducer(state, action);
}

Effects

Before version 7, you can find the usage of ofType function chained directly on this.actions$ (injected Actions). This syntax was dropped in version 7 in favor of ofType operator.

@Injectable()
export class CountriesEffects {
  @Effect()
  someEffect$: Observable<Action> = this.actions$
    .ofType(CountriesActionTypes.LoadCountries)
    .pipe(
      map((response) => new LoadCountriesSuccess(response)),
      catchError(() => of(new LoadCountriesFailure()))
    );

  constructor(private actions$: Actions) {}
}

The old effects use @Effect decorator which was replaced by createEffect() function.

import { Injectable } from '@angular/core';
import { Actions, Effect, ofType } from '@ngrx/effects';
import { Observable, of } from 'rxjs';
import { catchError, map, switchMap } from 'rxjs/operators';
import { CountriesActionTypes, LoadCountriesFailure, LoadCountriesSuccess } from './countries.actions';
import { CountriesService } from './countries.service';

@Injectable()
export class CountriesEffects {
  @Effect()
  load: Observable<LoadCountriesSuccess | LoadCountriesFailure> = this.actions.pipe(
    ofType(CountriesActionTypes.LoadCountries),
    switchMap(() =>
      this.countriesService.list().pipe(
        map((response: string[]) => new LoadCountriesSuccess(response)),
        catchError(() => of(new LoadCountriesFailure()))
      )
    )
  );



  constructor(
    private actions: Actions,
    private countriesService: CountriesService
  ) {
  }
}

To migrate:

• use createEffect() function instead of @Effect() decorator

• use ofType() operator to filter the desired action

• (minor) rename the effect property to be more verbose and end it with $ which indicates that it's an observable

import { Injectable } from '@angular/core';
import { Actions, createEffect, ofType } from '@ngrx/effects';
import { catchError, mergeMap, switchMap } from 'rxjs/operators';
import { of } from 'rxjs';
import {
  requestCountries,
  requestCountriesError,
  requestCountriesSuccess,
} from './countries.actions';
import { CountriesService } from './countries.service';

@Injectable()
export class CountriesEffects {
  requestCountries$ = createEffect(() =>
    this.actions$.pipe(
      ofType(requestCountries),
      mergeMap((action) =>
        this.countriesService.getCountries().pipe(
          switchMap((response) => of(requestCountriesSuccess({response}))),
          catchError((error) => of(requestCountriesError({error})))
        )
      )
    )
  );

  constructor(
    private readonly actions$: Actions,
    private readonly countriesService: CountriesService,
  ) {
  }
}

Selectors

If you were using selectors with props they might also need migration. You have to replace them with factory selectors.

const selectFirstNCountries = createSelector(
    selectCountries,
    (countries, props: { count: number }) => {
      return countries?.slice(count);
    }
);

To migrate:

• create a factory with a parameter instead of a selector with props

const selectFirstNCountries = (count: number) =>
  createSelector(
    selectCountries,
    (countries) => {
      return countries?.slice(count);
    }
  );

Last week, the flickering became a burden. It began to happen very often and was irritating. I googled it, and it turned out, that it's an Ubuntu problem. Here's what I've done.

1. Open file /etc/default/grub.

2. Find GRUB_CMDLINE_LINUX_DEFAULT key and add i915.enable_dc=0 intel_idle.max_cstate=2 i915.enable_psr=0.

   Full line after the changes:

    GRUB_CMDLINE_LINUX_DEFAULT="quiet splash i915.enable_dc=0 intel_idle.max_cstate=2 i915.enable_psr=0"
   

3. Run update-grub (I'm not sure if this step is necessary).

4. Reboot and the flickering is gone.

To be honest, I've no idea what these entries do, but I'm happy that problem is solved :).

To execute tests with code coverage simply run:

npx jest --coverage

The Jest will display a summary table in the shell. By default, the HTML report will be generated in the ./coverage directory. Navigate to ./coverage/lcov-report and open index.html in the browser to view it.

For all available options and configurations refer to the official Jest documentation https://jestjs.io.

Requirements

• NodeJS v16

• NPM v8

• npx

Setup

Install dependencies:

npm i jest@29 @types/jest@29 ts-jest@29 typescript@4.7

Initialize the default ts-jest configuration.

npx ts-jest config:init

Example

Assume, that you have two files:

• functions.ts

• functions.spec.ts

Take a look at the following code. It's supposed to sum all the passed numbers and return a result.

// functions.ts

export const sum = (values: number[]): number  => {
  return values.reduce((previous, current) => previous + current, 0);
}

The test file:

// functions.spec.ts

import { sum } from './functions';


interface Dataset {
  input: number[];
  result: number;
}

const datasets: Dataset[] = [
  {input: [0], result: 0},
  {input: [0, 1], result: 1},
  {input: [2, 6], result: 8},
  {input: [-9, 0], result: -9},
  {input: [-9, -2], result: -11},
  {input: [-9, 100], result: 91},
]

describe('Test sum function', () => {
  it.each(datasets)('dataset: %j', (dataset: Dataset) => {
    const result = sum(...dataset.input);
    expect(result).toBe(dataset.result);
  });
});

Run npx jest --coverage. All tests passed and the coverage shows 100%.

--------------|---------|----------|---------|---------|-------------------
File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------|---------|----------|---------|---------|-------------------
All files     |     100 |      100 |     100 |     100 |                   
 functions.ts |     100 |      100 |     100 |     100 |                   
--------------|---------|----------|---------|---------|-------------------

Next, update the definition of the sum function by introducing argument validation.

// functions.ts

export const sum = (values: number[]): number | never => {
  values.forEach((index, value) => {
    if (!Number.isFinite(value)) {
      throw new Error(`Provided argument at index:${index}, value:${String(value)} is invalid`);
    }
  });

  const result = values.reduce((previous, current) => previous + current, 0);

  if (!Number.isFinite(result)) {
    throw new Error('The result exceeded supported numeric values');
  }

  return result;
}

Run npx jest --coverage. All tests passed, but not all code paths were tested. A quick glimpse at the report shows, that lines 4 and 11 were not executed.

--------------|---------|----------|---------|---------|-------------------
File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------|---------|----------|---------|---------|-------------------
All files     |      80 |        0 |     100 |      75 |                   
 functions.ts |      80 |        0 |     100 |      75 | 4,11              
--------------|---------|----------|---------|---------|-------------------

To test the new code paths create separate tests that cause the exceptions. There are a couple of new cases to cover:

• pass null, undefined, NaN, Infinity or -Infinity

• make the sum of arguments resulting in Infinity or -Infinity

import { sum } from './functions';


interface Dataset {
  input: number[];
  result: number;
}

const datasets: Dataset[] = [
  {input: [0], result: 0},
  {input: [0, 1], result: 1},
  {input: [2, 6], result: 8},
  {input: [-9, 0], result: -9},
  {input: [-9, -2], result: -11},
  {input: [-9, 100], result: 91},
];

function formatMessage(index: number, value: number) {
  return `Invalid argument: index:${index}, value:${String(value)}`;
}

interface ExceptionDataset {
  input: number[],
  errorMessage: string;
}

const exceptionDatasets: ExceptionDataset[] = [
  {
    input: [null],
    errorMessage: formatMessage(0, null)
  },
  {
    input: [undefined],
    errorMessage: formatMessage(0, undefined)
  },
  {
    input: [NaN],
    errorMessage: formatMessage(0, NaN)
  },
  {
    input: [Infinity],
    errorMessage: formatMessage(0, Infinity)
  },
  {
    input: [-Infinity],
    errorMessage: formatMessage(0, -Infinity)
  },
  {
    input: [0, 0, 0, NaN],
    errorMessage: formatMessage(3, NaN)
  },
  {
    input: [1, null, 2],
    errorMessage: formatMessage(1, null)
  },
  {
    input: [1, null, 2, undefined, 3, NaN],
    errorMessage: formatMessage(1, null)
  },
  {
    input: [Math.pow(2, 1023), Math.pow(2, 1023)],
    errorMessage: 'The result exceeded supported numeric values'
  },
  {
    input: [-Math.pow(2, 1023), -Math.pow(2, 1023)],
    errorMessage: 'The result exceeded supported numeric values'
  },
];

describe('Test sum function', () => {
  it.each(datasets)('dataset: %j', (dataset: Dataset) => {
    const result = sum(dataset.input);
    expect(result).toBe(dataset.result);
  });

  it.each(exceptionDatasets)('dataset: %j', (dataset: ExceptionDataset) => {
    expect(() => sum(dataset.input)).toThrow(dataset.errorMessage);
  });
});

Run the tests with coverage and now all the paths are tested.

  Test sum function
    ✓ dataset: {"input":[0],"result":0}
    ✓ dataset: {"input":[0,1],"result":1}
    ✓ dataset: {"input":[2,6],"result":8}
    ✓ dataset: {"input":[-9,0],"result":-9}
    ✓ dataset: {"input":[-9,-2],"result":-11}
    ✓ dataset: {"input":[-9,100],"result":91}
    ✓ dataset: {"input":[null],"errorMessage":"Invalid argument: index:0, value:null"} 
    ✓ dataset: {"input":[null],"errorMessage":"Invalid argument: index:0, value:undefined"}
    ✓ dataset: {"input":[null],"errorMessage":"Invalid argument: index:0, value:NaN"}
    ✓ dataset: {"input":[null],"errorMessage":"Invalid argument: index:0, value:Infinity"} 
    ✓ dataset: {"input":[null],"errorMessage":"Invalid argument: index:0, value:-Infinity"} 
    ✓ dataset: {"input":[0,0,0,null],"errorMessage":"Invalid argument: index:3, value:NaN"}
    ✓ dataset: {"input":[1,null,2],"errorMessage":"Invalid argument: index:1, value:null"}
    ✓ dataset: {"input":[1,null,2,null,3,null],"errorMessage":"Invalid argument: index:1, value:null"} (
    ✓ dataset: {"input":[8.98846567431158e+307,8.98846567431158e+307],"errorMessage":"The result exceeded supported numeric values"} 
    ✓ dataset: {"input":[-8.98846567431158e+307,-8.98846567431158e+307],"errorMessage":"The result exceeded supported numeric values"} 

--------------|---------|----------|---------|---------|-------------------
File          | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s 
--------------|---------|----------|---------|---------|-------------------
All files     |     100 |      100 |     100 |     100 |                   
 functions.ts |     100 |      100 |     100 |     100 |                   
--------------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests:       16 passed, 16 total

A quick note about %j formatting. Due to the fact, that the value is converted to JSON we lose some details. Since the JSON format doesn't support values like NaN, undefined or Infinity they are all converted to null. Take a look at the message:

dataset: {"input":[null],"errorMessage":"Invalid argument: index:0, value:undefined"}

The input is [null] but the value in the error message is undefined. So the input's [null] was originally [undefined] but the information was lost during the conversion. In the message, you can see index:0, value:undefined" because that message was generated manually while the dataset was built. Since it's sufficient for this article, you should consider using a different approach to formatting when writing your tests. This might save you some headaches in the future.

Summary

In this article, I've shown you how to use code coverage and how can it be useful. When your application and the team grow bigger, and the code becomes more complex, the usage of code coverage becomes the natural part of the testing process.

This series will be based on the black box testing methodology. What does that even mean? It means that there is input data provided, then internal processing occurs (a.k.a. black box) and results are produced. The tester is not aware of how the internals work but only knows what the app should do.

input -> [ black box ] -> output

Take a look at a simple web page.

<input type="text">
<button>Add</button>

<table>
    <thead>
        <th>value</th>
    </thead>
    <tbody></tbody>
</table>

As a tester I know that:

• when I fill the input field (input)

• and click Add button (input)

• it should block the input field and the button (output)

• send HTTP request (output)

• add new a new record to the table (output)

• clear input field data (output)

• unblock the input field and the button (output)

I don't care how the app is going to do all that stuff, but I do care about the user interface and sent requests. And that's what can and should be tested.

The tools

Requirements

• node 16

• npm 8

• npx

Setup

The series will be using Jest as the default testing framework. Jest is a fast, widely used and well-documented testing framework. The documentation can be found here: https://jestjs.io. For testing typescript files ts-jest library is required.

Initialize npm with default settings.

npm init -y

Install required dependencies. For testing: jest and ts-jest. For compilation: typescript. For observables: RxJS

npm i jest@29 @types/jest@29 ts-jest@29 typescript@4.7 rxjs@7

Initialize the default ts-jest configuration.

npx ts-jest config:init

A simple test

Assume you want to test the following class:

class Formatter {
  whitespaceToUnderscore(input: string): string {
    return input.split('').join('_');
  }
}

So the test might look like this:

describe('Test Formatter', () => {
  let formatter: Formatter;

  beforeAll(() => {
    formatter = new Formatter();
  });

  it('should convert "This is and example input" to "This_is_and_example_input"', () => {
    expect(formatter.whitespaceToUnderscore('This is and example input')).toBe('This_is_and_example_input');
  });
});

Let's break it down.

• The describe is a block that groups the related tests or other describe blocks,

• The beforeAll is a block that is executed once in the describe block. Since you don't want to create Formatter instance each time it's more performant just to create it once.

• The it (a.k.a. test) is a block that contains expectations (preferably one expectation per it block),

• The expect is a function that takes input (i.e. the actual result of a method call). Next, it is chained with the matcher. The matcher is a function that takes a value, that you expect to receive and compares it with expect's argument. In this particular case, it's toBe matcher, which is used for comparing primitive types.

Jest basics

Primitives

To test primitives it's enough to use toBe matcher.

const inputString = 'my example';
const inputFloat = 512.1241;
const inputInteger = 999;
const inputBoolean = false;
const inputNull = null;
const inputUndefined = undefined;
const inputNaN = NaN;


describe('Test primitives', () => {

  it('should test string', () => {
    expect(inputString).toBe('my example');
  });

  it('should test float', () => {
    expect(inputFloat).toBe(512.1241);
  });

  it('should test integer', () => {
    expect(inputInteger).toBe(999);
  });

  it('should test boolean', () => {
    expect(inputBoolean).toBe(false);
  });

  it('should test null', () => {
    expect(inputNull).toBe(null);
  });

  it('should test undefined', () => {
    expect(inputUndefined).toBe(undefined);
  });

  it('should test NaN', () => {
    expect(inputNaN).toBe(NaN);
  });
});

When the value doesn't matter, but you need to check whether it's a false or true when compared to a boolean, use toBeFalsy() or toBeTruthy();

const inputString = 'my example';
const inputEmptyString = '';
const inputZeroInteger = 0;
const inputZeroFloat = 0.0;
const inputFloat = 512.1241;
const inputInteger = 999;
const inputBooleanFalse = false;
const inputBooleanTrue = true;
const inputNull = null;
const inputUndefined = undefined;
const inputNaN = NaN;


describe('Test primitives', () => {

  it('should test string', () => {
    expect(inputString).toBeTruthy();
    expect(inputEmptyString).toBeFalsy();
  });

  it('should test float', () => {
    expect(inputFloat).toBeTruthy();
    expect(inputZeroFloat).toBeFalsy();
  });

  it('should test integer', () => {
    expect(inputInteger).toBeTruthy();
    expect(inputZeroInteger).toBeFalsy();
  });

  it('should test boolean', () => {
    expect(inputBooleanFalse).toBeFalsy();
    expect(inputBooleanTrue).toBeTruthy();
  });

  it('should test null', () => {
    expect(inputNull).toBeFalsy();
  });

  it('should test undefined', () => {
    expect(inputUndefined).toBeFalsy();
  });

  it('should test NaN', () => {
    expect(inputNaN).toBeFalsy();
  });
});

For NaN, null and undefined there are corresponding matchers toBeNan(), toBeNull() and toBeUndefined(). It's the same as using toBe() matcher, but more verbose.

const inputNull = null;
const inputUndefined = undefined;
const inputNaN = NaN;


describe('Test primitives', () => {

  it('should test null', () => {
    expect(inputNull).toBeNull();
  });

  it('should test undefined', () => {
    expect(inputUndefined).toBeUndefined();
  });

  it('should test NaN', () => {
    expect(inputNaN).toBeNaN();
  });
});

Arrays

To deeply compare arrays use toEqual() matcher.

const inputEmptyArray = [];
const inputSimpleArray = [1, '2'];
const inputSparseArray = [undefined, 1, undefined, '2'];
const inputNestedArray = [1, '2', ['33', {color: '#fff'}]];


describe('Test array equality', () => {

  it('should test empty array', () => {
    expect(inputEmptyArray).toEqual([]);
  });

  it('should test simple array', () => {
    expect(inputSimpleArray).toEqual([1, '2']);
  });

  it('should test sparse array', () => {
    expect(inputSparseArray).toEqual([undefined, 1, undefined, '2']);
  });

  it('should test nested array', () => {
    expect(inputNestedArray).toEqual([1, '2', ['33', {color: '#fff'}]]);
  });
});

Objects and classes

To deeply compare objects use toEqual() matcher.

const inputEmptyObject = {};
const inputSimpleObject = {color: '#fff'};
const inputSparseObject = {color: '#fff', border: undefined};
const inputNestedObject = {color: '#fff', margin: {top: '25px', left: '5px'}};


describe('Test object equality', () => {

  it('should test empty object', () => {
    expect(inputEmptyObject).toEqual({});
  });

  it('should test simple object', () => {
    expect(inputSimpleObject).toEqual({color: '#fff'});
  });

  it('should test sparse object', () => {
    expect(inputSparseObject).toEqual({color: '#fff', border: undefined});
  });

  it('should test nested object', () => {
    expect(inputNestedObject).toEqual({color: '#fff', margin: {top: '25px', left: '5px'}});
  });
});

To check whether an object is an instance of a certain class use toBeInstanceOf() matcher.

class ExampleClass {}


describe('Test class instance', () => {
  it('should test empty object', () => {
    const myClass = new ExampleClass();
    expect(myClass).toBeInstanceOf(ExampleClass);
  });
});

Method calls

To track the method calls you need to use a spy. By default, the spied method will be executed normally as it's defined in the code. The first parameter for jest.spyOn() is a class instance. The second is the name of the tracked method.

class Logger {
  log(data: unknown): void {
    ...
  }
}

logger = new Logger();
jest.spyOn(logger, 'log');

When spies are set, you can use specific matchers to check how or if at all, all the methods were called.

To check only if a method was called, use toHaveBeenCalled() matcher.

expect(logger.log).toHaveBeenCalled();

To check if a method was called and returned a specific value, use toHaveReturnedWith() matcher.

expect(headphones.getVolume).toHaveReturnedWith(0.5);

If a method is called multiple times, you can verify all consecutive calls by using toHaveBeenNthCalledWith(). The first argument is the number of the consecutive call, the second is the expected result.

expect(logger.log).toHaveBeenNthCalledWith(1, {text: 'message-1'});
expect(logger.log).toHaveBeenNthCalledWith(2, {text: 'message-2'});
expect(logger.log).toHaveBeenNthCalledWith(3, {text: 'message-3'});

Below you can find a fully working example.

import { Subject } from 'rxjs';

class Headphones {
  private readonly maxVolume = 1;
  private readonly minVolume = 0;
  private volume = 0.5;
  private volumeSubject = new Subject<number>();
  readonly volumeChanges$ = this.volumeSubject.asObservable();

  volumeUp(): void {
    this.changeVolume(0.1);
  }

  volumeDown(): void {
    this.changeVolume(-0.1);
  }

  getVolume(): number {
    return this.volume;
  }

  private changeVolume(value: number): void {
    this.volume = this.calculateVolumeLevel(value);
    this.volumeSubject.next(this.volume);
  }

  private calculateVolumeLevel(value: number): number {
    let updatedVolume = this.volume + value;

    if (updatedVolume < this.minVolume) {
      return this.minVolume;
    }

    if (updatedVolume > this.maxVolume) {
      return this.maxVolume;
    }

    return updatedVolume;
  }
}

class Logger {
  log(data: unknown): void {
    // ...
  }
}


describe('Test class calls', () => {
  let headphones: Headphones;
  let logger: Logger;

  beforeEach(() => {
    headphones = new Headphones();
    logger = new Logger();
    jest.spyOn(headphones, 'getVolume');
    jest.spyOn(logger, 'log');
  });

  it('getVolume should be called and return 0.5', () => {
    headphones.getVolume();
    expect(headphones.getVolume).toHaveReturnedWith(0.5);
  });

  it('should call logger once upon a volume change', () => {
    headphones.volumeChanges$.subscribe(volume => {
      const data = {event: 'VolumeChange', value: volume};
      logger.log(data);
    });

    headphones.volumeUp();
    expect(logger.log).toHaveBeenCalled();
  });

  it('should call logger with payload once upon a volume change', () => {
    headphones.volumeChanges$.subscribe(volume => {
      const data = {event: 'VolumeChange', value: volume};
      logger.log(data);
    });

    headphones.volumeUp();
    const expected = {event: 'VolumeChange', value: 0.6};
    expect(logger.log).toHaveBeenCalledWith(expected)
  });

  it('should call logger 3 times upon a volume changes', () => {
    headphones.volumeChanges$.subscribe(volume => {
      const data = {event: 'VolumeChange', value: volume};
      logger.log(data);
    });

    headphones.volumeUp();
    headphones.volumeUp();
    headphones.volumeDown();
    const expected1 = {event: 'VolumeChange', value: 0.6};
    expect(logger.log).toHaveBeenNthCalledWith(1, expected1);
    const expected2 = {event: 'VolumeChange', value: 0.7};
    expect(logger.log).toHaveBeenNthCalledWith(2, expected2);
    const expected3 = {event: 'VolumeChange', value: 0.6};
    expect(logger.log).toHaveBeenNthCalledWith(3, expected3);
  });
});

Exceptions (errors)

There are a few basic ways to test whether an exception was thrown:

• test if any exception was thrown

• test if a certain exception class was thrown

• test if an exception is an object with certain message property

• test if a string was thrown

To test an exception, you have to wrap the code in a function, otherwise, the exception will not be caught and the assertion will fail. Instead of

expect(throwInvalidNumberException()).toThrow();

you need to use something like

expect(() => throwInvalidNumberException()).toThrow();

Let's assume that all tests contain the following declarations:

class AppException extends Error {

}

class InvalidNumberException extends AppException {

}

const throwInvalidNumberException = (): never => {
  throw new InvalidNumberException('Provided number is invalid');
}

const throwGenericError = (): never => {
  throw new Error('Unknown error');
}

const throwString = (): never => {
  throw 'Unexpected error';
}

To test if any exception was thrown it's enough to use toThrow() matcher without any argument.

describe('Test any exception', () => {
  it('should throw InvalidNumberException', () => {
    expect(() => throwInvalidNumberException()).toThrow();
  });

  it('should throw generic error', () => {
    expect(() => throwGenericError()).toThrow();
  });

  it('should throw string', () => {
    expect(() => throwString()).toThrow();
  });
});

To test if an exception is an instance of a certain class use toThrow() matcher passing a class reference as an argument.

describe('Test exception class', () => {
  it('should throw InvalidNumberException', () => {
    expect(() => throwInvalidNumberException()).toThrow(InvalidNumberException);
  });

  it('should throw AppException', () => {
    expect(() => throwInvalidNumberException()).toThrow(AppException);
  });

  it('should throw generic error', () => {
    expect(() => throwGenericError()).toThrow(Error);
  });
});

To test if an exception is a string or an object with message property also use toThrow() matcher passing a string containing the expected error message.

describe('Test exception message', () => {
  it('should throw "Provided number is invalid" message', () => {
    expect(() => throwInvalidNumberException()).toThrow('Provided number is invalid');
  });

  it('should throw "Unknown error', () => {
    expect(() => throwGenericError()).toThrow('Unknown error');
  });

  it('should throw "Unexpected error"', () => {
    expect(() => throwString()).toThrow('Unexpected error');
  });
});

Asynchronous code

The basic way of testing asynchronous code is quite straightforward.

To test a resolved promise:

• define the it callback as async function

• await for a promise resolution

• test the results

const resolvePromise = async (): Promise<string> => {
  return 'resolved';
}

it('should await for a promise', async () => {
  const result = await resolvePromise();
  expect(result).toBe('resolved');
});

To test a rejected promise you need to take some extra steps:

• define the it callback as async function

• since there will be a try/catch block, add expect.assertions() call. It takes a number and verifies that this number of assertions will be called during the test

• await for a promise in try block

• catch the error in catch block

• check the error instance

const rejectPromise = async (): Promise<never> => {
  throw new Error('rejected');
}

it('should await for a rejected promise', async () => {
  expect.assertions(1);

  try {
    await rejectPromise();
  } catch (error) {
    expect(error).toBeInstanceOf(Error);
  }
});

Datasets

Let's assume, that you have the following code. findMultipleEntries function takes two arguments: an array of entries and an array of keys and returns entries matching the keys.

interface HasId {
  id: string;
}

type Nullable<T> = T | null | undefined;

const findMultipleEntries = <T extends HasId>(entries: Nullable<T[]>, keys: Nullable<string[]>): T[] => {
  if (!entries || !keys) {
    return [];
  }

  return entries.filter(entry => keys.includes(entry.id));
}

Instead of writing multiple duplicated tests, you might use the datasets. The dataset should at least contain all values that will be used inside test calls and also an expected result.

To define the dataset use the interface Dataset with 3 self-explanatory properties.

interface Dataset {
  entries: Nullable<any[]>;
  keys: Nullable<any[]>;
  expected: any[]
};

const datasets: Dataset[] = [
  {
    entries: null,
    keys: null,
    expected: []
  },
  {
    entries: null,
    keys: undefined,
    expected: []
  },
  {
    entries: undefined,
    keys: null,
    expected: []
  },
  {
    entries: undefined,
    keys: undefined,
    expected: []
  },
  {
    entries: [],
    keys: [],
    expected: []
  },
  {
    entries: [
      {id: 'k1', value: 1},
      {id: 'k3', value: 3},
      {id: 'k5', value: 5},
    ],
    keys: [],
    expected: []
  },
  {
    entries: [],
    keys: ['k1', 'k5', 'k6'],
    expected: []
  },
  {
    entries: [
      {id: 'k22', value: 22},
      {id: 'k23', value: 23},
    ],
    keys: ['k91', 'k95'],
    expected: []
  },
  {
    entries: [
      {id: 'k1', value: 1},
      {id: 'k3', value: 3},
      {id: 'k5', value: 5},
    ],
    keys: ['k1', 'k5', 'k6'],
    expected: [{id: 'k1', value: 1},
      {id: 'k5', value: 5},]
  },
];

To utilize datasets use it.each (or describe.each if executing multiple tests on a dataset) call. The %j is the first (and the only) positional parameter, that will convert a dataset (first and the only argument) to JSON. There are many other formatting options, so should you need more details, please refer to the official Jest documentation.

describe('Test findMultipleEntries', () => {
  it.each(datasets)('dataset: %j', (dataset: Dataset) => {
    const actualResult = findMultipleEntries(dataset.entries, dataset.keys);
    expect(actualResult).toEqual(dataset.expected);
  });
});

The output should look similar to the following:

  Test findMultipleEntries
    ✓ dataset: {"entries":null,"keys":null,"expected":[]}
    ✓ dataset: {"entries":null,"expected":[]}
    ✓ dataset: {"keys":null,"expected":[]}
    ✓ dataset: {"expected":[]}
    ✓ dataset: {"entries":[],"keys":[],"expected":[]}
    ✓ dataset: {"entries":[{"id":"k1","value":1},{"id":"k3","value":3},{"id":"k5","value":5}],"keys":[],"expected":[]}
    ✓ dataset: {"entries":[],"keys":["k1","k5","k6"],"expected":[]}
    ✓ dataset: {"entries":[{"id":"k22","value":22},{"id":"k23","value":23}],"keys":["k91","k95"],"expected":[]}
    ✓ dataset: {"entries":[{"id":"k1","value":1},{"id":"k3","value":3},{"id":"k5","value":5}],"keys":["k1","k5","k6"],"expected":[{"id":"k1","value":1},{"id":"k5","value":5}]}

Test Suites: 1 passed, 1 total
Tests:       9 passed, 9 total

Naming

My preferred way of naming tests is a structure of very long sentences

Imagine a simple application, that displays a client list. What would the flow look like?

• the user enters the page

  • the skeleton is displayed

  • header is displayed

  • API clients request is made

    • request error occurs

      • an error is displayed

    • request is successful

      • the client list is displayed

  • add client button is displayed

    • user clicks the button

      • user is redirected to new URL

The tests should look similar to this structure. For example:

describe('When user enters the page', () => {

  it('should display page header', () => {});

  it('should display skeleton', () => {});

  it('should not display client list', () => {});

  it('should display "add user" button', () => {});

  it('should not display error', () => {});

  it('should send clients request', () => {});

  describe('and user clicks "add user" button', () => {
    it('should redirect to "/create" url', () => {});
  });

  describe('and clients request fails', () => {
    it('should display error', () => {});

    it('should not display skeleton', () => {});

    it('should not display client list', () => {});
  });

  describe('and clients request is successful', () => {
    it('should not display error', () => {});

    it('should not display skeleton', () => {});

    it('should display client list', () => {});
  });
});

When you run this test suite, you'll get this output:

When user enters the page
  ✓ should display page header
  ✓ should display skeleton
  ✓ should not display client list
  ✓ should display "add user" button
  ✓ should not display error
  ✓ should send clients request
  and user clicks "add user" button
    ✓ should redirect to "/create" url
  and clients request fails
    ✓ should display error
    ✓ should not display skeleton
    ✓ should not display client list
  and clients request is successful
    ✓ should not display error
    ✓ should not display skeleton
    ✓ should display client list

These sentences are easy to read and are quite verbose. Just a quick look at the results and you already know what's going on.

When your application grows bigger, and so do the tests, sometimes it's not always possible to keep that structure. At some point, you're going to add some nested blocks like describe('Testing pagination') that logically separate parts of the application.

There are of course many other best practices and guidelines on how to name your tests. Remember that the tests are mainly for us, the developers.

Footnote

This article just scratched the surface of testing. Jest itself is much more extensive and can be supplemented by extra libraries and plugins. And of course, there are many other frameworks, tools and methodologies to explore. As always - you have to find what works for you.