linkTesting

This guide offers tips and techniques for unit and integration testing Angular applications.

The guide presents tests of a sample CLI application that is much like the Tour of Heroes tutorial. The sample application and all tests in this guide are available for inspection and experimentation:

• Sample app / download example
• Tests / download example

linkSetup

The Angular CLI downloads and install everything you need to test an Angular application with the Jasmine test framework.

The project you create with the CLI is immediately ready to test. Just run this one CLI command:

      
        content_copy
      
      ng test
    

The ng test command builds the app in watch mode, and launches the karma test runner.

The console output looks a bit like this:

      
        content_copy
      
      10% building modules 1/1 modules 0 active
...INFO [karma]: Karma v1.7.1 server started at http://0.0.0.0:9876/
...INFO [launcher]: Launching browser Chrome ...
...INFO [launcher]: Starting browser Chrome
...INFO [Chrome ...]: Connected on socket ... 
Chrome ...: Executed 3 of 3 SUCCESS (0.135 secs / 0.205 secs)
    

The last line of the log is the most important. It shows that Karma ran three tests that all passed.

A chrome browser also opens and displays the test output in the "Jasmine HTML Reporter" like this.

Most people find this browser output easier to read than the console log. You can click on a test row to re-run just that test or click on a description to re-run the tests in the selected test group ("test suite").

Meanwhile, the ng test command is watching for changes.

To see this in action, make a small change to app.component.ts and save. The tests run again, the browser refreshes, and the new test results appear.

linkConfiguration

The CLI takes care of Jasmine and karma configuration for you.

You can fine-tune many options by editing the karma.conf.js file in the project root folder and the test.ts file in the src/ folder.

The karma.conf.js file is a partial karma configuration file. The CLI constructs the full runtime configuration in memory,based on application structure specified in the .angular-cli.json file, supplemented by karma.conf.js.

Search the web for more details about Jasmine and karma configuration.

linkOther test frameworks

You can also unit test an Angular app with other testing libraries and test runners. Each library and runner has its own distinctive installation procedures, configuration, and syntax.

Search the web to learn more.

linkTest file name and location

Look inside the src/app folder.

The CLI generated a test file for the AppComponent named app.component.spec.ts.

The app.component.ts and app.component.spec.ts files are siblings in the same folder. The root file names (app.component) are the same for both files.

Adopt these two conventions in your own projects for every kind of test file.

linkService Tests

Services are often the easiest files to unit test. Here are some synchronous and asynchronous unit tests of the ValueService written without assistance from Angular testing utilities.

      
        content_copy
      
      // Straight Jasmine testing without Angular's testing support
describe('ValueService', () => {
  let service: ValueService;
  beforeEach(() => { service = new ValueService(); });

  it('#getValue should return real value', () => {
    expect(service.getValue()).toBe('real value');
  });

  it('#getObservableValue should return value from observable',
    (done: DoneFn) => {
    service.getObservableValue().subscribe(value => {
      expect(value).toBe('observable value');
      done();
    });
  });

  it('#getPromiseValue should return value from a promise',
    (done: DoneFn) => {
    service.getPromiseValue().then(value => {
      expect(value).toBe('promise value');
      done();
    });
  });
});
    

linkServices with dependencies

Services often depend on other services that Angular injects into the constructor. In many cases, it easy to create and inject these dependencies by hand while calling the service's constructor.

The MasterService is a simple example:

      
        content_copy
      
      @Injectable()
export class MasterService {
  constructor(private valueService: ValueService) { }
  getValue() { return this.valueService.getValue(); }
}
    

MasterService delegates its only method, getValue, to the injected ValueService.

Here are several ways to test it.

      
        content_copy
      
      describe('MasterService without Angular testing support', () => {
  let masterService: MasterService;

  it('#getValue should return real value from the real service', () => {
    masterService = new MasterService(new ValueService());
    expect(masterService.getValue()).toBe('real value');
  });

  it('#getValue should return faked value from a fakeService', () => {
    masterService = new MasterService(new FakeValueService());
    expect(masterService.getValue()).toBe('faked service value');
  });

  it('#getValue should return faked value from a fake object', () => {
    const fake =  { getValue: () => 'fake value' };
    masterService = new MasterService(fake as ValueService);
    expect(masterService.getValue()).toBe('fake value');
  });

  it('#getValue should return stubbed value from a spy', () => {
    // create `getValue` spy on an object representing the ValueService
    const valueServiceSpy =
      jasmine.createSpyObj('ValueService', ['getValue']);

    // set the value to return when the `getValue` spy is called.
    const stubValue = 'stub value';
    valueServiceSpy.getValue.and.returnValue(stubValue);

    masterService = new MasterService(valueServiceSpy);

    expect(masterService.getValue())
      .toBe(stubValue, 'service returned stub value');
    expect(valueServiceSpy.getValue.calls.count())
      .toBe(1, 'spy method was called once');
    expect(valueServiceSpy.getValue.calls.mostRecent().returnValue)
      .toBe(stubValue);
  });
});
    

The first test creates a ValueService with new and passes it to the MasterService constructor.

However, injecting the real service rarely works well as most dependent services are difficult to create and control.

Instead you can mock the dependency, use a dummy value, or create a spy on the pertinent service method.

These standard testing techniques are great for unit testing services in isolation.

However, you almost always inject service into application classes using Angular dependency injection and you should have tests that reflect that usage pattern. Angular testing utilities make it easy to investigate how injected services behave.

linkTesting services with the TestBed

Your app relies on Angular dependency injection (DI) to create services. When a service has a dependent service, DI finds or creates that dependent service. And if that dependent service has its own dependencies, DI finds-or-creates them as well.

As service consumer, you don't worry about any of this. You don't worry about the order of constructor arguments or how they're created.

As a service tester, you must at least think about the first level of service dependencies but you can let Angular DI do the service creation and deal with constructor argument order when you use the TestBed testing utility to provide and create services.

linkAngular TestBed

The TestBed is the most important of the Angular testing utilities. The TestBed creates a dynamically-constructed Angular test module that emulates an Angular @NgModule.

The TestBed.configureTestingModule() method takes a metadata object that can have most of the properties of an @NgModule.

To test a service, you set the providers metadata property with an array of the services that you'll test or mock.

      
        content_copy
      
      let service: ValueService;

beforeEach(() => {
  TestBed.configureTestingModule({ providers: [ValueService] });
});
    

Then inject it inside a test by calling TestBed.get() with the service class as the argument.

      
        content_copy
      
      it('should use ValueService', () => {
  service = TestBed.get(ValueService);
  expect(service.getValue()).toBe('real value');
});
    

Or inside the beforeEach() if you prefer to inject the service as part of your setup.

      
        content_copy
      
      beforeEach(() => {
  TestBed.configureTestingModule({ providers: [ValueService] });
  service = TestBed.get(ValueService);
});
    

When testing a service with a dependency, provide the mock in the providers array.

In the following example, the mock is a spy object.

      
        content_copy
      
      let masterService: MasterService;
let valueServiceSpy: jasmine.SpyObj<ValueService>;

beforeEach(() => {
  const spy = jasmine.createSpyObj('ValueService', ['getValue']);

  TestBed.configureTestingModule({
    // Provide both the service-to-test and its (spy) dependency
    providers: [
      MasterService,
      { provide: ValueService, useValue: spy }
    ]
  });
  // Inject both the service-to-test and its (spy) dependency
  masterService = TestBed.get(MasterService);
  valueServiceSpy = TestBed.get(ValueService);
});
    

The test consumes that spy in the same way it did earlier.

      
        content_copy
      
      it('#getValue should return stubbed value from a spy', () => {
  const stubValue = 'stub value';
  valueServiceSpy.getValue.and.returnValue(stubValue);

  expect(masterService.getValue())
    .toBe(stubValue, 'service returned stub value');
  expect(valueServiceSpy.getValue.calls.count())
    .toBe(1, 'spy method was called once');
  expect(valueServiceSpy.getValue.calls.mostRecent().returnValue)
    .toBe(stubValue);
});
    

linkTesting without beforeEach()

