Testing

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

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

• Sample appSample app / download example
• TestsTests / download example

Setup

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 the ng test 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.

Configuration

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

You can fine-tune many options by editing the karma.conf.js and the test.ts files 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.json file, supplemented by karma.conf.js.

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

Other 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.

Test 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.

Set up continuous integration

One of the best ways to keep your project bug free is through a test suite, but it's easy to forget to run tests all the time. Continuous integration (CI) servers let you set up your project repository so that your tests run on every commit and pull request.

There are paid CI services like Circle CI and Travis CI, and you can also host your own for free using Jenkins and others. Although Circle CI and Travis CI are paid services, they are provided free for open source projects. You can create a public project on GitHub and add these services without paying. Contributions to the Angular repo are automatically run through a whole suite of Circle CI tests.

This article explains how to configure your project to run Circle CI and Travis CI, and also update your test configuration to be able to run tests in the Chrome browser in either environment.

Configure project for Circle CI

Step 1: Create a folder called .circleci at the project root.

Step 2: In the new folder, create a file called config.yml with the following content:

      
        content_copy
      
      
version: 2
jobs:
  build:
    working_directory: ~/my-project
    docker:
      - image: circleci/node:8-browsers
    steps:
      - checkout
      - restore_cache:
          key: my-project-{{ .Branch }}-{{ checksum "package-lock.json" }}
      - run: npm install
      - save_cache:
          key: my-project-{{ .Branch }}-{{ checksum "package-lock.json" }}
          paths:
            - "node_modules"
      - run: npm run test -- --no-watch --no-progress --browsers=ChromeHeadlessCI
      - run: npm run e2e -- --protractor-config=e2e/protractor-ci.conf.js
    

This configuration caches node_modules/ and uses npm run to run CLI commands, because @angular/cli is not installed globally. The double dash (--) is needed to pass arguments into the npm script.

Step 3: Commit your changes and push them to your repository.

Step 4: Sign up for Circle CI and add your project. Your project should start building.

• Learn more about Circle CI from Circle CI documentation.

Configure project for Travis CI

Step 1: Create a file called .travis.yml at the project root, with the following content:

      
        content_copy
      
      
dist: trusty
sudo: false
 
language: node_js
node_js:
  - "8"
  
addons:
  apt:
    sources:
      - google-chrome
    packages:
      - google-chrome-stable
 
cache:
  directories:
     - ./node_modules
 
install:
  - npm install
 
script:
  - npm run test -- --no-watch --no-progress --browsers=ChromeHeadlessCI
  - npm run e2e -- --protractor-config=e2e/protractor-ci.conf.js
    

This does the same things as the Circle CI configuration, except that Travis doesn't come with Chrome, so we use Chromium instead.

Step 2: Commit your changes and push them to your repository.

Step 3: Sign up for Travis CI and add your project. You'll need to push a new commit to trigger a build.

• Learn more about Travis CI testing from Travis CI documentation.

Configure CLI for CI testing in Chrome

When the CLI commands ng test and ng e2e are generally running the CI tests in your environment, you might still need to adjust your configuration to run the Chrome browser tests.

There are configuration files for both the Karma JavaScript test runner and Protractor end-to-end testing tool, which you must adjust to start Chrome without sandboxing.

We'll be using Headless Chrome in these examples.

• In the Karma configuration file, karma.conf.js, add a custom launcher called ChromeHeadlessCI below browsers:

      
        content_copy
      
      browsers: ['Chrome'],
customLaunchers: {
  ChromeHeadlessCI: {
    base: 'ChromeHeadless',
    flags: ['--no-sandbox']
  }
},
    

• In the root folder of your e2e tests project, create a new file named protractor-ci.conf.js. This new file extends the original protractor.conf.js.

      
        content_copy
      
      const config = require('./protractor.conf').config;

config.capabilities = {
  browserName: 'chrome',
  chromeOptions: {
    args: ['--headless', '--no-sandbox']
  }
};

exports.config = config;
    

Now you can run the following commands to use the --no-sandbox flag:

      
        content_copy
      
      ng test -- --no-watch --no-progress --browsers=ChromeHeadlessCI
ng e2e -- --protractor-config=e2e/protractor-ci.conf.js
    

