Angular ships with a unit testing API called TestBed, which is specifically designed for writing unit tests for the Angular framework. It allows for simple testing of Angular web components, that is to say a TypeScript class, paired with some HTML.
For a brief intro to unit testing concepts see here
If you use the Angular CLI for generating your app and your components (which you should), then it will by default set up a <component -name>.component.spec.ts file, with some boilerplate setup code for TestBed testing already populated.
Let’s have a look at how we might write a simple login component that is properly tested, using Test Driven Development, the Angular CLI and TestBed.
Login Component
Before writing any code, we should think about what the component is supposed to do.
This step is important, because if the behaviour of the component is not properly defined, we cannot write tests for it, and we can’t properly define the interface. This behaviour may need to change later on, but for now we need a design contract to code against. For a basic login component, I’m going to say I want:
- login form
- input box of type text for username
- input box of type password for password
- button which emits a login event with a payload of username and password
This is enough for me to write a suite of tests, and to develop my component against those criteria.
I’m going to set up a quick angular project using the Angular CLI in order to demonstrate all of the default test tooling that comes with Angular:
I will create one called ‘test-app’
ng new test-app
Once this command has run you will have a default hello world application. To view it, move into the directory of the new application and run
ng serve
If you open your browser and type localhost:4200 into the url box you should now see the default Angular application.
For now we will just use the app.component component as a sandbox for testing our new login component. For the first step, delete all the default code from app.component.html, as this is where we will be putting our new component eventually.
Also delete app.component.spec.ts as these tests will now fail because we have changed the underlying component.
Now we are ready to create our login component:
ng generate component login
This will create a new Login component, with a selector called app-login adding it as a declaration in app.module.ts. These files will be created:
login.component.html login.component.css login.component.ts login.component.spec.ts
This component can now be used in the app.component.html template file, so let’s add it now. app.component.html should now have only the following code in it:
<app-login></app-login>
The app at localhost:4200 in your browser should now say something similar to below:
login works!
TestBed setup
Before we start writing tests, let’s take a look at the generated login.component.spec.ts file to get a better understanding of how TestBed is set up:
import { async, ComponentFixture, TestBed } from '@angular/core/testing';
import { LoginComponent } from './login.component';
describe('LoginComponent', () => {
let component: LoginComponent;
let fixture: ComponentFixture<LoginComponent>;
beforeEach(async(() => {
TestBed.configureTestingModule({
declarations: [ LoginComponent ]
})
.compileComponents();
}));
beforeEach(() => {
fixture = TestBed.createComponent(LoginComponent);
component = fixture.componentInstance;
fixture.detectChanges();
});
it('should create', () => {
expect(component).toBeTruthy();
});
});
This sets up the TestBed environment, and one basic test ‘it should create’. Let’s run the tests now and see what happens:
ng test
A chrome window should open, showing the test output. If everything is working, it will look something like below:
So now we have a test than ensures our component can be instantiated correctly. At this point it is worth quickly digressing and explaining what TestBed.configureTestingModule does.
It basically allows you to set up a miniature Angular application, with only the components, providers, modules etc. that are needed for the specific piece of code you are testing. In our example it currently just has a declarations array, with our LoginComponent in it.
Specifically, the block below sets up the testing module, then compiles all the components. Again, in our case this is just the LoginComponent.
beforeEach(async(() => {
TestBed.configureTestingModule({
declarations: [ LoginComponent ]
})
.compileComponents();
}));
The compileComponents call is aysnchronous, so to make the tests easier to understand and avoid dealing with promises explicitly, we use the Angular testing module’s async call to ensure that all of the asynchronous code has finished before the next block of code is run. Essentially this means that the asynchronous code can be read synchronously.
Once this is done we get references to the ComponentFixture of type LoginComponent and the LoginComponent itself:
let component: LoginComponent;
let fixture: ComponentFixture<LoginComponent>;
beforeEach(() => {
fixture = TestBed.createComponent(LoginComponent);
component = fixture.componentInstance;
fixture.detectChanges();
});
When we start writing tests we will see how these two variables can be used to interact with our component and to assert that it is behaving correctly.
Jasmine provides the syntax for writing our tests in a behaviour driven style. A detailed analysis of Jasmine is beyond the scope of this post. For more information read the docs. For now all you need to know is that Jasmine is what we are using when we use beforeEach, describe, it and expect etc. functions.
Time to add some tests!
Now we can begin adding tests to cover our design contract, I.E. the things that our component will do, when interacted with in specific ways.
I normally just set up a bunch of empty it blocks as below with the things I’m expecting the component to do. Notice that this reflects our original design contract:
it('should have a form named loginForm', () => {
});
it('should have an input box of type text with the name username', () => {
});
it('should have an input box of type password with the name password', () => {
});
it('should have a button with the text login that emits an event with a payload with username and password, based on form inputs', () => {
});
At this stage we are just looking to organise our thoughts. Once we are relatively happy that we know what we want to test, we can start adding the code to actually test the component. These new tests will fail, as we haven’t written any code yet. Then we can write code to make them pass and in theory our component will work.
Let’s start with the first test ‘should have a form name loginForm’:
it('should have a form named loginForm', () => {
expect(fixture.debugElement.query(By.css('form[name=loginForm]'))).toBeTruthy();
});
Here, the fixture variable allows us to query our component and check it’s DOM for whether certain elements are present. In this case we are checking that a form with the attribute name=loginForm is present on the component. Obviously currently this is not true, so if your tests are still running, they should fail now:
For a more detailed look at how to query your components for specific DOM elements etc. it is best to look at the Angular documentation on testing
OK so now we have a failing test, let’s fix it. Adding the following code to your login.component.html ought to do it:
<form name="loginForm"></form>
Now let’s fill in the rest of login.component.spec.ts:
it('should create', () => {
expect(component).toBeTruthy();
});
it('should have a form named loginForm', () => {
expect(fixture.debugElement.query(By.css('form[name=loginForm]'))).toBeTruthy();
});
it('should have an input box of type text with the name username', () => {
expect(fixture.debugElement.query(By.css('input[type="text"][name="username"'))).toBeTruthy();
});
it('should have an input box of type password with the name password', () => {
expect(fixture.debugElement.query(By.css('input[type="password"][name="password"'))).toBeTruthy();
});
describe('loginButton', () => {
it('should have a button with id loginButton and text \"Login\"', () => {
const loginButton = fixture.debugElement.query(By.css('button[id=loginButton]'));
expect(loginButton).toBeTruthy();
expect(loginButton.nativeElement.innerText).toEqual('Login');
});
});
If you run your tests again now you should have some failing specs. To fix them, add the following code to your login.component.ts file:
<form name="loginForm">
<input type="text" name="username">
<input type="password" name="password">
<button id="loginButton">Login</button>
</form>
run the tests again:
So now we have a tested component, designed to a contract, which has a spec file documenting what HTML elements are present on it. Pretty cool! Now if anyone accidentally breaks that contract, a big red message will tell them off 🙂
Notice that in the Karma chrome test output, our component is being rendered to the screen. This is important to understand. We are actually testing our component with a browser to ensure that it is rendered and behaves correctly. This is very powerful!
You might have noticed that our test specification has changed slightly from the first round of tests. This is fine and in fact a good thing. As you start to develop you may find that your assumptions were wrong, and you should adjust your tests and assumptions as you go to reflect any new information or changed design decisions.
Clearly at the moment our component is a bit limited in functionality. Let’s add a test to check that when the button is clicked, it emits an event with username and password based on the form field values:
describe('loginButton', () => {
let loginButton: DebugElement;
beforeEach(() => {
loginButton = fixture.debugElement.query(By.css('button[id=loginButton][type="submit"]'));
});
it('should have a button of type submit with id loginButton and text "Login"', () => {
expect(loginButton).toBeTruthy();
expect(loginButton.nativeElement.innerText).toEqual('Login');
});
it('should have a button that emits an event with a payload of username and password, based on form inputs', (done) => {
// set up test data for use in our test
const testUserDetails = {
username: 'user01',
password: 'superSweetPassword01!'
};
// subscribe to the emitted login event and ensure that it fires and has correct data
component.login.subscribe((data) => {
expect(data).toEqual(testUserDetails);
done();
});
// find the input fields and the login button in the DOM and interact with them
const usernameInput = fixture.debugElement.query(By.css('input[name=username]')).nativeElement;
const passwordInput = fixture.debugElement.query(By.css('input[name=password]')).nativeElement;
usernameInput.value = testUserDetails.username;
usernameInput.dispatchEvent(new Event('input'));
passwordInput.value = testUserDetails.password;
passwordInput.dispatchEvent(new Event('input'));
loginButton.nativeElement.click();
// trigger change detection so our code actually updates
fixture.detectChanges();
});
});
I will be honest, this code is a bit more complex than what we have seen so far… let’s break it down:
We need to test that our component emits an event called onLogin which has the correct data when the login button is clicked. This is something we would probably achieve in Angular by using an EventEmitter, which emits a stream from the component that can be subscribed to. As it is a stream it is asynchronous, so here we make use of Jasmine’s method for dealing with testing asynchronous code: namely the done method. By default, if the done() call is not carried out within 5000 ms then the test will fail.
it('should have a button that emits an event with a payload of username and password, based on form inputs', (done) => {
const testUserDetails = {
username: 'user01',
password: 'superSweetPassword01!'
};
component.login.subscribe((data) => {
expect(data).toEqual(testUserDetails);
done();
});
The remainder of the spec file is code dedicated to interacting with the DOM elements by sending click events etc. After we have made these changes we have to call fixture.detectChanges() in order to trigger Angular’s change detection, and actually update our test environment. Essentially what we are testing here is that after populating the form inputs via the DOM, and clicking the login button, our component emits an event. Crucially, we want to ensure where at all possible we are interacting with the DOM directly in our tests, as this is the closest simulation to how a user might interact with our component.
Again, our tests will fail now, as we haven’t written an event emitter yet, or tied it to the form inputs. To fix this we add the following code to login.component.ts so it now looks like below:
import {Component, EventEmitter, OnInit, Output} from '@angular/core';
export interface LoginDetails {
username?: string;
password?: string;
}
@Component({
selector: 'app-login',
templateUrl: './login.component.html',
styleUrls: ['./login.component.css']
})
export class LoginComponent implements OnInit {
@Output() login = new EventEmitter();
userDetails: LoginDetails = {};
onLogin() {
this.login.emit(this.userDetails);
}
constructor() { }
ngOnInit() {
}
}
And these changes to our login.component.html:
<form #loginForm name="loginForm" (ngSubmit)="onLogin()">
<input type="text" name="username" [(ngModel)]="userDetails.username">
<input type="password" name="password" [(ngModel)]="userDetails.password">
<button type="submit" id="loginButton">Login</button>
</form>
Notice that we are now using ngSubmit and ngModel. These require the FormsModule to be imported into the app.module.ts:
@NgModule({
declarations: [
AppComponent,
LoginComponent
],
imports: [
BrowserModule,
FormsModule,
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
Because TestBed is just a way of setting up a mini app, we will also have to add this FormsModule import to ourlogin.component.spec.ts:
beforeEach(async(() => {
TestBed.configureTestingModule({
imports: [FormsModule],
declarations: [LoginComponent]
})
.compileComponents();
}));
In order to properly test NgModel based code via native inputs, we also have to add the following block to our spec file, because NgModel is asynchronously updated :
beforeEach(async(() => {
fixture.detectChanges();
fixture.whenStable();
}));
With those changes, the tests should now pass:
NB While I have written the tests first for this post, quite often you will end up writing bits of functionality first and then testing them. As with most things TDD is a great tool when not used dogmatically. If you are messing around with different implementation options, it can make sense to hack about a bit first, then to add the tests. Basically don’t let the perfect be the enemy of the good 🙂 Try writing the tests first and then implementing the feature, but don’t be too rigid if you find you need to try some other stuff first. The important thing is that eventually your code is properly covered by meaningful unit tests which clarify how it is to be used, what is does, and protects it from regression bugs.
For the full source code look here