Most test suites in this guide call beforeEach() to set the preconditions for each it() test and rely on the TestBed to create classes and inject services.

There's another school of testing that never calls beforeEach() and and prefers to create classes explicitly rather than use the TestBed.

Here's how you might rewrite one of the MasterService tests in that style.

Begin by putting re-usable, preparatory code in a setup function instead of beforeEach().

      
        content_copy
      
      function setup() {
  const valueServiceSpy =
    jasmine.createSpyObj('ValueService', ['getValue']);
  const stubValue = 'stub value';
  const masterService = new MasterService(valueServiceSpy);

  valueServiceSpy.getValue.and.returnValue(stubValue);
  return { masterService, stubValue, valueServiceSpy };
}
    

The setup() function returns an object literal with the variables, such as masterService, that a test might reference. You don't define semi-global variables (e.g., let masterService: MasterService) in the body of the describe().

Then each test invokes setup() in its first line, before continuing with steps that manipulate the test subject and assert expectations.

      
        content_copy
      
      it('#getValue should return stubbed value from a spy', () => {
  const { masterService, stubValue, valueServiceSpy } = setup();
  expect(masterService.getValue())
    .toBe(stubValue, 'service returned stub value');
  expect(valueServiceSpy.getValue.calls.count())
    .toBe(1, 'spy method was called once');
  expect(valueServiceSpy.getValue.calls.mostRecent().returnValue)
    .toBe(stubValue);
});
    

Notice how the test uses destructuring assignment to extract the setup variables that it needs.

      
        content_copy
      
      const { masterService, stubValue, valueServiceSpy } = setup();
    

Many developers feel this approach is cleaner and more explicit than the traditional beforeEach() style.

Although this testing guide follows the tradition style and the default CLI schematics generate test files with beforeEach() and TestBed, feel free to adopt this alternative approach in your own projects.

linkTesting HTTP services

Data services that make HTTP calls to remote servers typically inject and delegate to the Angular HttpClient service for XHR calls.

You can test a data service with an injected HttpClient spy as you would test any service with a dependency.

      
        content_copy
      
      let httpClientSpy: { get: jasmine.Spy };
let heroService: HeroService;

beforeEach(() => {
  // TODO: spy on other methods too
  httpClientSpy = jasmine.createSpyObj('HttpClient', ['get']);
  heroService = new HeroService(<any> httpClientSpy);
});

it('should return expected heroes (HttpClient called once)', () => {
  const expectedHeroes: Hero[] =
    [{ id: 1, name: 'A' }, { id: 2, name: 'B' }];

  httpClientSpy.get.and.returnValue(asyncData(expectedHeroes));

  heroService.getHeroes().subscribe(
    heroes => expect(heroes).toEqual(expectedHeroes, 'expected heroes'),
    fail
  );
  expect(httpClientSpy.get.calls.count()).toBe(1, 'one call');
});

it('should return an error when the server returns a 404', () => {
  const errorResponse = new HttpErrorResponse({
    error: 'test 404 error',
    status: 404, statusText: 'Not Found'
  });

  httpClientSpy.get.and.returnValue(asyncError(errorResponse));

  heroService.getHeroes().subscribe(
    heroes => fail('expected an error, not heroes'),
    error  => expect(error.message).toContain('test 404 error')
  );
});
    

linkHttpClientTestingModule

Extended interactions between a data service and the HttpClient can be complex and difficult to mock with spies.

The HttpClientTestingModule can make these testing scenarios more manageable.

While the code sample accompanying this guide demonstrates HttpClientTestingModule, this page defers to the Http guide, which covers testing with the HttpClientTestingModule in detail.

linkComponent Test Basics

A component, unlike all other parts of an Angular application, combines an HTML template and a TypeScript class. The component truly is the template and the class working together. and to adequately test a component, you should test that they work together as intended.

Such tests require creating the component's host element in the browser DOM, as Angular does, and investigating the component class's interaction with the DOM as described by its template.

The Angular TestBed facilitates this kind of testing as you'll see in the sections below. But in many cases, testing the component class alone, without DOM involvement, can validate much of the component's behavior in an easier, more obvious way.

linkComponent class testing

Test a component class on its own as you would test a service class.

Consider this LightswitchComponent which toggles a light on and off (represented by an on-screen message) when the user clicks the button.

      
        content_copy
      
      @Component({
  selector: 'lightswitch-comp',
  template: `
    <button (click)="clicked()">Click me!</button>
    <span>{{message}}</span>`
})
export class LightswitchComponent {
  isOn = false;
  clicked() { this.isOn = !this.isOn; }
  get message() { return `The light is ${this.isOn ? 'On' : 'Off'}`; }
}
    

You might decide only to test that the clicked() method toggles the light's on/off state and sets the message appropriately.

This component class has no dependencies. To test a service with no dependencies, you create it with new, poke at its API, and assert expectations on its public state. Do the same with the component class.

      
        content_copy
      
      describe('LightswitchComp', () => {
  it('#clicked() should toggle #isOn', () => {
    const comp = new LightswitchComponent();
    expect(comp.isOn).toBe(false, 'off at first');
    comp.clicked();
    expect(comp.isOn).toBe(true, 'on after click');
    comp.clicked();
    expect(comp.isOn).toBe(false, 'off after second click');
  });

  it('#clicked() should set #message to "is on"', () => {
    const comp = new LightswitchComponent();
    expect(comp.message).toMatch(/is off/i, 'off at first');
    comp.clicked();
    expect(comp.message).toMatch(/is on/i, 'on after clicked');
  });
});
    

Here is the DashboardHeroComponent from the Tour of Heroes tutorial.

      
        content_copy
      
      export class DashboardHeroComponent {
  @Input() hero: Hero;
  @Output() selected = new EventEmitter<Hero>();
  click() { this.selected.emit(this.hero); }
}
    

It appears within the template of a parent component, which binds a hero to the @Input property and listens for an event raised through the selected @Output property.

You can test that the class code works without creating the the DashboardHeroComponent or its parent component.

      
        content_copy
      
      it('raises the selected event when clicked', () => {
  const comp = new DashboardHeroComponent();
  const hero: Hero = { id: 42, name: 'Test' };
  comp.hero = hero;

  comp.selected.subscribe(selectedHero => expect(selectedHero).toBe(hero));
  comp.click();
});
    

When a component has dependencies, you may wish to use the TestBed to both create the component and its dependencies.

The following WelcomeComponent depends on the UserService to know the name of the user to greet.

      
        content_copy
      
      export class WelcomeComponent  implements OnInit {
  welcome: string;
  constructor(private userService: UserService) { }

  ngOnInit(): void {
    this.welcome = this.userService.isLoggedIn ?
      'Welcome, ' + this.userService.user.name : 'Please log in.';
  }
}
    

You might start by creating a mock of the UserService that meets the minimum needs of this component.

      
        content_copy
      
      class MockUserService {
  isLoggedIn = true;
  user = { name: 'Test User'};
};
    

Then provide and inject both the component and the service in the TestBed configuration.

      
        content_copy
      
      beforeEach(() => {
  TestBed.configureTestingModule({
    // provide the component-under-test and dependent service
    providers: [
      WelcomeComponent,
      { provide: UserService, useClass: MockUserService }
    ]
  });
  // inject both the component and the dependent service.
  comp = TestBed.get(WelcomeComponent);
  userService = TestBed.get(UserService);
});
    

Then exercise the component class, remembering to call the lifecycle hook methods as Angular does when running the app.

      
        content_copy
      
      it('should not have welcome message after construction', () => {
  expect(comp.welcome).toBeUndefined();
});

it('should welcome logged in user after Angular calls ngOnInit', () => {
  comp.ngOnInit();
  expect(comp.welcome).toContain(userService.user.name);
});

it('should ask user to log in if not logged in after ngOnInit', () => {
  userService.isLoggedIn = false;
  comp.ngOnInit();
  expect(comp.welcome).not.toContain(userService.user.name);
  expect(comp.welcome).toContain('log in');
});
    

linkComponent DOM testing

Testing the component class is as easy as testing a service.

But a component is more than just its class. A component interacts with the DOM and with other components. The class-only tests can tell you about class behavior. They cannot tell you if the component is going to render properly, respond to user input and gestures, or integrate with its parent and and child components.