Enable code coverage reports

The CLI can run unit tests and create code coverage reports. Code coverage reports show you any parts of our code base that may not be properly tested by your unit tests.

To generate a coverage report run the following command in the root of your project.

      
        content_copy
      
      ng test --no-watch --code-coverage
    

When the tests are complete, the command creates a new /coverage folder in the project. Open the index.html file to see a report with your source code and code coverage values.

If you want to create code-coverage reports every time you test, you can set the following option in the CLI configuration file, angular.json:

      
        content_copy
      
      "test": {
  "options": {
    "codeCoverage": true
  }
}
    

Code coverage enforcement

The code coverage percentages let you estimate how much of your code is tested.
If your team decides on a set minimum amount to be unit tested, you can enforce this minimum with the Angular CLI.

For example, suppose you want the code base to have a minimum of 80% code coverage. To enable this, open the Karma test platform configuration file, karma.conf.js, and add the following in the coverageIstanbulReporter: key.

      
        content_copy
      
      coverageIstanbulReporter: {
  reports: [ 'html', 'lcovonly' ],
  fixWebpackSourcePaths: true,
  thresholds: {
    statements: 80,
    lines: 80,
    branches: 80,
    functions: 80
  }
}
    

The thresholds property causes the tool to enforce a minimum of 80% code coverage when the unit tests are run in the project.

Service 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();
    });
  });
});
    

Services with dependencies

Services often depend on other services that Angular injects into the constructor. In many cases, it's 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 services 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.

Testing 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.

Angular 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);
});
    

Testing 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 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 traditional style and the default CLI schematics generate test files with beforeEach() and TestBed, feel free to adopt this alternative approach in your own projects.

Testing 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')
  );
});
    

HttpClientTestingModule

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.

Component 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.

Component 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 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');
});
    

Component 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 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.

CLI-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();
  });
});
    

Reduce 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 ]
});
    

createComponent()

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.

ComponentFixture

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();
    

beforeEach()

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!');
});
    

nativeElement

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!');
});
    

DebugElement

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';
    

By.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.

Component Test Scenarios

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

Component 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.

Query 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');
});
    

createComponent() 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('');
});
    

detectChanges()

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');
});
    

Automatic 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.

Change 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');
});
    

Component 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:

      
        content_copy
      
      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.

Component 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.

Provide 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'}
};
    

Get 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);
    

TestBed.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);
    

Always 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);
});
    

Final 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.

Component 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.

Testing 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.

Synchronous 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.

Async test with fakeAsync()

