@orchestrator/ngx-testing

NgxTesting

Testing utilities for Angular projects

npm install -D @orchestrator/ngx-testing@next

Why?

Because you want to test your code and not writing testing code to test your code.

How?

This utility library will generate a wrapping (host) component for your component under test and bind all the @Inputs and @Outputs for you so you can interact with component as the consumer will.

That also means that you do not need to worry about life-cycle hooks hassle because auto generated code will move this bit to Angular itself.

Getting started

Configuring mocking (Optional)

Library will initialize every @Output property on host component to a mock so you have a nice time checking if the output was triggered.

By default it is simply a NOOP function (that does nothing).

But which testing tool do you use is up to you so you have to tell us what to use by writing next code in your main test configuration file:

import { setOutputMock } from '@orchestrator/ngx-testing';

// Use this for Jasmine Spies
setOutputMock(() => jasmine.createSpy());

// Or this for Jest Mocks
setOutputMock(() => jest.fn());

// Optionally you can provide typings for mocks
declare module '@orchestrator/ngx-testing' {
  // Use this for Jasmine Spies
  interface OutputMock<T> extends jasmine.Spy {}

  // Or this for Jest Mocks
  interface OutputMock<T> extends jest.Mock {}
  // <T> here represents actual type from `EventEmitter<T>`
  // You can use it if you need it
}

Testing component

Let's see how to test a component with this library:

import { TestBed } from '@angular/core/testing';
import { getTestingForComponent } from '@orchestrator/ngx-testing';

// This is component under test
@Component({ selector: 'my-component', template: 'Text is: {{text}}' })
class MyComponent implements OnInit, OnChanges {
  @Input() text: string;
}

describe('MyComponent', () => {
  // This will generate host component and module with everything required
  const { testModule, createComponent } = getTestingForComponent(MyComponent);

  // Configure testing module by importing generated module before
  beforeEach(() => TestBed.configureTestingModule({ imports: [testModule] }));

  it('should render input text', async () => {
    // Now simply create host component
    // It is async because it performs compilation of templates
    // And returns a special Host service that contains a bunch of useful stuff
    const host = await createComponent();

    // To interact with your component Inputs/Outputs use `hostComponent` property
    // It's an instance of generated host component that binds all Inputs and Outputs
    host.hostComponent.text = 'something';
    // This is an alias to fixture.detectChanges()
    // Fixture can be used as well and is available as `fixture` property
    host.detectChanges();

    // htmlElement is simply an HTMLElement of rendered component under test
    expect(host.htmlElement.textContent).toBe(`Text is: something`);
  });
});

For more examples visit example-component.spec.ts.

Providing custom config for NgModule

Sometimes you will need to provide extra config for your component/directive under test so it can work in isolated unit test. You can do this like so:

import { getTestingForComponent, getTestingForDirective } from '@orchestrator/ngx-testing';

// For component
getTestingForComponent(YourComponent, { ngModule: { imports: [...], providers: [...] } });

// For directive
getTestingForDirective(YourDirective, { ngModule: { imports: [...], providers: [...] } });

NOTE: ngModule prop in second argument is default config for @NgModule.

Initial Inputs

You can set initial inputs to component when creating it:

const host = createComponent({ prop1: 'value', prop2: 'value2' });

Also while setting initial inputs you may trigger Change Detection so that the view will immediately render with the inputs:

const host = createComponent({ ...inputs }, true);

Setting Inputs

During test you may set inputs using utility method setInputs():

host.setInputs({ prop1: 'value1', prop2: 'value2' });

Also while setting inputs you may trigger Change Detection so that the view will immediately render with the inputs:

host.setInputs({ ...inputs }, true);

Build

Run ng build to build the project. The build artifacts will be stored in the dist/ directory. Use the --prod flag for a production build.

Running unit tests

Run ng test to execute the unit tests via Karma.

Running end-to-end tests

Run ng e2e to execute the end-to-end tests via Protractor.