None of the class-only tests above can answer key questions about how the components actually behave on screen.

• Is Lightswitch.clicked() bound to anything such that the user can invoke it?
• Is the Lightswitch.message displayed?
• Can the user actually select the hero displayed by DashboardHeroComponent?
• Is the hero name displayed as expected (i.e, in uppercase)?
• Is the welcome message displayed by the template of WelcomeComponent?

These may not be troubling questions for the simple components illustrated above. But many components have complex interactions with the DOM elements described in their templates, causing HTML to appear and disappear as the component state changes.

To answer these kinds of questions, you have to create the DOM elements associated with the components, you must examine the DOM to confirm that component state displays properly at the appropriate times, and you must simulate user interaction with the screen to determine whether those interactions cause the component to behave as expected.

To write these kinds of test, you'll use additional features of the TestBed as well as other testing helpers.

linkCLI-generated tests

The CLI creates an initial test file for you by default when you ask it to generate a new component.

For example, the following CLI command generates a BannerComponent in the app/banner folder (with inline template and styles):

      
        content_copy
      
      ng generate component banner --inline-template --inline-style --module app
    

It also generates an initial test file for the component, banner-external.component.spec.ts, that looks like this:

      
        content_copy
      
      import { async, ComponentFixture, TestBed } from '@angular/core/testing';
import { BannerComponent } from './banner.component';

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

  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [ BannerComponent ]
    })
    .compileComponents();
  }));

  beforeEach(() => {
    fixture = TestBed.createComponent(BannerComponent);
    component = fixture.componentInstance;
    fixture.detectChanges();
  });

  it('should create', () => {
    expect(component).toBeDefined();
  });
});
    

linkReduce the setup

Only the last three lines of this file actually test the component and all they do is assert that Angular can create the component.

The rest of the file is boilerplate setup code anticipating more advanced tests that might become necessary if the component evolves into something substantial.

You'll learn about these advanced test features below. For now, you can radically reduce this test file to a more manageable size:

      
        content_copy
      
      describe('BannerComponent (minimal)', () => {
  it('should create', () => {
    TestBed.configureTestingModule({
      declarations: [ BannerComponent ]
    });
    const fixture = TestBed.createComponent(BannerComponent);
    const component = fixture.componentInstance;
    expect(component).toBeDefined();
  });
});
    

In this example, the metadata object passed to TestBed.configureTestingModule simply declares BannerComponent, the component to test.

      
        content_copy
      
      TestBed.configureTestingModule({
  declarations: [ BannerComponent ]
});
    

linkcreateComponent()

After configuring TestBed, you call its createComponent() method.

      
        content_copy
      
      const fixture = TestBed.createComponent(BannerComponent);
    

TestBed.createComponent() creates an instance of the BannerComponent, adds a corresponding element to the test-runner DOM, and returns a ComponentFixture.

linkComponentFixture

The ComponentFixture is a test harness for interacting with the created component and its corresponding element.

Access the component instance through the fixture and confirm it exists with a Jasmine expectation:

      
        content_copy
      
      const component = fixture.componentInstance;
expect(component).toBeDefined();
    

linkbeforeEach()

You will add more tests as this component evolves. Rather than duplicate the TestBed configuration for each test, you refactor to pull the setup into a Jasmine beforeEach() and some supporting variables:

      
        content_copy
      
      describe('BannerComponent (with beforeEach)', () => {
  let component: BannerComponent;
  let fixture: ComponentFixture<BannerComponent>;

  beforeEach(() => {
    TestBed.configureTestingModule({
      declarations: [ BannerComponent ]
    });
    fixture = TestBed.createComponent(BannerComponent);
    component = fixture.componentInstance;
  });

  it('should create', () => {
    expect(component).toBeDefined();
  });
});
    

Now add a test that gets the component's element from fixture.nativeElement and looks for the expected text.

      
        content_copy
      
      it('should contain "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  expect(bannerElement.textContent).toContain('banner works!');
});
    

linknativeElement

The value of ComponentFixture.nativeElement has the any type. Later you'll encounter the DebugElement.nativeElement and it too has the any type.

Angular can't know at compile time what kind of HTML element the nativeElement is or if it even is an HTML element. The app might be running on a non-browser platform, such as the server or a Web Worker, where the element may have a diminished API or not exist at all.

The tests in this guide are designed to run in a browser so a nativeElement value will always be an HTMLElement or one of its derived classes.

Knowing that it is an HTMLElement of some sort, you can use the standard HTML querySelector to dive deeper into the element tree.

Here's another test that calls HTMLElement.querySelector to get the paragraph element and look for the banner text:

      
        content_copy
      
      it('should have <p> with "banner works!"', () => {
  const bannerElement: HTMLElement = fixture.nativeElement;
  const p = bannerElement.querySelector('p');
  expect(p.textContent).toEqual('banner works!');
});
    

linkDebugElement

The Angular fixture provides the component's element directly through the fixture.nativeElement.

      
        content_copy
      
      const bannerElement: HTMLElement = fixture.nativeElement;
    

This is actually a convenience method, implemented as fixture.debugElement.nativeElement.

      
        content_copy
      
      const bannerDe: DebugElement = fixture.debugElement;
const bannerEl: HTMLElement = bannerDe.nativeElement;
    

There's a good reason for this circuitous path to the element.

The properties of the nativeElement depend upon the runtime environment. You could be running these tests on a non-browser platform that doesn't have a DOM or whose DOM-emulation doesn't support the full HTMLElement API.

Angular relies on the DebugElement abstraction to work safely across all supported platforms. Instead of creating an HTML element tree, Angular creates a DebugElement tree that wraps the native elements for the runtime platform. The nativeElement property unwraps the DebugElement and returns the platform-specific element object.

Because the sample tests for this guide are designed to run only in a browser, a nativeElement in these tests is always an HTMLElement whose familiar methods and properties you can explore within a test.

Here's the previous test, re-implemented with fixture.debugElement.nativeElement:

      
        content_copy
      
      it('should find the <p> with fixture.debugElement.nativeElement)', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const bannerEl: HTMLElement = bannerDe.nativeElement;
  const p = bannerEl.querySelector('p');
  expect(p.textContent).toEqual('banner works!');
});
    

The DebugElement has other methods and properties that are useful in tests, as you'll see elsewhere in this guide.

You import the DebugElement symbol from the Angular core library.

      
        content_copy
      
      import { DebugElement } from '@angular/core';
    

linkBy.css()

Although the tests in this guide all run in the browser, some apps might run on a different platform at least some of the time.

For example, the component might render first on the server as part of a strategy to make the application launch faster on poorly connected devices. The server-side renderer might not support the full HTML element API. If it doesn't support querySelector, the previous test could fail.

The DebugElement offers query methods that work for all supported platforms. These query methods take a predicate function that returns true when a node in the DebugElement tree matches the selection criteria.

You create a predicate with the help of a By class imported from a library for the runtime platform. Here's the By import for the browser platform:

      
        content_copy
      
      import { By } from '@angular/platform-browser';
    

The following example re-implements the previous test with DebugElement.query() and the browser's By.css method.

      
        content_copy
      
      it('should find the <p> with fixture.debugElement.query(By.css)', () => {
  const bannerDe: DebugElement = fixture.debugElement;
  const paragraphDe = bannerDe.query(By.css('p'));
  const p: HTMLElement = paragraphDe.nativeElement;
  expect(p.textContent).toEqual('banner works!');
});
    

Some noteworthy observations:

• The By.css() static method selects DebugElement nodes with a standard CSS selector.
• The query returns a DebugElement for the paragraph.
• You must unwrap that result to get the paragraph element.

When you're filtering by CSS selector and only testing properties of a browser's native element, the By.css approach may be overkill.

It's often easier and more clear to filter with a standard HTMLElement method such as querySelector() or querySelectorAll(), as you'll see in the next set of tests.

linkComponent Test Scenarios

The following sections, comprising most of this guide, explore common component testing scenarios

linkComponent binding

The current BannerComponent presents static title text in the HTML template.