To use fakeAsync() functionality, you need to import zone-testing, for details, please read setup guide.

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(
    throwError('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.

The 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 accepts milliseconds as parameter (defaults to 0 if not provided). The parameter represents how much the virtual clock advances. For example, if you have a setTimeout(fn, 100) in a fakeAsync() test, you need to use tick(100) to trigger the fn callback.

      
        content_copy
      
      it('should run timeout callback with delay after call tick with millis', fakeAsync(() => {
    let called = false;
    setTimeout(() => { called = true; }, 100);
    tick(100);
    expect(called).toBe(true);
  }));
    

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.

Comparing dates inside fakeAsync()

fakeAsync() simulates passage of time, which allows you to calculate the difference between dates inside fakeAsync().

      
        content_copy
      
      it('should get Date diff correctly in fakeAsync', fakeAsync(() => {
    const start = Date.now();
    tick(100);
    const end = Date.now();
    expect(end - start).toBe(100);
  }));
    

jasmine.clock with fakeAsync()

Jasmine also provides a clock feature to mock dates. Angular automatically runs tests that are run after jasmine.clock().install() is called inside a fakeAsync() method until jasmine.clock().uninstall() is called. fakeAsync() is not needed and throws an error if nested.

By default, this feature is disabled. To enable it, set a global flag before import zone-testing.

If you use the Angular CLI, configure this flag in src/test.ts.

      
        content_copy
      
      (window as any)['__zone_symbol__fakeAsyncPatchLock'] = true;
import 'zone.js/dist/zone-testing';
    

      
        content_copy
      
      
describe('use jasmine.clock()', () => {
  // need to config __zone_symbol__fakeAsyncPatchLock flag
  // before loading zone.js/dist/zone-testing
  beforeEach(() => { jasmine.clock().install(); });
  afterEach(() => { jasmine.clock().uninstall(); });
  it('should auto enter fakeAsync', () => {
    // is in fakeAsync now, don't need to call fakeAsync(testFn)
    let called = false;
    setTimeout(() => { called = true; }, 100);
    jasmine.clock().tick(100);
    expect(called).toBe(true);
  });
});
    

Using the RxJS scheduler inside fakeAsync()

You can also use RxJS scheduler in fakeAsync() just like using setTimeout() or setInterval(), but you need to import zone.js/dist/zone-patch-rxjs-fake-async to patch RxJS scheduler.

      
        content_copy
      
      
it('should get Date diff correctly in fakeAsync with rxjs scheduler', fakeAsync(() => {
    // need to add `import 'zone.js/dist/zone-patch-rxjs-fake-async'
    // to patch rxjs scheduler
    let result = null;
    of ('hello').pipe(delay(1000)).subscribe(v => { result = v; });
    expect(result).toBeNull();
    tick(1000);
    expect(result).toBe('hello');
 
    const start = new Date().getTime();
    let dateDiff = 0;
    interval(1000).pipe(take(2)).subscribe(() => dateDiff = (new Date().getTime() - start));
 
    tick(1000);
    expect(dateDiff).toBe(1000);
    tick(1000);
    expect(dateDiff).toBe(2000);
  }));
    

Support more macroTasks

By default fakeAsync() supports the following macroTasks.

• setTimeout
• setInterval
• requestAnimationFrame
• webkitRequestAnimationFrame
• mozRequestAnimationFrame

If you run other macroTask such as HTMLCanvasElement.toBlob(), Unknown macroTask scheduled in fake async test error will be thrown.

      
        content_copy
      
      import { TestBed, async, tick, fakeAsync } from '@angular/core/testing';
import { CanvasComponent } from './canvas.component';
describe('CanvasComponent', () => {
  beforeEach(async(() => {
    TestBed.configureTestingModule({
      declarations: [
        CanvasComponent
      ],
    }).compileComponents();
  }));
  beforeEach(() => {
    window['__zone_symbol__FakeAsyncTestMacroTask'] = [
      {
        source: 'HTMLCanvasElement.toBlob',
        callbackArgs: [{ size: 200 }]
      }
    ];
  });
  it('should be able to generate blob data from canvas', fakeAsync(() => {
    const fixture = TestBed.createComponent(CanvasComponent);
    fixture.detectChanges();
    tick();
    const app = fixture.debugElement.componentInstance;
    expect(app.blobSize).toBeGreaterThan(0);
  }));
});
    

If you want to support such case, you need to define the macroTask you want to support in beforeEach(). For example:

      
        content_copy
      
      
beforeEach(() => {
  window['__zone_symbol__FakeAsyncTestMacroTask'] = [
    {
      source: 'HTMLCanvasElement.toBlob',
      callbackArgs: [{ size: 200 }]
    }
  ];
});
 
it('toBlob should be able to run in fakeAsync', fakeAsync(() => {
    const canvas: HTMLCanvasElement = document.getElementById('canvas') as HTMLCanvasElement;
    let blob = null;
    canvas.toBlob(function(b) {
      blob = b;
    });
    tick();
    expect(blob.size).toBe(200);
  })
);
    

Async 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));
    

Async 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.

The RxJS defer() operator 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.

The defer() operator transforms the Promise.resolve() into a new observable that, like HttpClient, emits once and completes. Subscribers are 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));
}
    

More 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.

Async test with async()

To use async() functionality, you need to import zone-testing, for details, please read setup guide.

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 need to pass Jasmine's done() into the test and call done() because it is undefined 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.

When using an intervalTimer() such as setInterval() in async(), remember to cancel the timer with clearInterval() after the test, otherwise the async() never ends.

whenStable

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.

Jasmine 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.

You can't call done() in async() or fakeAsync() functions, because the done parameter is undefined.

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 async()and fakeAsync(). But it is occasionally necessary when code involves the intervalTimer() like setInterval.

Here are two more 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();
  });
});
    

Component 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.

Marble 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.

Learn 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.

Component 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.