After a few changes, the BannerComponent presents a dynamic title by binding to the component's title property like this.

      
        content_copy
      
      @Component({
  selector: 'app-banner',
  template: '<h1>{{title}}</h1>',
  styles: ['h1 { color: green; font-size: 350%}']
})
export class BannerComponent {
  title = 'Test Tour of Heroes';
}
    

Simple as this is, you decide to add a test to confirm that component actually displays the right content where you think it should.

linkQuery for the <h1>

You'll write a sequence of tests that inspect the value of the <h1> element that wraps the title property interpolation binding.

You update the beforeEach to find that element with a standard HTML querySelector and assign it to the h1 variable.

      
        content_copy
      
      let component: BannerComponent;
let fixture:   ComponentFixture<BannerComponent>;
let h1:        HTMLElement;

beforeEach(() => {
  TestBed.configureTestingModule({
    declarations: [ BannerComponent ],
  });
  fixture = TestBed.createComponent(BannerComponent);
  component = fixture.componentInstance; // BannerComponent test instance
  h1 = fixture.nativeElement.querySelector('h1');
});
    

linkcreateComponent() does not bind data

For your first test you'd like to see that the screen displays the default title. Your instinct is to write a test that immediately inspects the <h1> like this:

      
        content_copy
      
      it('should display original title', () => {
  expect(h1.textContent).toContain(component.title);
});
    

That test fails with the message:

      
        content_copy
      
      expected '' to contain 'Test Tour of Heroes'.
    

Binding happens when Angular performs change detection.

In production, change detection kicks in automatically when Angular creates a component or the user enters a keystroke or an asynchronous activity (e.g., AJAX) completes.

The TestBed.createComponent does not trigger change detection. a fact confirmed in the revised test:

      
        content_copy
      
      it('no title in the DOM after createComponent()', () => {
  expect(h1.textContent).toEqual('');
});
    

linkdetectChanges()

You must tell the TestBed to perform data binding by calling fixture.detectChanges(). Only then does the <h1> have the expected title.

      
        content_copy
      
      it('should display original title after detectChanges()', () => {
  fixture.detectChanges();
  expect(h1.textContent).toContain(component.title);
});
    

Delayed change detection is intentional and useful. It gives the tester an opportunity to inspect and change the state of the component before Angular initiates data binding and calls lifecycle hooks.

Here's another test that changes the component's title property before calling fixture.detectChanges().

      
        content_copy
      
      it('should display a different test title', () => {
  component.title = 'Test Title';
  fixture.detectChanges();
  expect(h1.textContent).toContain('Test Title');
});
    

linkAutomatic change detection

The BannerComponent tests frequently call detectChanges. Some testers prefer that the Angular test environment run change detection automatically.

That's possible by configuring the TestBed with the ComponentFixtureAutoDetect provider. First import it from the testing utility library:

      
        content_copy
      
      import { ComponentFixtureAutoDetect } from '@angular/core/testing';
    

Then add it to the providers array of the testing module configuration:

      
        content_copy
      
      TestBed.configureTestingModule({
  declarations: [ BannerComponent ],
  providers: [
    { provide: ComponentFixtureAutoDetect, useValue: true }
  ]
});
    

Here are three tests that illustrate how automatic change detection works.

      
        content_copy
      
      it('should display original title', () => {
  // Hooray! No `fixture.detectChanges()` needed
  expect(h1.textContent).toContain(comp.title);
});

it('should still see original title after comp.title change', () => {
  const oldTitle = comp.title;
  comp.title = 'Test Title';
  // Displayed title is old because Angular didn't hear the change :(
  expect(h1.textContent).toContain(oldTitle);
});

it('should display updated title after detectChanges', () => {
  comp.title = 'Test Title';
  fixture.detectChanges(); // detect changes explicitly
  expect(h1.textContent).toContain(comp.title);
});
    

The first test shows the benefit of automatic change detection.

The second and third test reveal an important limitation. The Angular testing environment does not know that the test changed the component's title. The ComponentFixtureAutoDetect service responds to asynchronous activities such as promise resolution, timers, and DOM events. But a direct, synchronous update of the component property is invisible. The test must call fixture.detectChanges() manually to trigger another cycle of change detection.

linkChange an input value with dispatchEvent()

To simulate user input, you can find the input element and set its value property.

You will call fixture.detectChanges() to trigger Angular's change detection. But there is an essential, intermediate step.

Angular doesn't know that you set the input element's value property. It won't read that property until you raise the element's input event by calling dispatchEvent(). Then you call detectChanges().

The following example demonstrates the proper sequence.

      
        content_copy
      
      it('should convert hero name to Title Case', () => {
  // get the name's input and display elements from the DOM
  const hostElement = fixture.nativeElement;
  const nameInput: HTMLInputElement = hostElement.querySelector('input');
  const nameDisplay: HTMLElement = hostElement.querySelector('span');

  // simulate user entering a new name into the input box
  nameInput.value = 'quick BROWN  fOx';

  // dispatch a DOM event so that Angular learns of input value change.
  nameInput.dispatchEvent(newEvent('input'));

  // Tell Angular to update the display binding through the title pipe
  fixture.detectChanges();

  expect(nameDisplay.textContent).toBe('Quick Brown  Fox');
});
    

linkComponent with external files

The BannerComponent above is defined with an inline template and inline css, specified in the @Component.template and @Component.styles properties respectively.

Many components specify external templates and external css with the @Component.templateUrl and @Component.styleUrls properties respectively, as the following variant of BannerComponent does.

      
        content_copy
      
      @Component({
  selector: 'app-banner',
  templateUrl: './banner-external.component.html',
  styleUrls:  ['./banner-external.component.css']
})
    

This syntax tells the Angular compiler to read the external files during component compilation.

That's not a problem when you run the CLI ng test command because it compiles the app before running the tests.

However, if you run the tests in a non-CLI environment, tests of this component may fail. For example, if you run the BannerComponent tests in a web coding environment such as plunker, you'll see a message like this one:

      
      Error: This test module uses the component BannerComponent 
which is using a "templateUrl" or "styleUrls", but they were never compiled. 
Please call "TestBed.compileComponents" before your test.
    

You get this test failure message when the runtime environment compiles the source code during the tests themselves.

To correct the problem, call compileComponents() as explained below.

linkComponent with a dependency

Components often have service dependencies.

The WelcomeComponent displays a welcome message to the logged in user. It knows who the user is based on a property of the injected UserService:

      
        content_copy
      
      import { Component, OnInit } from '@angular/core';
import { UserService }       from '../model/user.service';

@Component({
  selector: 'app-welcome',
  template: '<h3 class="welcome"><i>{{welcome}}</i></h3>'
})
export class WelcomeComponent  implements OnInit {
  welcome: string;
  constructor(private userService: UserService) { }

  ngOnInit(): void {
    this.welcome = this.userService.isLoggedIn ?
      'Welcome, ' + this.userService.user.name : 'Please log in.';
  }
}
    

The WelcomeComponent has decision logic that interacts with the service, logic that makes this component worth testing. Here's the testing module configuration for the spec file, app/welcome/welcome.component.spec.ts:

      
        content_copy
      
      TestBed.configureTestingModule({
   declarations: [ WelcomeComponent ],
// providers:    [ UserService ]  // NO! Don't provide the real service!
                                  // Provide a test-double instead
   providers:    [ {provide: UserService, useValue: userServiceStub } ]
});
    

This time, in addition to declaring the component-under-test, the configuration adds a UserService provider to the providers list. But not the real UserService.

linkProvide service test doubles

A component-under-test doesn't have to be injected with real services. In fact, it is usually better if they are test doubles (stubs, fakes, spies, or mocks). The purpose of the spec is to test the component, not the service, and real services can be trouble.

Injecting the real UserService could be a nightmare. The real service might ask the user for login credentials and attempt to reach an authentication server. These behaviors can be hard to intercept. It is far easier and safer to create and register a test double in place of the real UserService.

This particular test suite supplies a minimal mock of the UserService that satisfies the needs of the WelcomeComponent and its tests:

      
        content_copy
      
      let userServiceStub: Partial<UserService>;

userServiceStub = {
  isLoggedIn: true,
  user: { name: 'Test User'}
};
    

linkGet injected services

The tests need access to the (stub) UserService injected into the WelcomeComponent.

Angular has a hierarchical injection system. There can be injectors at multiple levels, from the root injector created by the TestBed down through the component tree.

The safest way to get the injected service, the way that always works, is to get it from the injector of the component-under-test. The component injector is a property of the fixture's DebugElement.

      
        content_copy
      
      // UserService actually injected into the component
userService = fixture.debugElement.injector.get(UserService);
    

linkTestBed.get()

You may also be able to get the service from the root injector via TestBed.get(). This is easier to remember and less verbose. But it only works when Angular injects the component with the service instance in the test's root injector.

In this test suite, the only provider of UserService is the root testing module, so it is safe to call TestBed.get() as follows:

      
        content_copy
      
      // UserService from the root injector
userService = TestBed.get(UserService);
    

linkAlways get the service from an injector

Do not reference the userServiceStub object that's provided to the testing module in the body of your test. It does not work! The userService instance injected into the component is a completely different object, a clone of the provided userServiceStub.

      
        content_copy
      
      it('stub object and injected UserService should not be the same', () => {
  expect(userServiceStub === userService).toBe(false);

  // Changing the stub object has no effect on the injected service
  userServiceStub.isLoggedIn = false;
  expect(userService.isLoggedIn).toBe(true);
});
    

linkFinal setup and tests

Here's the complete beforeEach(), using TestBed.get():

      
        content_copy
      
      let userServiceStub: Partial<UserService>;

beforeEach(() => {
  // stub UserService for test purposes
  userServiceStub = {
    isLoggedIn: true,
    user: { name: 'Test User'}
  };

  TestBed.configureTestingModule({
     declarations: [ WelcomeComponent ],
     providers:    [ {provide: UserService, useValue: userServiceStub } ]
  });

  fixture = TestBed.createComponent(WelcomeComponent);
  comp    = fixture.componentInstance;

  // UserService from the root injector
  userService = TestBed.get(UserService);

  //  get the "welcome" element by CSS selector (e.g., by class name)
  el = fixture.nativeElement.querySelector('.welcome');
});
    

And here are some tests:

      
        content_copy
      
      it('should welcome the user', () => {
  fixture.detectChanges();
  const content = el.textContent;
  expect(content).toContain('Welcome', '"Welcome ..."');
  expect(content).toContain('Test User', 'expected name');
});

it('should welcome "Bubba"', () => {
  userService.user.name = 'Bubba'; // welcome message hasn't been shown yet
  fixture.detectChanges();
  expect(el.textContent).toContain('Bubba');
});

it('should request login if not logged in', () => {
  userService.isLoggedIn = false; // welcome message hasn't been shown yet
  fixture.detectChanges();
  const content = el.textContent;
  expect(content).not.toContain('Welcome', 'not welcomed');
  expect(content).toMatch(/log in/i, '"log in"');
});
    

The first is a sanity test; it confirms that the stubbed UserService is called and working.

The remaining tests confirm the logic of the component when the service returns different values. The second test validates the effect of changing the user name. The third test checks that the component displays the proper message when there is no logged-in user.

linkComponent with async service

In this sample, the AboutComponent template hosts a TwainComponent. The TwainComponent displays Mark Twain quotes.

      
        content_copy
      
      template: `
  <p class="twain"><i>{{quote | async}}</i></p>
  <button (click)="getQuote()">Next quote</button>
  <p class="error" *ngIf="errorMessage">{{ errorMessage }}</p>`,
    

Note that value of the component's quote property passes through an AsyncPipe. That means the property returns either a Promise or an Observable.

In this example, the TwainComponent.getQuote() method tells you that the quote property returns an Observable.

      
        content_copy
      
      getQuote() {
  this.errorMessage = '';
  this.quote = this.twainService.getQuote().pipe(
    startWith('...'),
    catchError( (err: any) => {
      // Wait a turn because errorMessage already set once this turn
      setTimeout(() => this.errorMessage = err.message || err.toString());
      return of('...'); // reset message to placeholder
    })
  );
    

The TwainComponent gets quotes from an injected TwainService. The component starts the returned Observable with a placeholder value ('...'), before the service can returns its first quote.

The catchError intercepts service errors, prepares an error message, and returns the placeholder value on the success channel. It must wait a tick to set the errorMessage in order to avoid updating that message twice in the same change detection cycle.

These are all features you'll want to test.

linkTesting with a spy

When testing a component, only the service's public API should matter. In general, tests themselves should not make calls to remote servers. They should emulate such calls. The setup in this app/twain/twain.component.spec.ts shows one way to do that:

      
        content_copy
      
      beforeEach(() => {
  testQuote = 'Test Quote';

  // Create a fake TwainService object with a `getQuote()` spy
  const twainService = jasmine.createSpyObj('TwainService', ['getQuote']);
  // Make the spy return a synchronous Observable with the test data
  getQuoteSpy = twainService.getQuote.and.returnValue( of(testQuote) );

  TestBed.configureTestingModule({
    declarations: [ TwainComponent ],
    providers:    [
      { provide: TwainService, useValue: twainService }
    ]
  });

  fixture = TestBed.createComponent(TwainComponent);
  component = fixture.componentInstance;
  quoteEl = fixture.nativeElement.querySelector('.twain');
});
    

Focus on the spy.

      
        content_copy
      
      // Create a fake TwainService object with a `getQuote()` spy
const twainService = jasmine.createSpyObj('TwainService', ['getQuote']);
// Make the spy return a synchronous Observable with the test data
getQuoteSpy = twainService.getQuote.and.returnValue( of(testQuote) );
    

The spy is designed such that any call to getQuote receives an Observable with a test quote. Unlike the real getQuote() method, this spy bypasses the server and returns a synchronous Observable whose value is available immediately.

You can write many useful tests with this spy, even though its Observable is synchronous.

linkSynchronous tests

A key advantage of a synchronous Observable is that you can often turn asynchronous processes into synchronous tests.

      
        content_copy
      
      it('should show quote after component initialized', () => {
  fixture.detectChanges(); // onInit()

  // sync spy result shows testQuote immediately after init
  expect(quoteEl.textContent).toBe(testQuote);
  expect(getQuoteSpy.calls.any()).toBe(true, 'getQuote called');
});
    

Because the spy result returns synchronously, the getQuote() method updates the message on screen immediately after the first change detection cycle during which Angular calls ngOnInit.

You're not so lucky when testing the error path. Although the service spy will return an error synchronously, the component method calls setTimeout(). The test must wait at least one full turn of the JavaScript engine before the value becomes available. The test must become asynchronous.

linkAsync test with fakeAsync()

The following test confirms the expected behavior when the service returns an ErrorObservable.

      
        content_copy
      
      it('should display error when TwainService fails', fakeAsync(() => {
  // tell spy to return an error observable
  getQuoteSpy.and.returnValue(
    new ErrorObservable('TwainService test failure'));

  fixture.detectChanges(); // onInit()
  // sync spy errors immediately after init

  tick(); // flush the component's setTimeout()

  fixture.detectChanges(); // update errorMessage within setTimeout()

  expect(errorMessage()).toMatch(/test failure/, 'should display error');
  expect(quoteEl.textContent).toBe('...', 'should show placeholder');
}));
    

Note that the it() function receives an argument of the following form.

      
        content_copy
      
      fakeAsync(() => { /* test body */ })`
    

The fakeAsync function enables a linear coding style by running the test body in a special fakeAsync test zone. The test body appears to be synchronous. There is no nested syntax (like a Promise.then()) to disrupt the flow of control.

linkThe tick() function

You do have to call tick() to advance the (virtual) clock.

Calling tick() simulates the passage of time until all pending asynchronous activities finish. In this case, it waits for the error handler's setTimeout();

The tick function is one of the Angular testing utilities that you import with TestBed. It's a companion to fakeAsync and you can only call it within a fakeAsync body.

linkAsync observables

You might be satisfied with the test coverage of these tests.

But you might be troubled by the fact that the real service doesn't quite behave this way. The real service sends requests to a remote server. A server takes time to respond and the response certainly won't be available immediately as in the previous two tests.

Your tests will reflect the real world more faithfully if you return an asynchronous observable from the getQuote() spy like this.

      
        content_copy
      
      // Simulate delayed observable values with the `asyncData()` helper
getQuoteSpy.and.returnValue(asyncData(testQuote));
    

linkAsync observable helpers

The async observable was produced by an asyncData helper The asyncData helper is a utility function that you'll have to write yourself. Or you can copy this one from the sample code.

      
        content_copy
      
      /** Create async observable that emits-once and completes
 *  after a JS engine turn */
export function asyncData<T>(data: T) {
  return defer(() => Promise.resolve(data));
}
    

This helper's observable emits the data value in the next turn of the JavaScript engine.

RxJS defer() returns an observable. It takes a factory function that returns either a promise or an observable. When something subscribes to defer's observable, it adds the subscriber to a new observable created with that factory.

RxJS defer() transform the Promise.resolve() into a new observable that, like HttpClient, emits once and completes. Subscribers will be unsubscribed after they receive the data value.

There's a similar helper for producing an async error.

      
        content_copy
      
      /** Create async observable error that errors
 *  after a JS engine turn */
export function asyncError<T>(errorObject: any) {
  return defer(() => Promise.reject(errorObject));
}
    

linkMore async tests

Now that the getQuote() spy is returning async observables, most of your tests will have to be async as well.

Here's a fakeAsync() test that demonstrates the data flow you'd expect in the real world.

      
        content_copy
      
      it('should show quote after getQuote (fakeAsync)', fakeAsync(() => {
  fixture.detectChanges(); // ngOnInit()
  expect(quoteEl.textContent).toBe('...', 'should show placeholder');

  tick(); // flush the observable to get the quote
  fixture.detectChanges(); // update view

  expect(quoteEl.textContent).toBe(testQuote, 'should show quote');
  expect(errorMessage()).toBeNull('should not show error');
}));
    

Notice that the quote element displays the placeholder value ('...') after ngOnInit(). The first quote hasn't arrived yet.

To flush the first quote from the observable, you call tick(). Then call detectChanges() to tell Angular to update the screen.

Then you can assert that the quote element displays the expected text.

linkAsync test with async()

The fakeAsync() utility function has a few limitations. In particular, it won't work if the test body makes an XHR call.

XHR calls within a test are rare so you can generally stick with fakeAsync(). But if you ever do need to call XHR, you'll want to know about async().

Here's the previous fakeAsync() test, re-written with the async() utility.

      
        content_copy
      
      it('should show quote after getQuote (async)', async(() => {
  fixture.detectChanges(); // ngOnInit()
  expect(quoteEl.textContent).toBe('...', 'should show placeholder');

  fixture.whenStable().then(() => { // wait for async getQuote
    fixture.detectChanges();        // update view with quote
    expect(quoteEl.textContent).toBe(testQuote);
    expect(errorMessage()).toBeNull('should not show error');
  });
}));
    

The async() utility hides some asynchronous boilerplate by arranging for the tester's code to run in a special async test zone. You don't have to pass Jasmine's done() into the test and call done() in promise or observable callbacks.

But the test's asynchronous nature is revealed by the call to fixture.whenStable(), which breaks the linear flow of control.

linkwhenStable

The test must wait for the getQuote() observable to emit the next quote. Instead of calling tick(), it calls fixture.whenStable().

The fixture.whenStable() returns a promise that resolves when the JavaScript engine's task queue becomes empty. In this example, the task queue becomes empty when the observable emits the first quote.

The test resumes within the promise callback, which calls detectChanges() to update the quote element with the expected text.

linkJasmine done()

While the async and fakeAsync functions greatly simplify Angular asynchronous testing, you can still fall back to the traditional technique and pass it a function that takes a done callback.

Now you are responsible for chaining promises, handling errors, and calling done() at the appropriate moments.

Writing test functions with done(), is more cumbersome than asyncand fakeAsync. But it is occasionally necessary. For example, you can't call async or fakeAsync when testing code that involves the intervalTimer() or the RxJS delay() operator.

Here are two mover versions of the previous test, written with done(). The first one subscribes to the Observable exposed to the template by the component's quote property.

      
        content_copy
      
      it('should show last quote (quote done)', (done: DoneFn) => {
  fixture.detectChanges();

  component.quote.pipe( last() ).subscribe(() => {
    fixture.detectChanges(); // update view with quote
    expect(quoteEl.textContent).toBe(testQuote);
    expect(errorMessage()).toBeNull('should not show error');
    done();
  });
});
    

The RxJS last() operator emits the observable's last value before completing, which will be the test quote. The subscribe callback calls detectChanges() to update the quote element with the test quote, in the same manner as the earlier tests.

In some tests, you're more interested in how an injected service method was called and what values it returned, than what appears on screen.

A service spy, such as the qetQuote() spy of the fake TwainService, can give you that information and make assertions about the state of the view.

      
        content_copy
      
      it('should show quote after getQuote (spy done)', (done: DoneFn) => {
  fixture.detectChanges();

  // the spy's most recent call returns the observable with the test quote
  getQuoteSpy.calls.mostRecent().returnValue.subscribe(() => {
    fixture.detectChanges(); // update view with quote
    expect(quoteEl.textContent).toBe(testQuote);
    expect(errorMessage()).toBeNull('should not show error');
    done();
  });
});
    

linkComponent marble tests

The previous TwainComponent tests simulated an asynchronous observable response from the TwainService with the asyncData and asyncError utilities.

These are short, simple functions that you can write yourself. Unfortunately, they're too simple for many common scenarios. An observable often emits multiple times, perhaps after a significant delay. A component may coordinate multiple observables with overlapping sequences of values and errors.

RxJS marble testing is a great way to test observable scenarios, both simple and complex. You've likely seen the marble diagrams that illustrate how observables work. Marble testing uses a similar marble language to specify the observable streams and expectations in your tests.

The following examples revisit two of the TwainComponent tests with marble testing.

Start by installing the jasmine-marbles npm package. Then import the symbols you need.

      
        content_copy
      
      import { cold, getTestScheduler } from 'jasmine-marbles';
    

Here's the complete test for getting a quote:

      
        content_copy
      
      it('should show quote after getQuote (marbles)', () => {
  // observable test quote value and complete(), after delay
  const q$ = cold('---x|', { x: testQuote });
  getQuoteSpy.and.returnValue( q$ );

  fixture.detectChanges(); // ngOnInit()
  expect(quoteEl.textContent).toBe('...', 'should show placeholder');

  getTestScheduler().flush(); // flush the observables

  fixture.detectChanges(); // update view

  expect(quoteEl.textContent).toBe(testQuote, 'should show quote');
  expect(errorMessage()).toBeNull('should not show error');
});
    

Notice that the Jasmine test is synchronous. There's no fakeAsync(). Marble testing uses a test scheduler to simulate the passage of time in a synchronous test.

The beauty of marble testing is in the visual definition of the observable streams. This test defines a cold observable that waits three frames (---), emits a value (x), and completes (|). In the second argument you map the value marker (x) to the emitted value (testQuote).

      
        content_copy
      
      const q$ = cold('---x|', { x: testQuote });
    

The marble library constructs the corresponding observable, which the test sets as the getQuote spy's return value.

When you're ready to activate the marble observables, you tell the TestScheduler to flush its queue of prepared tasks like this.

      
        content_copy
      
      getTestScheduler().flush(); // flush the observables
    

This step serves a purpose analogous to tick() and whenStable() in the earlier fakeAsync() and async() examples. The balance of the test is the same as those examples.

linkMarble error testing

Here's the marble testing version of the getQuote() error test.

      
        content_copy
      
      it('should display error when TwainService fails', fakeAsync(() => {
  // observable error after delay
  const q$ = cold('---#|', null, new Error('TwainService test failure'));
  getQuoteSpy.and.returnValue( q$ );

  fixture.detectChanges(); // ngOnInit()
  expect(quoteEl.textContent).toBe('...', 'should show placeholder');

  getTestScheduler().flush(); // flush the observables
  tick();                     // component shows error after a setTimeout()
  fixture.detectChanges();    // update error message

  expect(errorMessage()).toMatch(/test failure/, 'should display error');
  expect(quoteEl.textContent).toBe('...', 'should show placeholder');
}));
    

It's still an async test, calling fakeAsync() and tick(), because the component itself calls setTimeout() when processing errors.

Look at the marble observable definition.

      
        content_copy
      
      const q$ = cold('---#|', null, new Error('TwainService test failure'));
    

This is a cold observable that waits three frames and then emits an error, The hash (#) indicates the timing of the error that is specified in the third argument. The second argument is null because the observable never emits a value.

linkLearn about marble testing

A marble frame is a virtual unit of testing time. Each symbol (-, x, |, #) marks the passing of one frame.

A cold observable doesn't produce values until you subscribe to it. Most of your application observables are cold. All HttpClient methods return cold observables.

A hot observable is already producing values before you subscribe to it. The Router.events observable, which reports router activity, is a hot observable.

RxJS marble testing is a rich subject, beyond the scope of this guide. Learn about it on the web, starting with the official documentation.

linkComponent with inputs and outputs

A component with inputs and outputs typically appears inside the view template of a host component. The host uses a property binding to set the input property and an event binding to listen to events raised by the output property.

The testing goal is to verify that such bindings work as expected. The tests should set input values and listen for output events.

The DashboardHeroComponent is a tiny example of a component in this role. It displays an individual hero provided by the DashboardComponent. Clicking that hero tells the DashboardComponent that the user has selected the hero.

The DashboardHeroComponent is embedded in the DashboardComponent template like this:

      
        content_copy
      
      <dashboard-hero *ngFor="let hero of heroes"  class="col-1-4"
  [hero]=hero  (selected)="gotoDetail($event)" >
</dashboard-hero>
    

The DashboardHeroComponent appears in an *ngFor repeater, which sets each component's hero input property to the looping value and listens for the component's selected event.

Here's the component's full definition:

      
        content_copy
      
      @Component({
  selector: 'dashboard-hero',
  template: `
    <div (click)="click()" class="hero">
      {{hero.name | uppercase}}
    </div>`,
  styleUrls: [ './dashboard-hero.component.css' ]
})
export class DashboardHeroComponent {
  @Input() hero: Hero;
  @Output() selected = new EventEmitter<Hero>();
  click() { this.selected.emit(this.hero); }
}
    

While testing a component this simple has little intrinsic value, it's worth knowing how. You can use one of these approaches:

• Test it as used by DashboardComponent.
• Test it as a stand-alone component.
• Test it as used by a substitute for DashboardComponent.

A quick look at the DashboardComponent constructor discourages the first approach:

      
        content_copy
      
      constructor(
  private router: Router,
  private heroService: HeroService) {
}
    

The DashboardComponent depends on the Angular router and the HeroService. You'd probably have to replace them both with test doubles, which is a lot of work. The router seems particularly challenging.

The immediate goal is to test the DashboardHeroComponent, not the DashboardComponent, so, try the second and third options.

linkTest DashboardHeroComponent stand-alone

Here's the meat of the spec file setup.

      
        content_copy
      
      TestBed.configureTestingModule({
  declarations: [ DashboardHeroComponent ]
})
fixture = TestBed.createComponent(DashboardHeroComponent);
comp    = fixture.componentInstance;

// find the hero's DebugElement and element
heroDe  = fixture.debugElement.query(By.css('.hero'));
heroEl = heroDe.nativeElement;

// mock the hero supplied by the parent component
expectedHero = { id: 42, name: 'Test Name' };

// simulate the parent setting the input property with that hero
comp.hero = expectedHero;

// trigger initial data binding
fixture.detectChanges();
    

Note how the setup code assigns a test hero (expectedHero) to the component's hero property, emulating the way the DashboardComponent would set it via the property binding in its repeater.

The following test verifies that the hero name is propagated to the template via a binding.

      
        content_copy
      
      it('should display hero name in uppercase', () => {
  const expectedPipedName = expectedHero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});
    

Because the template passes the hero name through the Angular UpperCasePipe, the test must match the element value with the upper-cased name.

linkClicking

Clicking the hero should raise a selected event that the host component (DashboardComponent presumably) can hear:

      
        content_copy
      
      it('should raise selected event when clicked (triggerEventHandler)', () => {
  let selectedHero: Hero;
  comp.selected.subscribe((hero: Hero) => selectedHero = hero);

  heroDe.triggerEventHandler('click', null);
  expect(selectedHero).toBe(expectedHero);
});
    

The component's selected property returns an EventEmitter, which looks like an RxJS synchronous Observable to consumers. The test subscribes to it explicitly just as the host component does implicitly.

If the component behaves as expected, clicking the hero's element should tell the component's selected property to emit the hero object.

The test detects that event through its subscription to selected.

linktriggerEventHandler

The heroDe in the previous test is a DebugElement that represents the hero <div>.

It has Angular properties and methods that abstract interaction with the native element. This test calls the DebugElement.triggerEventHandler with the "click" event name. The "click" event binding responds by calling DashboardHeroComponent.click().

The Angular DebugElement.triggerEventHandler can raise any data-bound event by its event name. The second parameter is the event object passed to the handler.

The test triggered a "click" event with a null event object.

      
        content_copy
      
      heroDe.triggerEventHandler('click', null);
    

The test assumes (correctly in this case) that the runtime event handler—the component's click() method—doesn't care about the event object.

linkClick the element

The following test alternative calls the native element's own click() method, which is perfectly fine for this component.

      
        content_copy
      
      it('should raise selected event when clicked (element.click)', () => {
  let selectedHero: Hero;
  comp.selected.subscribe((hero: Hero) => selectedHero = hero);

  heroEl.click();
  expect(selectedHero).toBe(expectedHero);
});
    

linkclick() helper

Clicking a button, an anchor, or an arbitrary HTML element is a common test task.

Make that consistent and easy by encapsulating the click-triggering process in a helper such as the click() function below:

      
        content_copy
      
      /** Button events to pass to `DebugElement.triggerEventHandler` for RouterLink event handler */
export const ButtonClickEvents = {
   left:  { button: 0 },
   right: { button: 2 }
};

/** Simulate element click. Defaults to mouse left-button click event. */
export function click(el: DebugElement | HTMLElement, eventObj: any = ButtonClickEvents.left): void {
  if (el instanceof HTMLElement) {
    el.click();
  } else {
    el.triggerEventHandler('click', eventObj);
  }
}
    

The first parameter is the element-to-click. If you wish, you can pass a custom event object as the second parameter. The default is a (partial) left-button mouse event object accepted by many handlers including the RouterLink directive.

Here's the previous test, rewritten using the click helper.

      
        content_copy
      
      it('should raise selected event when clicked (click helper)', () => {
  let selectedHero: Hero;
  comp.selected.subscribe(hero => selectedHero = hero);

  click(heroDe); // click helper with DebugElement
  click(heroEl); // click helper with native element

  expect(selectedHero).toBe(expectedHero);
});
    

linkComponent inside a test host

The previous tests played the role of the host DashboardComponent themselves. But does the DashboardHeroComponent work correctly when properly data-bound to a host component?

You could test with the actual DashboardComponent. But doing so could require a lot of setup, especially when its template features an *ngFor repeater, other components, layout HTML, additional bindings, a constructor that injects multiple services, and it starts interacting with those services right away.

Imagine the effort to disable these distractions, just to prove a point that can be made satisfactorily with a test host like this one:

      
        content_copy
      
      @Component({
  template: `
    <dashboard-hero
      [hero]="hero" (selected)="onSelected($event)">
    </dashboard-hero>`
})
class TestHostComponent {
  hero: Hero = {id: 42, name: 'Test Name' };
  selectedHero: Hero;
  onSelected(hero: Hero) { this.selectedHero = hero; }
}
    

This test host binds to DashboardHeroComponent as the DashboardComponent would but without the noise of the Router, the HeroService, or the *ngFor repeater.

The test host sets the component's hero input property with its test hero. It binds the component's selected event with its onSelected handler, which records the emitted hero in its selectedHero property.

Later, the tests will be able to easily check selectedHero to verify that the DashboardHeroComponent.selected event emitted the expected hero.

The setup for the test-host tests is similar to the setup for the stand-alone tests:

      
        content_copy
      
      TestBed.configureTestingModule({
  declarations: [ DashboardHeroComponent, TestHostComponent ]
})
// create TestHostComponent instead of DashboardHeroComponent
fixture  = TestBed.createComponent(TestHostComponent);
testHost = fixture.componentInstance;
heroEl   = fixture.nativeElement.querySelector('.hero');
fixture.detectChanges(); // trigger initial data binding
    

This testing module configuration shows three important differences:

1. It declares both the DashboardHeroComponent and the TestHostComponent.
2. It creates the TestHostComponent instead of the DashboardHeroComponent.
3. The TestHostComponent sets the DashboardHeroComponent.hero with a binding.

The createComponent returns a fixture that holds an instance of TestHostComponent instead of an instance of DashboardHeroComponent.

Creating the TestHostComponent has the side-effect of creating a DashboardHeroComponent because the latter appears within the template of the former. The query for the hero element (heroEl) still finds it in the test DOM, albeit at greater depth in the element tree than before.

The tests themselves are almost identical to the stand-alone version:

      
        content_copy
      
      it('should display hero name', () => {
  const expectedPipedName = testHost.hero.name.toUpperCase();
  expect(heroEl.textContent).toContain(expectedPipedName);
});

it('should raise selected event when clicked', () => {
  click(heroEl);
  // selected hero should be the same data bound hero
  expect(testHost.selectedHero).toBe(testHost.hero);
});
    

Only the selected event test differs. It confirms that the selected DashboardHeroComponent hero really does find its way up through the event binding to the host component.

linkRouting component

A routing component is a component that tells the Router to navigate to another component. The DashboardComponent is a routing component because the user can navigate to the HeroDetailComponent by clicking on one of the hero buttons on the dashboard.

Routing is pretty complicated. Testing the DashboardComponent seemed daunting in part because it involves the Router, which it injects together with the HeroService.

      
        content_copy
      
      constructor(
  private router: Router,
  private heroService: HeroService) {
}
    

Mocking the HeroService with a spy is a familiar story. But the Router has a complicated API and is entwined with other services and application preconditions. Might it be difficult to mock?

Fortunately, not in this case because the DashboardComponent isn't doing much with the Router

      
        content_copy
      
      gotoDetail(hero: Hero) {
  let url = `/heroes/${hero.id}`;
  this.router.navigateByUrl(url);
}
    

This is often the case with routing components. As a rule you test the component, not the router, and care only if the component navigates with the right address under the given conditions.

Providing a router spy for this component test suite happens to be as easy as providing a HeroService spy.

      
        content_copy
      
      const routerSpy = jasmine.createSpyObj('Router', ['navigateByUrl']);
const heroServiceSpy = jasmine.createSpyObj('HeroService', ['getHeroes']);

TestBed.configureTestingModule({
  providers: [
    { provide: HeroService, useValue: heroServiceSpy },
    { provide: Router,      useValue: routerSpy }
  ]
})
    

The following test clicks the displayed hero and confirms that Router.navigateByUrl is called with the expected url.

      
        content_copy
      
      it('should tell ROUTER to navigate when hero clicked', () => {

  heroClick(); // trigger click on first inner <div class="hero">

  // args passed to router.navigateByUrl() spy
  const spy = router.navigateByUrl as jasmine.Spy;
  const navArgs = spy.calls.first().args[0];

  // expecting to navigate to id of the component's first hero
  const id = comp.heroes[0].id;
  expect(navArgs).toBe('/heroes/' + id,
    'should nav to HeroDetail for first hero');
});
    

linkRouted components

A routed component is the destination of a Router navigation. It can be trickier to test, especially when the route to the component includes parameters. The HeroDetailComponent is a routed component that is the destination of such a route.

When a user clicks a Dashboard hero, the DashboardComponent tells the Router to navigate to heroes/:id. The :id is a route parameter whose value is the id of the hero to edit.

The Router matches that URL to a route to the HeroDetailComponent. It creates an ActivatedRoute object with the routing information and injects it into a new instance of the HeroDetailComponent.

Here's the HeroDetailComponent constructor:

      
        content_copy
      
      constructor(
  private heroDetailService: HeroDetailService,
  private route:  ActivatedRoute,
  private router: Router) {
}
    

The HeroDetail component needs the id parameter so it can fetch the corresponding hero via the HeroDetailService.

The component has to get the id from the ActivatedRoute.paramMap property which is an Observable.

It can't just reference the id property of the ActivatedRoute.paramMap. The component has to subscribe to the ActivatedRoute.paramMap observable and be prepared for the id to change during its lifetime.

      
        content_copy
      
      ngOnInit(): void {
  // get hero when `id` param changes
  this.route.paramMap.subscribe(pmap => this.getHero(pmap.get('id')));
}
    

Tests can explore how the HeroDetailComponent responds to different id parameter values by manipulating the ActivatedRoute injected into the component's constructor.

You know how to spy on the Router and a data service.

You'll take a different approach with ActivatedRoute because

• paramMap returns an Observable that can emit more than one value during a test.
• You need the router helper function, convertToParamMap(), to create a ParamMap.
• Other routed components tests need a test double for ActivatedRoute.

These differences argue for a re-usable stub class.

linkActivatedRouteStub

The following ActivatedRouteStub class serves as a test double for ActivatedRoute.

      
        content_copy
      
      import { ReplaySubject } from 'rxjs/ReplaySubject';
import { convertToParamMap, ParamMap, Params } from '@angular/router';

/**
 * An ActivateRoute test double with a `paramMap` observable.
 * Use the `setParamMap()` method to add the next `paramMap` value.
 */
export class ActivatedRouteStub {
  // Use a ReplaySubject to share previous values with subscribers
  // and pump new values into the `paramMap` observable
  private subject = new ReplaySubject<ParamMap>();

  constructor(initialParams?: Params) {
    this.setParamMap(initialParams);
  }

  /** The mock paramMap observable */
  readonly paramMap = this.subject.asObservable();

  /** Set the paramMap observables's next value */
  setParamMap(params?: Params) {
    this.subject.next(convertToParamMap(params));
  };
}
    

Consider placing such helpers in a testing folder sibling to the app folder. This sample puts ActivatedRouteStub in testing/activated-route-stub.ts.

linkTesting with ActivatedRouteStub

Here's a test demonstrating the component's behavior when the observed id refers to an existing hero:

      
        content_copy
      
      describe('when navigate to existing hero', () => {
  let expectedHero: Hero;

  beforeEach(async(() => {
    expectedHero = firstHero;
    activatedRoute.setParamMap({ id: expectedHero.id });
    createComponent();
  }));

  it('should display that hero\'s name', () => {
    expect(page.nameDisplay.textContent).toBe(expectedHero.name);
  });
});
    

When the id cannot be found, the component should re-route to the HeroListComponent.

The test suite setup provided the same router spy described above which spies on the router without actually navigating.

This test expects the component to try to navigate to the HeroListComponent.

      
        content_copy
      
      describe('when navigate to non-existent hero id', () => {
  beforeEach(async(() => {
    activatedRoute.setParamMap({ id: 99999 });
    createComponent();
  }));

  it('should try to navigate back to hero list', () => {
    expect(page.gotoListSpy.calls.any()).toBe(true, 'comp.gotoList called');
    expect(page.navigateSpy.calls.any()).toBe(true, 'router.navigate called');
  });
});
    

While this app doesn't have a route to the HeroDetailComponent that omits the id parameter, it might add such a route someday. The component should do something reasonable when there is no id.

In this implementation, the component should create and display a new hero. New heroes have id=0 and a blank name. This test confirms that the component behaves as expected:

      
        content_copy
      
      describe('when navigate with no hero id', () => {
  beforeEach(async( createComponent ));

  it('should have hero.id === 0', () => {
    expect(component.hero.id).toBe(0);
  });

  it('should display empty hero name', () => {
    expect(page.nameDisplay.textContent).toBe('');
  });
});