Table of Contents

1. Introduction
2. Target audience
3. Terminology
4. Testing principles
1. What makes a good test
2. What testing can achieve
3. Tailoring your testing approach
4. The right amount of testing
5. Levels of testing
1. End-to-end tests
2. Unit tests
3. Integration tests

6. Distribution of testing efforts

7. Black box vs. white box testing

5. Example applications
1. The counter Component
2. The Flickr photo search

6. Angular testing principles

1. Testability
2. Dependency injection and faking
3. Testing tools
4. Testing conventions
5. Running the unit and integration tests
6. Configuring Karma and Jasmine

7. Test suites with Jasmine

1. Creating a test suite
2. Specifications
3. Structure of a test
4. Expectations
5. Efficient test suites

8. Faking dependencies
1. Equivalence of fake and original
2. Effective faking
3. Faking functions with Jasmine spies
4. Spying on existing methods

9. Debugging tests
1. Test focus
2. Developer tools
3. Debug output and the JavaScript debugger
4. Inspect the DOM
5. Jasmine debug runner

10. Testing Components

1. Unit test for the counter Component
2. TestBed
3. Configuring the testing Module
4. Rendering the Component
5. TestBed and Jasmine
6. ComponentFixture and DebugElement
7. Writing the first Component spec
8. Querying the DOM with test ids
9. Triggering event handlers
10. Expecting text output
11. Testing helpers
12. Filling out forms
13. Testing Inputs
14. Testing Outputs
15. Repetitive Component specs
16. Black vs. white box Component testing

11. Testing Components with children

1. Shallow vs. deep rendering
2. Unit test
3. Faking a child Component
4. Faking a child Component with ng-mocks

12. Testing Components depending on Services

1. Service dependency integration test
2. Faking Service dependencies
3. Fake Service with minimal logic
4. Faking Services: Summary
13. Testing complex forms
1. Sign-up form Component
2. Form validation and errors
3. Test plan
4. Test setup
5. Successful form submission
6. Invalid form
7. Form submission failure
8. Required fields
9. Asynchronous validators
10. Dynamic field relations
11. Password type toggle
12. Testing form accessibility
1. pa11y
2. pa11y-ci
3. Start server and run pa11y-ci

13. Form accessibility: Summary

14. Testing Components with Spectator

1. Component with an Input
2. Component with children and Service dependency
3. Event handling with Spectator
4. Spectator: Summary

15. Testing Services

1. Testing a Service with internal state
2. Testing a Service that sends HTTP requests
1. Call the method under test
2. Find pending requests
3. Respond with fake data
4. Check the result of the method call
5. Verify that all requests have been answered
6. Testing the error case
7. Alternatives for finding pending requests

3. Testing Services: Summary

16. Testing Pipes

1. GreetPipe
2. GreetPipe test
3. Testing Pipes with dependencies
1. TranslateService
2. TranslatePipe
3. TranslatePipe test

17. Testing Directives

1. Testing Attribute Directives
1. ThresholdWarningDirective
2. ThresholdWarningDirective test

2. Testing Structural Directives

1. PaginateDirective
2. PaginateDirective test

18. Testing Modules

19. Measuring code coverage
1. Coverage report
2. How to use the coverage report

20. End-to-end testing

1. Strengths of end-to-end tests
2. Deployment for end-to-end tests
3. How end-to-end tests work
4. End-to-end testing frameworks
5. Introducing Protractor
6. Introducing Cypress
7. Installing Cypress
8. Writing an end-to-end test with Cypress
9. Testing the counter Component
10. Running the Cypress tests
11. Asynchronous tests
12. Automatic retries and waiting
13. Testing the counter increment
14. Finding elements
15. Interacting with elements
16. Custom Cypress commands
17. Testing the Flickr search
1. Testing the search form
2. Testing the full photo

18. Page objects

19. Faking the Flickr API
20. End-to-end testing: Summary

21. Summary
22. Index of example applications
23. References
24. Acknowledgements
25. About
26. License
Flying probes testing a printed circuit board. Photo by genkur from iStock.
Testing Angular
A Guide to Robust Angular
Applications

The Angular Framework is a mature and

comprehensive solution for enterprise-ready
applications based on web technologies. At
Angular’s core lies the ability to test all
application parts in an automated way. How
do we take advantage of Angular’s testability?

This guide explains the principles of

automated testing as well as the practice of
testing Angular web applications. It
empowers you and your team to write
effective tests on a daily basis.
In this book, you learn how to set up your
own testing conventions, write your own
testing helpers and apply proven testing
libraries. The book covers different tests that
complement each other: unit tests,
integration tests and end-to-end tests.

With a strong focus on testing Angular

Components, this guide teaches you to write
realistic specs that describe and verify a
Component’s behavior. It demonstrates how
to properly mock dependencies like Services
to test a Component in isolation. The guide
introduces the Spectator and ng-mocks
libraries, two powerful testing libraries.

Apart from Components, the book illustrates

how to test the other application parts:
Services, Pipes, Directives as well as Modules.
Last but not least, it covers end-to-end tests
with Cypress.
Introduction
LEARNING OBJECTIVES

The benefits of automated software testing

Why testing is difficult to learn
The difference between implementation and testing
Establishing a steady testing practice

Most web developers come across automated tests in their

career. They fancy the idea of writing code to scrutinize a web
application and put it to an acid test. As web developers, as
business people, we want to know whether the site works for the
user, our customers.

Does the site allow the user to complete their tasks? Is the site
still functional after new features have been introduced or
internals have been refactored? How does the site react to usage
errors or system failure? Testing gives answers to these
questions.

I believe the benefits of automated testing are easy to grasp.

Developers want to sleep well and be confident that their
application works correctly. Moreover, testing helps developers
to write better software. Software that is more robust, better to
understand and easier to maintain.
In stark contrast, I have met only few web developers with a
steady testing practice. Only few find it easy, let alone enjoy
writing tests. This task is seen as a chore or nuisance.

Often individual developers are blamed for the lack of tests. The
claim that developers are just too ignorant or lazy to write tests
is simplistic and downright toxic. If testing has an indisputable
value, we need to examine why developers avoid it while being
convinced of the benefits. Testing should be easy, straight-
forward and commonplace.

If you are struggling with writing tests, it is not your fault or

deficit. We are all struggling because testing software is
inherently complicated and difficult.

First, writing automated tests requires a different mindset than

writing the implementation code. Implementing a feature means
building a structure – testing means trying to knock it over.

You try to find weaknesses and loopholes in your own work. You
think through all possible cases and pester your code with “What
if?” questions. What seems frustrating at first sight is an
invaluable strategy to improve your code.

Second, testing has a steep learning curve. If testing can be seen

as a tool, it is not a like a screwdriver or power drill. Rather, it
compares to a tractor or excavator. It takes training to operate
these machines. And it takes experience to apply them
accurately and safely.

This is meant to encourage you. Getting started with testing is

hard, but it gets easier and easier with more practice. The goal of
this guide is to empower you to write tests on a daily basis that
cover the important features of your Angular application.
Target audience
LEARNING OBJECTIVES

Angular topics you need to know when reading this book

Where to learn about Angular core concepts
Picking chapters you are interested in

The target audience of this guide are intermediate Angular

developers. You should be familiar with Angular’s core concepts.

TESTING, NOT IMPLEMENTATION

This guide teaches you how to test Angular application parts like
Components and Services. It assumes you know how to
implement them, but not how to test them properly. If you have
questions regarding Angular’s core concepts, please refer to the
official Angular documentation.

If you have not used individual concepts yet, like Directives, that
is fine. You can simply skip the related chapters and pick
chapters you are interested in.

JAVASCRIPT & TYPESCRIPT PROFICIENCY

Furthermore, this guide is not an introduction to JavaScript or

TypeScript. It assumes you have enough JavaScript and
TypeScript knowledge to write the implementation and test code
you need. Of course, this guide will explain special idioms
commonly used for testing.

The official Angular documentation offers a comprehensive

guide on testing. It is a recommended reading, but this guide
does not assume you have read it.
Terminology
LEARNING OBJECTIVES

Terms used in this book

Notation conventions

Before we dive in, a quick note regarding the technical terms.

Some words have a special meaning in the context of Angular. In

the broader JavaScript context, they have plenty other meanings.
This guide tries to distinguish these meanings by using a
different letter case.

When referring to core Angular concepts, this guide uses upper

case:

Module, Component, Service, Input, Output, Directive, Pipe, etc.

When using these terms in the general sense, this guide uses
lower case:

module, component, service, input, output, etc.

Testing principles
LEARNING OBJECTIVES

The goals of testing and how to achieve them

Establishing regular testing practice in your team
Classify tests by their proximity to the code
Classify tests by their knowledge of code internals

There is a gap between practical introductions – how to test a

feature – and fundamental discussions on the core concepts –
what does testing achieve, which types of tests are beneficial,
etc. Before we dive into the tutorial, we need to reflect on a few
basics about testing.

What makes a good test

When writing tests, you need to keep the goals of testing in
mind. You need to judge whether a test is valuable with regard
to these goals.

Automated testing has several technical, economical and

organizational benefits. Let us pick a few that are useful to judge
a test:

1. Testing saves time and money. Testing tries to nip software

problems in the bud. Tests prevent bugs before they cause
real damage, when they are still manageable and under
control.

Of course, quality assurance takes time and costs money

itself. But it takes less time and is cheaper than letting bugs
slip through into the software release.

When a faulty application ships to the customer, when users

run into a bug, when data is lost or corrupted, your whole
business might be at stake. After an incident, it is expensive
to analyze and fix the bug in order to regain the user’s trust.

COST-EFFECTIVE

A valuable test is cost-effective. The test prevents bugs that

could ultimately render the application unusable. The test is
cheap to write compared to the potential damage it prevents.

2. Testing formalizes and documents the requirements. A

test suite is a formal, human- and machine-readable
description of how the code should behave. It helps the
original developers to understand the requirements they
have to implement. It helps fellow developers to understand
the challenges they had to deal with.

DESCRIPTIVE
A valuable test clearly describes how the implementation
code should behave. The test uses a proper language to talk
to developers and convey the requirements. The test lists
known cases the implementation has to deal with.

3. Testing ensures that the code implements the

requirements and does not exhibit bugs. Testing taps every
part of the code in order to find flaws.

SUCCESS AND ERROR CASES

A valuable test covers the important scenarios – both

correct and incorrect input, expected cases as well as
exceptional cases.

4. Testing makes change safe by preventing regressions.

Tests not only verify that the current implementation meets
the requirements. They also verify that the code still works as
expected after changes. With proper automated tests in
place, accidentally breakage is less likely. Implementing new
features and code refactoring is safer.

PREVENT BREAKAGE

A valuable test fails when essential code is changed or

deleted. Design the test to fail if dependent behavior is
changed. It should still pass if unrelated code is changed.
What testing can achieve
Automated testing is a tool with a specific purpose. A basic
concept is that testing helps to build an application that
functions according to its requirements. That is true, but there
are certain subtleties.

The International Software Testing Qualifications Board (ISTQB)

came up with Seven Testing Principles that shed light on what
testing can achieve and what not. Without discussing every
principle, let us consider the main ideas.

DISCOVER BUGS

The purpose of a test is to discover bugs. If the test fails, it

proves the presence of a bug (or the test is set up incorrectly). If
the test passes, it proves that this particular test setup did not
trigger a bug. It does not prove that the code is correct and free
of bugs.

TEST HIGH-RISK CASES

So should you write automated tests for all possible cases to

ensure correctness? No, say the ISTQB principles: “Exhaustive
testing is impossible”. It is neither technically feasible nor
worthwhile to write tests for all possible inputs and conditions.
Instead, you should assess the risks of a certain case and write
tests for high-risk cases first.
Even if it was viable to cover all cases, it would give you a false
sense of security. No software is without errors, and a fully
tested software may still be a usability nightmare that does not
satisfy its users.

ADAPT TESTING APPROACH

Another core idea is that testing depends on its context and

that it needs to be adapted again and again to provide meaning.
The specific context in this guide are single-page web
applications written in JavaScript, made with Angular. Such
applications need specific testing methods and tools we will get
to know.

Once you have learned and applied these tools, you should not
stop. A fixed tool chain will only discover certain types of bugs.
You need to try different approaches to find new classes of bugs.
Likewise, an existing test suite needs to be updated regularly so
that it still finds regressions.

🔗 International Software Testing Qualifications Board: Certified Tester Foundation

Level Syllabus, Version 2018 V3.1, Page 16: Seven Testing Principles

Tailoring your testing approach

There is not one correct approach to testing. In fact there are
several competing schools of thoughts and methodologies.
Learn from other’s experience, but develop a testing approach
that suits your application, your team, your project or business.

EXAMINE YOUR APPLICATION

Before you start setting up tests, you should examine the

current situation of your application:

What are the critical features? For example, logging in,

searching for a record and editing a form.

What are the frequently reported technical problems and

obstacles? For example, your application may lack error
handling or cross-browser compatibility.

What are the technical requirements? For example, your

application needs to consume structured data from a given
back-end API. In turn, it needs to expose certain URL routes.

DEVELOPMENT PROCESS

This technical assessment is as important as an inquiry of your

development team:

What is the overall attitude on testing? For example, some

developers value testing while others find it ineffective to
avoid bugs.
What is the current testing practice? For example,
developers sometimes write tests, but not as a daily routine.

What is the experience on writing tests? For example, some

developers have written tests for several environments, while
others understand the basic concepts but have not yet gotten
into practice.

What are the obstacles that impede a good testing routine?

For example, developers have not been trained on the testing
tools.

Are tests well-integrated into your development workflow?

For example, a continuous integration server automatically
runs the test suite on every change set.

Once you have answered these questions, you should set up a

testing goal and implement steps to achieve it.

RETURN ON INVESTMENT

A good start is to think economically. What is the return on

investment of writing a test? Pick the low-hanging fruits. Find
business-critical features and make sure they are covered by
tests. Write tests that require little effort but cover large parts of
the code.

NORMALIZE TESTING
Simultaneously, integrate testing into your team’s workflow:

Make sure everyone shares the same basic expertise.

Offer formal training workshops and pair experienced

programmers with team members less familiar with testing.

Appoint maintainers and contact persons for test quality and

testing infrastructure.

Hire dedicated software testers, if applicable.

Writing automated tests should be easy and fun for your team
members. Remove any obstacles that make testing difficult or
inefficient.

The right amount of testing

A fierce debate revolves around the right amount of testing. Too
little testing is a problem: Features are not properly specified,
bugs go unnoticed, regressions happen. But too much testing
consumes development time, yields no additional profit and
slows down development in the long run.

So we need to reach a sweet spot. If your testing practice

deteriorates from this spot, you run into problems. If you add
more tests, you observe little benefit.

MEANINGFUL TESTS

Tests differ in their value and quality. Some tests are more
meaningful than others. If they fail, your application is actually
unusable. This means the quality of tests is more important
than their quantity.

A common metric of testing is code coverage. It counts the lines

in your code that are called by your tests. It tells you which parts
of your code are executed at all.

This metric on testing is useful but also deeply flawed because

the value of a test cannot be quantified automatically. Code
coverage tells you whether a piece of code was called, regardless
of its importance.

FIND UNCOVERED CODE

The coverage report may point to important behavior that is not

yet covered by tests, but should be. It does not tell whether the
existing tests are meaningful and make the right expectations.
You can merely infer that the code does not throw exceptions
under test conditions.

It is controversial whether one should strive for 100% code

coverage. While it is feasible to cover 100% of certain business-
critical code, it requires immense efforts to cover all parts of an
application written in Angular and TypeScript.

COVER MAIN FEATURES

If you write tests for the main features of your app from a user’s
perspective, you can achieve a code coverage of 60-70%. Every
extra percent gain takes more and more time and bears weird
and twisted tests that do not reflect the actual usage of your
application.

We are going to discuss the practical use of code coverage tools

later.

🔗 Angular guide: Code Coverage

Levels of testing
We can distinguish automated tests by their perspective and
proximity to the code.

End-to-end tests
SIMULATE REAL USAGE
Some tests have a high-level, bird’s-eye view on the application.
They simulate a user interacting with the application: Navigating
to an address, reading text, clicking on a link or button, filling
out a form, moving the mouse or typing on the keyboard. These
tests make expectations about what the user sees and reads in
the browser.

From the user’s perspective, it does not matter that your

application is implemented in Angular. Technical details like the
inner structure of your code are not relevant. There is no
distinction between front-end and back-end, between parts of
your code. The full experience is tested.

END-TO-END TESTS

These tests are called end-to-end (E2E) tests since they

integrate all parts of the application from one end (the user) to
the other end (the darkest corners of the back-end). End-to-end
tests also form the automated part of acceptance tests since
they tell whether the application works for the user.

Unit tests
Other tests have a low-level, worm’s-eye view on the application.
They pick a small piece of code and put it through its paces.
From this perspective, implementation details matter. The
developer needs to set up an appropriate testing environment to
trigger all relevant cases.

ISOLATE ONE PIECE

The shortsighted worm only sees what is directly in front. This

perspective tries to cut off the ties of the code under test with its
dependencies. It tries to isolate the code in order to examine it.

UNIT TESTS

These tests are called unit tests. A unit is a small piece of code
that is reasonable to test.

Integration tests
COHESIVE GROUPS

Between these two extreme perspectives, there are tests that

operate on specific parts of the code, but test cohesive groups.
They prescind from implementation details and try to take the
user’s perspective.

INTEGRATION TESTS

These tests are called integration tests since they test how well
the parts integrate into the group. For example, all parts of one
feature may be tested together. An integration test proves that
the parts work together properly.
Distribution of testing efforts
All levels of testing are necessary and valuable. Different types of
tests need to be combined to create a thorough test suite.

But how should we divide our attention? On which level should

we spend most of the time? Should we focus on end-to-end tests
since they mimic how the user interacts with the application?
Again, this is a controversial issue among testing experts.

SPEED

What is indisputable is that high-level tests like end-to-end tests

are expensive and slow, while lower-level tests like integration
and unit tests are cheaper and faster.

RELIABILITY

Because of their inherent complexity, end-to-end tests tend to be

unreliable. They often fail even though the software is without
fault. Sometimes they fail for no apparent reason. When you run
the same tests again, they suddenly pass. Even if the test
correctly fails, it is hard to find the root cause of the problem.
You need to wander through the full stack to locate the bug.

SETUP COSTS

End-to-end tests use a real browser and run against the full
software stack. Therefore the testing setup is immense. You
need to deploy front-end, back-end, databases, caches, etc. to
testing machines and then have machines to run the end-to-end
tests.

In comparison, integration tests are simpler and unit tests even

more so. Since they have less moving parts and fewer
dependencies, they run faster and the results are reproducible.
The setup is relatively simple. Integration and unit tests typically
run on one machine against a build of the code under test.

COST VS. BENEFIT

The crucial question for dividing your testing efforts is: Which
tests yield the most return on investment? How much work is it
to maintain a test in relation to its benefit?

In theory, the benefit of end-to-end tests is the highest, since

they indicate whether the application works for the user. In
practice, they are unreliable, imprecise and hard to debug. The
business value of integration and unit tests is estimated higher.

DISTRIBUTION

For this reason, some experts argue you should write few end-
to-end test, a fair amount of integration tests and many unit
tests. If this distribution is visualized, it looks like a pyramid:
End
to
end

Integration

Unit

These proportions are known as the Testing Pyramid. They are

widely recognized in software testing across domains, platforms
and programming languages.

However, this common distribution also drew criticism. In

particular, experts disagree on the value of unit tests.

DESIGN GUIDE

On the one hand, unit tests are precise and cheap. They are ideal
to specify all tiny details of a shared module. They help
developers to design small, composable modules that “do one
thing and do it well”. This level of testing forces developers to
reconsider how the module interacts with other modules.

CONFIDENCE
On the other hand, unit tests are too low-level to check whether
a certain feature works for the user. They give you little
confidence that your application works. In addition, unit tests
might increase the cost of every code change.

Unit tests run the risk of mirroring or even duplicating

implementation details. These details change frequently because
of new requirements elsewhere or during internal refactoring. If
you change a line of code somewhere, some distant unit test
suddenly fails.

This makes sense if you have touched shared types or shared

logic, but it may just be a false alarm. You have to fix this failing
test for technical reasons, not because something broke.

MIDDLE GROUND

Integration tests provide a better trade-off. These mid-level tests

prescind from implementation details, cover a group of code
units and provide more confidence. They are less likely to fail if
you refactor code inside of the group.

That is why some experts deem integration tests more valuable

and recommend that you spend most of your testing efforts on
this level.

In Angular, the difference between unit and integration tests is

sometimes subtle. A unit test typically focusses on a single
Angular Component, Directive, Service, Pipe, etc. Dependencies
are replaced with fakes. An integration test spans one
Component together with its children and possibly connected
Services as well. It is also possible to write a test that integrates
all parts of an Angular Module.

Comparison of software testing levels

Inte­‐
Level End-to-End Unit
gration

Coverage full large small

Performance slow fast fastest

least most
Reliability reliable
reliable reliable

Isolate Failures hard fair easy

Simulate the Real

yes no no
User

(Table adapted from a Google Testing Blog article by Mike Wacker.)

🔗 Martin Fowler: Test Pyramid

🔗 Google Testing Blog: Just Say No to More End-to-End Tests
🔗 Kent C. Dodds: Write tests. Not too many. Mostly integration.

Black box vs. white box testing

Once you have identified a piece of code you would like to test,
you have to decide how to test it properly. One important
distinction is whether a test treats the implementation as a
closed, unlit box – a black box – or an open, lit box – a white
box. In this metaphor, the code under test is a machine in a box
with holes for inputs and outputs.

OUTSIDE

Black box testing does not assume anything about the internal
structure. It puts certain values into the box and expects certain
output values. The test talks to the publicly exposed,
documented API. The inner state and workings are not
examined.

In p u
t

Black box

u t
O u tp
INSIDE
White box testing opens the box, sheds light on the internals
and takes measurements by reaching into the box. For example,
a white box test may call methods that are not part of the public
API, but still technically tangible. Then it checks the internal state
and expects that it has changed accordingly.

IRRELEVANT INTERNALS

While both approaches have their value, this guide recommends

to write black box tests whenever possible. You should check
what the code does for the user and for other parts of the code.
For this purpose, it is not relevant how the code looks internally.
Tests that make assumptions about internals are likely to break
in the future when the implementation slightly changes.

RELEVANT BEHAVIOR

More importantly, white box tests run the risk of forgetting to

check the real output. They reach into the box, spin some wheel,
flip some switch and check a particular state. They just assume
the output without actually checking it. So they fail to cover
important code behavior.

PUBLIC API

For an Angular Component, Directive, Service, Pipe, etc., a black

box test passes a certain input and expects a proper output or
measures side effects. The test only calls methods that are
marked with public in the TypeScript code. Internal methods
should be marked with private.
Example applications
LEARNING OBJECTIVES

Example Angular applications used in the book

Features demonstrated by the examples

In this guide, we will explore the different aspects of testing

Angular applications by looking at two examples.

The counter Component

🔗 Counter Component: Source code
🔗 Counter Component: Run the app
The counter is a reusable Component that increments,
decrements and resets a number using buttons and input fields.

CHALLENGING TO TEST

For intermediate Angular developers, this might look trivial. That

is intentional. This guide assumes that you know Angular basics
and that you are able to build a counter Component, but
struggle testing the ins and outs.

The goals of this example are:

Simplicity: Quickly grasp what the Component is supposed
to do.

Cover core Angular features: Reusable Components with

state, Inputs, Outputs, templates, event handling.

Scalability: Starting point for more complex application

architectures.

STATE MANAGEMENT

The counter comes in three flavors with different state

management solutions:

1. An independent, self-sufficient counter Component that

holds its own state.

2. A counter that is connected to a Service using dependency

injection. It shares its state with other counters and changes
it by calling Service methods.

3. A counter that is connected to a central NgRx Store. (NgRx is

a popular state management library.) The counter changes
the state indirectly by dispatching NgRx Actions.

While the counter seems easy to implement, it already offers

valuable challenges from a testing perspective.
The Flickr photo search
🔗 Flickr photo search: Source code
🔗 Flickr photo search: Run the app
This application allows you to search for photos on Flickr, the
popular photo hosting site.

TYPICAL APPLICATION FLOW

First, you enter a search term and start the search. The Flickr
search API is queried. Second, the search results with thumbnails
are rendered. Third, you can select a search result to see the
photo details.

This application is straight-forward and relatively simple to

implement. Still it raises important questions:

App structure: How to split responsibilities into Components

and how to model dependencies.

API communication: How to fetch data by making HTTP

requests and update the user interface.

State management: Where to hold the state, how to pass it

down in the Component tree, how to alter it.

The Flickr search comes in two flavors using different state

management solutions:
STATE MANAGEMENT

1. The state is managed in the top-level Component, passed

down in the Component tree and changed using Outputs.

2. The state is managed by an NgRx Store. Components are

connected to the store to pull state and dispatch Actions. The
state is changed in a Reducer. The side effects of an Action
are handled by NgRx Effects.

Once you are able to write automatic tests for this example
application, you will be able to test most features of a typical
Angular application.
Angular testing principles
LEARNING OBJECTIVES

Angular’s architectural principles that facilitate testing

Standard and alternative testing tools
Running and configuring unit and integration tests with Karma and Jasmine

Testability
In contrast to other popular front-end JavaScript libraries,
Angular is an opinionated, comprehensive framework that
covers all important aspects of developing a JavaScript web
application. Angular provides high-level structure, low-level
building blocks and means to bundle everything together into a
usable application.

TESTABLE ARCHITECTURE

The complexity of Angular cannot be understood without

considering automated testing. Why is an Angular application
structured into Components, Services, Modules, etc.? Why are
the parts intertwined the way they are? Why do all parts of an
Angular application apply the same patterns?

An important reason is testability. Angular’s architecture

guarantees that all application parts can be tested easily in a
similar way.

WELL-STRUCTURED CODE

We know from experience that code that is easy to test is also

simpler, better structured, easier to read and easier to
understand. The main technique of writing testable code is to
break code into smaller chunks that “do one thing and do it well”.
Then couple the chunks loosely.

Dependency injection and faking

A major design pattern for loose coupling is dependency
injection and the underlying inversion of control. Instead of
creating a dependency itself, an application part merely declares
the dependency. The tedious task of creating and providing the
dependency is delegated to an injector that sits on top.

This division of work decouples an application part from its

dependencies: One part does not need to know how to set up a
dependency, let alone the dependency’s dependencies and so
forth.

LOOSE COUPLING

Dependency injection turns tight coupling into loose coupling. A

certain application part no longer depends on a specific class,
function, object or other value. It rather depends on an abstract
token that can be traded in for a concrete implementation. The
injector takes the token and exchanges it for a real value.

ORIGINAL OR FAKE

This is of immense importance for automated testing. In our

test, we can decide how to deal with a dependency:

We can either provide an original, fully-functional

implementation. In this case, we are writing an integration
test that includes direct and indirect dependencies.

Or we provide a fake implementation that does not have side

effects. In this case, we are writing a unit test that tries to test
the application part in isolation.

A large portion of the time spent while writing tests is spent on

decoupling an application part from its dependencies. This guide
will teach you how to set up the test environment, isolate an
application part and reconnect it with equivalent fake objects.

🔗 Angular guide: Dependency injection

Testing tools
Angular provides solid testing tools out of the box. When you
create an Angular project using the command line interface, it
comes with a fully-working testing setup for unit, integration and
end-to-end tests.

BALANCED DEFAULTS

The Angular team already made decisions for you: Jasmine as

testing framework and Karma as test runner. Implementation
and test code is bundled with Webpack. Application parts are
typically tested inside Angular’s TestBed.

This setup is a trade-off with strengths and weaknesses. Since it

is just one possible way to test Angular applications, you can
compile your own testing tool chain.

ALTERNATIVES

For example, some Angular developers use Jest instead of

Jasmine and Karma. Some use Spectator or the Angular Testing
Library instead of using TestBed directly.

These alternatives are not better or worse, they simply make

different trade-offs. This guide uses Jasmine and Karma for unit
and integration tests. Later, you will learn about Spectator.

Once you have reached the limits of a particular setup, you

should investigate whether alternatives make testing your
application easier, faster and more reliable.
Testing conventions
Angular offers some tools and conventions on testing. By design,
they are flexible enough to support different ways of testing. So
you need to decide how to apply them.

MAKING CHOICES

This freedom of choice benefits experts, but confuses beginners.

In your project, there should be one preferable way how to test a
specific application part. You should make choices and set up
project-wide conventions and patterns.

CAST CONVENTIONS INTO CODE

The testing tools that ship with Angular are low-level. They
merely provide the basic operations. If you use these tools
directly, your tests become messy, repetitive and hard to
maintain.

Therefore, you should create high-level testing tools that cast

your conventions into code in order to write short, readable and
understandable tests.

This guide values strong conventions and introduces helper

functions that codify these conventions. Again, your mileage
may vary. You are free to adapt these tools to your needs or
build other testing helpers.
Running the unit and integration
tests
The Angular command line interface (CLI) allows you to run the
unit, integration and end-to-end tests. If you have not installed
the CLI yet or need to update to the latest version, run this
command on your shell:

npm install -g @angular/cli

This installs Angular CLI globally so the ng command can be

used everywhere. ng itself does nothing but exposing a couple of
Angular-specific commands.

For example, ng new creates a new Angular project directory

with a ready-to-use application scaffold. ng serve starts a
development server, and ng build makes a build.

The command for starting the unit and integration tests is:

ng test

This command does several things at once.

TEST.TS

First, ng test uses Webpack to compile your code into a

JavaScript bundle. The entry point for the bundle is
src/test.ts. This file initializes the Angular testing
environment – the TestBed – and then imports all files in the
directory tree that match the pattern .spec.ts.

MAIN.TS

You might be familiar with the entry point for the application,
src/main.ts. This file also initializes Angular, but then it
typically bootstraps (loads and starts) the AppModule. The
AppModule imports other Modules, Components, Services, etc.
This way, the bundler finds all parts of the application.

The test bundle with the entry point test.ts works differently.
It does not start with one Module and walks through all its
dependencies. It merely imports all files whose name ends with
.spec.ts.

.SPEC.TS

Each .spec.ts file represents a test. Typically, one .spec.ts

file contains at least one Jasmine test suite (more on that in the
next chapter). The files are co-located with the implementation
code.

In our example application, the CounterComponent is located in

src/app/components/counter/counter.component.ts. The
corresponding test file sits in
src/app/components/counter/counter.component.spec.ts. This is
an Angular convention, not a technical necessity, and we are
going to stick to it.

KARMA

Second, ng test launches Karma, the test runner. Karma starts

a development server at http://localhost:9876/ that serves the
JavaScript bundles compiled by Webpack.

Karma then launches one or more browsers. The idea of Karma

is to run the same tests in different browsers to ensure cross-
browser interoperability. All widely used browsers are supported:
Chrome, Internet Explorer, Edge, Firefox and Safari. Per default,
Karma starts Chrome.

TEST RUNNER

The launched browser navigates to http://localhost:9876/.

As mentioned, this site serves the test runner and the test
bundle. The tests start immediately. You can track the progress
and read the results in the browser and on the shell.

When running the tests in the counter project, the browser

output looks like this:
This is the shell output:

INFO [karma-server]: Karma v5.0.7 server started at

http://0.0.0.0:9876/

INFO [launcher]: Launching browsers Chrome with concurrency

unlimited

INFO [launcher]: Starting browser Chrome

WARN [karma]: No captured browser, open http://localhost:9876/

INFO [Chrome 84.0.4147.135 (Mac OS 10.15.6)]: Connected on socket

yH0-wtoVtflRWMoWAAAA with id 76614320

Chrome 84.0.4147.135 (Mac OS 10.15.6): Executed 46 of 46 SUCCESS

(0.394 secs / 0.329 secs)

TOTAL: 46 SUCCESS

Webpack watches changes on the .spec.ts files and files

imported by them. When you change the implementation code,
counter.component.ts for example, or the test code,
counter.component.spec.ts for example, Webpack
automatically re-compiles the bundle and pushes it to the open
browsers. All tests will be restarted.

RED-GREEN CYCLE

This feedback cycle allows you to work on the implementation

and test code side-by-side. This is important for test-driven
development. You change the implementation and expect the
test to fail – the test is “red”. You adapt the test so it passes again
– the test is “green”. Or you write a failing test first, then adapt
the implementation until the test passes.

Test-driven development means letting the red-green cycle

guide your development.

🔗 Angular CLI reference: ng test

Configuring Karma and Jasmine

Karma and Jasmine are configured in the file karma.conf.js in
the project’s root directory. There are many configuration
options and plenty of plugins, so we will only mention a few.

LAUNCHERS

As mentioned, the standard configuration opens Chrome. To run

the tests in other browsers, we need to install different
launchers.

The launcher needs to be loaded in the plugins array:

plugins: [

require('karma-jasmine'),

require('karma-chrome-launcher'),

require('karma-jasmine-html-reporter'),

require('karma-coverage'),

require('@angular-devkit/build-angular/plugins/karma')

],

There is already one launcher, karma-chrome-launcher. This is

an npm package.

To install other launchers, we first need to install the respective

npm package. Let us install the Firefox launcher. Run this shell
command:

npm install --save-dev karma-firefox-launcher

Then we require the package in karma.conf.js:

plugins: [

require('karma-jasmine'),

require('karma-chrome-launcher'),

require('karma-firefox-launcher'),

require('karma-jasmine-html-reporter'),

require('karma-coverage'),

require('@angular-devkit/build-angular/plugins/karma'),

],

If we want Karma to launch Firefox when the tests run, we also

need to add it to the list of browsers: browsers: ['Chrome']
becomes browsers: ['Chrome', 'Firefox'].

REPORTERS

Another important concept of Karma are reporters. They format

and output the test results. In the default configuration, three
reporters are active:

1. The built-in progress reporter is responsible for the text

output on the shell. While the tests run, it outputs the
progress:

Chrome 84.0.4147.135 (Mac OS 10.15.6): Executed

9 of 46 SUCCESS (0.278 secs / 0.219 secs)

And finally:

Chrome 84.0.4147.135 (Mac OS 10.15.6): Executed

46 of 46 SUCCESS (0.394 secs / 0.329 secs)

TOTAL: 46 SUCCESS

2. The standard HTML reporter kjhtml (npm package: karma-

jasmine-html-reporter) renders the results in the
browser.
3. The coverage reporter (npm package: karma-coverage)
creates the test coverage report. See measuring code
coverage.

By editing the reporters array, you can add reporters or

replace the existing ones:

reporters: ['progress', 'kjhtml'],

For example, to add a reporter that creates JUnit XML reports,

first install the npm package:

npm install --save-dev karma-junit-reporter

Next, require it as a plugin:

plugins: [

require('karma-jasmine'),

require('karma-chrome-launcher'),

require('karma-jasmine-html-reporter'),

require('karma-coverage'),

require('karma-junit-reporter'),

require('@angular-devkit/build-angular/plugins/karma'),

],

Finally, add the reporter:

reporters: ['progress', 'kjhtml', 'junit'],

When we run the tests with ng test, we will find an XML report
file in the project directory.

JASMINE CONFIGURATION

The configuration for the Jasmine adapter is located in the

client object. To configure Jasmine itself, we need to add the
jasmine property:

client: {

// leave Jasmine Spec Runner output visible in browser

clearContext: false,

jasmine: {

// Jasmine configuration goes here!

},

},

This guide recommends to activate one useful Jasmine

configuration option: failSpecWithNoExpectations lets the
test fail if it does not contain at least one expectation. (More on
expectations later.) In almost all cases, specs without
expectations stem from an error in the test code.

client: {

// leave Jasmine Spec Runner output visible in browser

clearContext: false,

jasmine: {

failSpecWithNoExpectations: true,

},

},

🔗 Karma documentation: Configuration File

🔗 Karma documentation: Plugins
🔗 npm: List of Karma plugins
🔗 Jasmine reference: Configuration options
Test suites with Jasmine
LEARNING OBJECTIVES

Introducing the Jasmine testing framework

Writing test suites, specs and assertions
Structuring a spec with Arrange, Act, Assert
Efficient test suites with setup and teardown logic

Angular ships with Jasmine, a JavaScript framework that enables

you to write and execute unit and integration tests. Jasmine
consists of three important parts:

1. A library with classes and functions for constructing tests.

2. A test execution engine.

3. A reporting engine that outputs test results in different

formats.

If you are new to Jasmine, it is recommended to read the official

Jasmine tutorial. This guide provides a short introduction to
Jasmine, exploring the basic structure and terminology that will
be used throughout this guide.

Creating a test suite

In terms of Jasmine, a test consists of one or more suites. A suite
is declared with a describe block:

describe('Suite description', () => {

/* … */

});

Each suite describes a piece of code, the code under test.

DESCRIBE: SUITE

describe is a function that takes two parameters.

1. A string with a human-readable name. Typically the name of

the function or class under test. For example,
describe('CounterComponent', /* … */) is the suite
that tests the CounterComponent class.

2. A function containing the suite definition.

A describe block groups related specs that we will learn about

in the next chapter.

NESTING DESCRIBE

describe blocks can be nested to structure big suites and divide

them into logical sections:

describe('Suite description', () => {

describe('One aspect', () => {

/* … */

});

describe('Another aspect', () => {

/* … */

});

});

Nested describe blocks add a human-readable description to a

group of specs. They can also host their own setup and teardown
logic.

Specifications
IT: SPEC

Each suit consists of one or more specifications, or short, specs. A

spec is declared with an it block:

describe('Suite description', () => {

it('Spec description', () => {

/* … */

});

/* … more specs … */

});

Again, it is a function that takes two parameters. The first

parameter is a string with a human-readable description. The
second parameter is a function containing the spec code.

READABLE SENTENCE
The pronoun it refers to the code under test. it should be the
subject of a human-readable sentence that asserts the behavior
of the code under test. The spec code then proves this assertion.
This style of writing specs originates from the concept of
Behavior-Driven Development (BDD).

One goal of BDD is to describe software behavior in a natural

language – in this case, English. Every stakeholder should be
able to read the it sentences and understand how the code is
supposed to behave. Team members without JavaScript
knowledge should be able to add more requirements by forming
it does something sentences.

Ask yourself, what does the code under test do? For example, in
case of a CounterComponent, it increments the counter value.
And it resets the counter to a specific value. So you could write:

it('increments the count', () => {

/* … */

});

it('resets the count', () => {

/* … */

});

After it, typically a verb follows, like increments and resets in

the example.

NO “SHOULD”
Some people prefer to write it('should increment the
count', /* … */), but should bears no additional meaning.
The nature of a spec is to state what the code under test should
do. The word “should” is redundant and just makes the sentence
longer. This guide recommends to simply state what the code
does.

🔗 Jasmine tutorial: Your first suite

Structure of a test
Inside the it block lies the actual testing code. Irrespective of
the testing framework, the testing code typically consists of
three phases: Arrange, Act and Assert.

ARRANGE, ACT, ASSERT

1. Arrange is the preparation and setup phase. For example,

the class under test is instantiated. Dependencies are set up.
Spies and fakes are created.

2. Act is the phase where interaction with the code under test
happens. For example, a method is called or an HTML
element in the DOM is clicked.
3. Assert is the phase where the code behavior is checked and
verified. For example, the actual output is compared to the
expected output.

How could the structure of the spec it('resets the count',

/* … */) for the CounterComponent look like?

1. Arrange:

Create an instance of CounterComponent.

Render the Component into the document.

2. Act:

Find and focus the reset input field.

Enter the text “5”.

Find and click the “Reset” button.

3. Assert:

Expect that the displayed count now reads “5”.

STRUCTURE A TEST

This structure makes it easier to come up with a test and also to

implement it. Ask yourself:
What is the necessary setup? Which dependencies do I need
to provide? How do they behave? (Arrange)

What is the user input or API call that triggers the behavior I
would like to test? (Act)

What is the expected behavior? How do I prove that the

behavior is correct? (Assert)

GIVEN, WHEN, THEN

In Behavior-Driven Development (BDD), the three phases of a

test are fundamentally the same. But they are called Given,
When and Then. These plain English words try to avoid technical
jargon and pose a natural way to think of a test’s structure:
“Given these conditions, when the user interacts with the
application, then it behaves in a certain way.”

Expectations
In the Assert phase, the test compares the actual output or
return value to the expected output or return value. If they are
the same, the test passes. If they differ, the test fails.

Let us examine a simple contrived example, an add function:

const add = (a, b) => a + b;

A primitive test without any testing tools could look like this:

const expectedValue = 5;

const actualValue = add(2, 3);

if (expectedValue !== actualValue) {

throw new Error(

`Wrong return value: ${actualValue}. Expected:

${expectedValue}`

);

EXPECT

We could write that code in a Jasmine spec, but Jasmine allows

us to create expectations in an easier and more concise manner:
The expect function together with a matcher.

const expectedValue = 5;

const actualValue = add(2, 3);

expect(actualValue).toBe(expectedValue);

First, we pass the actual value to the expect function. It returns

an expectation object with methods for checking the actual
value. We would like to compare the actual value to the expected
value, so we use the toBe matcher.

MATCHERS

toBe is the simplest matcher that applies to all possible

JavaScript values. Internally, it uses JavaScript’s strict equality
operator ===. expect(actualValue)​
.toBe(expectedValue)
essentially runs actualValue === expectedValue.
toBe is useful to compare primitive values like strings, numbers
and booleans. For objects, toBe matches only if the actual and
the expected value are the very same object. toBe fails if two
objects are not identical, even if they happen to have the same
properties and values.

For checking the deep equality of two objects, Jasmine offers the
toEqual matcher. This example illustrates the difference:

// Fails, the two objects are not identical

expect({ name: 'Linda' }).toBe({ name: 'Linda' });

// Passes, the two objects are not identical but deeply equal

expect({ name: 'Linda' }).toEqual({ name: 'Linda' });

Jasmine has numerous useful matchers built-in, toBe and

toEqual being the most common. You can add custom
matchers to hide a complex check behind a short name.

READABLE SENTENCE

The pattern
expect(actualValue).toEqual(expectedValue) originates
from Behavior-Driven Development (BDD) again. The expect
function call and the matcher methods form a human-readable
sentence: “Expect the actual value to equal the expected value.”
The goal is to write a specification that is as readable as a plain
text but can be verified automatically.
🔗 Jasmine documentation: Built-in matchers
🔗 Jasmine tutorials: Custom matchers

Efficient test suites

When writing multiple specs in one suite, you quickly realize that
the Arrange phase is similar or even identical across these specs.
For example, when testing the CounterComponent, the Arrange
phase always consists of creating a Component instance and
rendering it into the document.

REPETITIVE SETUP

This setup is repeated over and over, so it should be defined

once in a central place. You could write a setup function and call
it at the beginning of each spec. But using Jasmine, you can
declare code that is called before and after each spec, or before
and after all specs.

For this purpose, Jasmine provides four functions: beforeEach,

afterEach, beforeAll and afterAll. They are called inside of
a describe block, just like it. They expect one parameter, a
function that is called at the given stages.

describe('Suite description', () => {

beforeAll(() => {

console.log('Called before all specs are run');

});

afterAll(() => {

console.log('Called after all specs are run');

});

beforeEach(() => {

console.log('Called before each spec is run');

});

afterEach(() => {

console.log('Called after each spec is run');

});

it('Spec 1', () => {

console.log('Spec 1');

});

it('Spec 2', () => {

console.log('Spec 2');

});

});

This suite has two specs and defines shared setup and teardown
code. The output is:

Called before all specs are run

Called before each spec is run

Spec 1

Called after each spec is run

Called before each spec is run

Spec 2

Called after each spec is run

Called after all specs are run

Most tests we are going to write will have a beforeEach block to

host the Arrange code.
Faking dependencies
LEARNING OBJECTIVES

Testing a code unit in isolation

Replacing dependencies with fakes
Rules for creating fakes to avoid pitfalls
Using Jasmine spies to fake functions and methods

When testing a piece of code, you need to decide between an

integration test and a unit test. To recap, the integration test
includes (“integrates”) the dependencies. In contrast, the unit
test replaces the dependencies with fakes in order to isolate the
code under test.

ALSO KNOWN AS MOCKING

These replacements are also called test doubles, stubs or mocks.

Replacing a dependency is called stubbing or mocking.

Since these terms are used inconsistently and their difference is

subtle, this guide uses the term “fake” and “faking” for any
dependency substitution.

FAKING SAFELY

Creating and injecting fake dependencies is essential for unit

tests. This technique is double-edged – powerful and dangerous
at the same time. Since we will create many fakes throughout
this guide, we need to set up rules for faking dependencies to
apply the technique safely.

Equivalence of fake and original

A fake implementation must have the same shape of the
original. If the dependency is a function, the fake must have the
same signature, meaning the same parameters and the same
return value. If the dependency is an object, the fake must have
the same public API, meaning the same public methods and
properties.

REPLACEABILITY

The fake does not need to be complete, but sufficient enough to

act as a replacement. The fake needs to be equivalent to the
original as far as the code under test is concerned, not fully
equal to the original.

Imagine a fake building on a movie set. The outer shape needs

to be indistinguishable from an original building. But behind the
authentic facade, there is only a wooden scaffold. The building is
an empty shell.

The biggest danger of creating a fake is that it does not properly

mimic the original. Even if the fake resembles the original at the
time of writing the code, it might easily get out of sync later
when the original is changed.

When the original dependency changes its public API,

dependent code needs to be adapted. Also, the fake needs to be
aligned. When the fake is outdated, the unit test becomes a
fantasy world where everything magically works. The test passes
but in fact the code under test is broken.

KEEP FAKE IN SYNC

How can we ensure that the fake is up-to-date with the original?
How can we ensure the equivalence of original and fake in the
long run and prevent any possible divergence?

We can use TypeScript to enforce that the fake has a matching

type. The fake needs to be strictly typed. The fake’s type needs
to be a subset of the original’s type.

TYPE EQUIVALENCE

Then, TypeScript assures the equivalence. The compiler reminds

us to update the implementation and the fake. The TypeScript
code simply does not compile if we forget that. We will learn how
to declare matching types in the upcoming examples.

Effective faking
The original dependency code has side effects that need to be
suppressed during testing. The fake needs to effectively prevent
the original code from being executed. Strange errors may
happen if a mix of fake and original code is executed.

DO NOT MIX FAKE AND ORIGINAL

In some faking approaches, the fake inherits from the original.

Only those properties and methods are overwritten that are
currently used by the code under test.

This is dangerous since we may forget to overwrite methods.

When the code under test changes, the test may accidentally call
original methods of the dependency.

This guide will present thorough faking techniques that do not

allow a slip. They imitate the original code while shielding the
original from calls.

Faking functions with Jasmine spies

Jasmine provides simple yet powerful patterns to create fake
implementations. The most basic pattern is the Jasmine spy for
replacing a function dependency.

CALL RECORD
In its simplest form, a spy is a function that records its calls. For
each call, it records the function parameters. Using this record,
we later assert that the spy has been called with particular input
values.

For example, we declare in a spec: “Expect that the spy has been
called two times with the values mickey and minnie,
respectively.”

Like every other function, a spy can have a meaningful return

value. In the simple case, this is a fixed value. The spy will always
return the same value, regardless of the input parameters. In a
more complex case, the return value originates from an
underlying fake function.

CREATESPY

A standalone spy is created by calling jasmine.createSpy:

const spy = jasmine.createSpy('name');

createSpy expects one parameter, an optional name. It is

recommended to pass a name that describes the original. The
name will be used in error messages when you make
expectations against the spy.

Assume we have class TodoService responsible for fetching a

to-do list from the server. The class uses the Fetch API to make
an HTTP request. (This is a plain TypeScript example. It is
uncommon to use fetch directly in an Angular app.)

class TodoService {

constructor(

// Bind `fetch` to `window` to ensure that `window` is the

`this` context

private fetch = window.fetch.bind(window)

) {}

public async getTodos(): Promise<string[]> {

const response = await this.fetch('/todos');

if (!response.ok) {

throw new Error(

`HTTP error: ${response.status} ${response.statusText}`

);

return await response.json();

INJECT FAKE

The TodoService uses the constructor injection pattern. The

fetch dependency can be injected via an optional constructor
parameter. In production code, this parameter is empty and
defaults to the original window.fetch. In the test, a fake
dependency is passed to the constructor.

The fetch parameter, whether original or fake, is saved as an

instance property this.fetch. Eventually, the public method
getTodos uses it to make an HTTP request.

In our unit test, we do not want the Service to make any HTTP
requests. We pass in a Jasmine spy as replacement for
window.fetch.

// Fake todos and response object

const todos = [

'shop groceries',

'mow the lawn',

'take the cat to the vet'

];

const okResponse = new Response(JSON.stringify(todos), {

status: 200,

statusText: 'OK',

});

describe('TodoService', () => {

it('gets the to-dos', async () => {

// Arrange

const fetchSpy = jasmine.createSpy('fetch')

.and.returnValue(okResponse);

const todoService = new TodoService(fetchSpy);

// Act

const actualTodos = await todoService.getTodos();

// Assert

expect(actualTodos).toEqual(todos);

expect(fetchSpy).toHaveBeenCalledWith('/todos');

});

});

There is a lot to unpack in this example. Let us start with the fake
data before the describe block:

const todos = [

'shop groceries',

'mow the lawn',

'take the cat to the vet'

];

const okResponse = new Response(JSON.stringify(todos), {

status: 200,

statusText: 'OK',

});

First, we define the fake data we want the fetch spy to return.
Essentially, this is an array of strings.

FAKE RESPONSE

The original fetch function returns a Response object. We

create one using the built-in Response constructor. The original
server response is a string before it is parsed as JSON. So we
need to serialize the array into a string before passing it to the
Response constructor. (These fetch details are not relevant to
grasp the spy example.)

Then, we declare a test suite using describe:

describe('TodoService', () => {

/* … */

});

The suite contains one spec that tests the getTodos method:

it('gets the to-dos', async () => {

/* … */

});

The spec starts with Arrange code:

// Arrange

const fetchSpy = jasmine.createSpy('fetch')

.and.returnValue(okResponse);

const todoService = new TodoService(fetchSpy);

Here, we create a spy. With .and.returnValue(…), we set a

fixed return value: the successful response.

INJECT SPY

We also create an instance of TodoService, the class under test.

We pass the spy into the constructor. This is a form of manual
dependency injection.

In the Act phase, we call the method under test:

const actualTodos = await todoService.getTodos();

getTodos returns a Promise. We use an async function

together with await to access the return value easily. Jasmine
deals with async functions just fine and waits for them to
complete.

In the Assert phase, we create two expectations:

expect(actualTodos).toEqual(todos);

expect(fetchSpy).toHaveBeenCalledWith('/todos');

DATA PROCESSING

First, we verify the return value. We compare the actual data

(actualTodos) with the fake data the spy returns (todos). If
they are equal, we have proven that getTodos parsed the
response as JSON and returned the result. (Since there is no
other way getTodos could access the fake data, we can deduce
that the spy has been called.)

VERIFY CALL RECORD

Second, we verify that the fetch spy has been called with the
correct parameter, the API endpoint URL. Jasmine offers several
matchers for making expectations on spies. The example uses
toHaveBeenCalledWith to assert that the spy has been called
with the parameter '/todos'.

Both expectations are necessary to guarantee that getTodos

works correctly.

HAPPY AND UNHAPPY PATHS

After having written the first spec for getTodos, we need to ask
ourselves: Does the test fully cover its behavior? We have tested
the success case, also called happy path, but the error case, also
called unhappy path, is yet to be tested. In particular, this error
handling code:
if (!response.ok) {

throw new Error(

`HTTP error: ${response.status} ${response.statusText}`

);

When the server response is not “ok”, we throw an error. “Ok”

means the HTTP response status code is 200-299. Examples of
“not ok” are “403 Forbidden”, “404 Not Found” and “500 Internal
Server Error”. Throwing an error rejects the Promise so the caller
of getTodos knows that fetching the to-dos failed.

The fake okResponse mimics the success case. For the error
case, we need to define another fake Response. Let us call it
errorResponse with the notorious HTTP status 404 Not Found:

const errorResponse = new Response('Not Found', {

status: 404,

statusText: 'Not Found',

});

Assuming the server does not return JSON in the error case, the
response body is simply the string 'Not Found'.

Now we add a second spec for the error case:

describe('TodoService', () => {

/* … */

it('handles an HTTP error when getting the to-dos', async () => {

// Arrange

const fetchSpy = jasmine.createSpy('fetch')

.and.returnValue(errorResponse);

const todoService = new TodoService(fetchSpy);

// Act

let error;

try {

await todoService.getTodos();

} catch (e) {

error = e;

// Assert

expect(error).toEqual(new Error('HTTP error: 404 Not Found'));

expect(fetchSpy).toHaveBeenCalledWith('/todos');

});

});

In the Arrange phase, we inject a spy that returns the error

response.

CATCHING ERRORS

In the Act phase, we call the method under test but anticipate
that it throws an error. In Jasmine, there are several ways to test
whether a Promise has been rejected with an error. The example
above wraps the getTodos call in a try/catch statement and
saves the error. Most likely, this is how implementation code
would handle the error.

In the Assert phase, we make two expectations again. Instead of

verifying the return value, we make sure the caught error is an
Error instance with a useful error message. Finally, we verify
that the spy has been called with the right value, just like in the
spec for the success case.

Again, this is a plain TypeScript example to illustrate the usage of

spies. Usually, an Angular Service does not use fetch directly
but uses HttpClient instead. We will get to know testing this
later (see Testing a Service that sends HTTP requests).

🔗 TodoService: Implementation and test code

🔗 Jasmine reference: Spies

Spying on existing methods

We have used jasmine.createSpy('name') to create a
standalone spy and have injected it into the constructor. Explicit
constructor injection is straight-forward and used extensively in
Angular code.

SPY ON OBJECT METHODS

Sometimes, there is already an object whose method we need to

spy on. This is especially helpful if the code uses global methods
from the browser environment, like window.fetch in the
example above.

For this purpose, we can use the spyOn method:

spyOn(window, 'fetch');

OVERWRITE AND RESTORE

This installs a spy on the global fetch method. Under the hood,
Jasmine saves the original window.fetch function for later and
overwrites window.fetch with a spy. Once the spec is
completed, Jasmine automatically restores the original function.

spyOn returns the created spy, enabling us to set a return value,

like we have learned above.

spyOn(window, 'fetch')

.and.returnValue(okResponse);

We can create a version of TodoService that does not rely on

construction injection, but uses fetch directly:

class TodoService {

public async getTodos(): Promise<string[]> {

const response = await fetch('/todos');

if (!response.ok) {

throw new Error(

`HTTP error: ${response.status} ${response.statusText}`

);

return await response.json();

The test suite then uses spyOn to catch all calls to

window.fetch:
// Fake todos and response object

const todos = [

'shop groceries',

'mow the lawn',

'take the cat to the vet'

];

const okResponse = new Response(JSON.stringify(todos), {

status: 200,

statusText: 'OK',

});

describe('TodoService', () => {

it('gets the to-dos', async () => {

// Arrange

spyOn(window, 'fetch')

.and.returnValue(okResponse);

const todoService = new TodoService();

// Act

const actualTodos = await todoService.getTodos();

// Assert

expect(actualTodos).toEqual(todos);

expect(window.fetch).toHaveBeenCalledWith('/todos');

});

});

Not much has changed here. We spy on fetch and make it

return okResponse. Since window.fetch is overwritten with a
spy, we make the expectation against it to verify that it has been
called.
Creating standalone spies and spying on existing methods are
not mutually exclusive. Both will be used frequently when testing
Angular applications, and both work well with dependencies
injected into the constructor.

🔗 Jasmine reference: spyOn

Debugging tests
LEARNING OBJECTIVES

Fixing problems in your test

Finding the cause of a failing test
Applying familiar debugging techniques to tests
Using Jasmine debugging features

Writing tests is as arduous as writing implementation code. You

will be stuck quite often and ask yourself why the test fails – and
sometimes why the test passes when it should rather fail.

The good news is that you can apply familiar debugging

techniques to tests as well.

Test focus
Some tests require an extensive Arrange phase, the Act phase
calls several methods or simulates complex user input. These
tests are hard to debug.

ISOLATE THE PROBLEM

When locating an error, narrow down the scope gradually:

Execute only one test, one suite, one spec, one expectation.
Per default, Karma and Jasmine compile and run all specs again
with every code change. This leads to a slow feedback cycle
when you work on a particular spec. After a code change, it may
take 10-20 seconds before you see the test result. Also one spec
might interfere with another spec.

The easiest way to narrow down the scope is to set a focus on a

suite or spec. Let us assume you have a test suite with two specs:

describe('Example spec', () => {

it('one spec', () => { /* … */ });

it('another spec', () => { /* … */ });

});

FDESCRIBE

If you want Jasmine to run only this test suite and skip all others,
change describe to fdescribe:

fdescribe('Example spec', () => {

it('one spec', () => { /* … */ });

it('another spec', () => { /* … */ });

});

FIT

If you want Jasmine to run only one spec, change it to fit:

describe('Example spec', () => {

fit('one spec', () => { /* … */ });

it('another spec', () => { /* … */ });

});

This improves the developing experience tremendously.

The Webpack module bundler still re-emits the whole bundle

even if you have only changed one line of code and even if there
is a test focus on one suite.

BUNDLE ONE FILE

In this case, you can instruct ng test to consider only the file
you are currently working on. Webpack then includes all its
dependencies, like the Angular framework, but not more.

For example, to include only tests called

counter.component.spec.ts, we call ng test with the --
include option.

ng test --include **/counter.component.spec.ts

**/counter.component.spec.ts means all files called

counter.component.spec.ts in any subdirectory.

The bundling is now fast and the feedback is almost instant

when we change implementation or test code.

Keep in mind to remove the test focus before committing your

code. There are several tools that prevent fdescribe and fit
from being committed.

🔗 Jasmine API reference: fdescribe

🔗 Jasmine API reference: fit
🔗 Angular CLI reference: ng test
🔗 Tim Deschryver: Don’t commit focused tests

Developer tools
The Jasmine test runner is just another web page made with
HTML, CSS and JavaScript. This means you can debug it in the
browser using the developer tools.

FAMILIAR DEBUGGING TOOLS

Focus the browser window and open the developer tools. In

Chrome, Firefox and Edge, you can use the F12 key.

You can use the developer tools to:

Write debug output to the console using console.log,

console.debug and friends.

Use the JavaScript debugger. You can either set breakpoints

in the developer tools or place a debugger statement.

Inspect the DOM of rendered Components.

Debug output and the JavaScript

debugger
The most primitive tool, console.log, is in fact invaluable when
debugging tests. You can place debug output both in the test
code and the implementation code.

VERSATILE CONSOLE.LOG

Use debug output to answer these questions:

Is the test, suite, spec run at all?

Does the test execution reach the log command?

Did the test call the class, method, function under test
correctly?

Are callbacks called correctly? Do Promises complete or fail?

Do Observables emit, complete or error?

For Component tests:

Is Input data passed correctly?

Are the lifecycle methods called correctly?

DEBUGGER

Some people prefer to use debugger instead of console output.

While the debugger certainly gives you more control, it halts the
JavaScript execution. It may disturb the processing of
asynchronous JavaScript tasks and the order of execution.

ASYNC LOGGING

The console methods have their own pitfalls. For performance

reasons, browsers do not write the output to the console
synchronously, but asynchronously.

If you output a complex object with console.log(object),

most browsers render an interactive representation of the object
on the console. You can click on the object to inspect its
properties.

const exampleObject = { name: 'Usagi Tsukino' };

console.log(exampleObject);

It is important to know that the rendering happens

asynchronously. If you change the object shortly after, you might
see the changed object, not the object at the time of the
console.log call.

const exampleObject = { name: 'Usagi Tsukino' };

console.log(exampleObject);

exampleObject.name = 'Sailor Moon';

On the console, the object representation may show name:

'Sailor Moon' instead of name: 'Usagi Tsukino'.

One way to prevent this confusion is to create a snapshot of the

object. You convert the object to a JSON string:

const exampleObject = { name: 'Usagi Tsukino' };

console.log(JSON.stringify(exampleObject, null, ' '));

exampleObject.name = 'Sailor Moon';

LOG A SNAPSHOT

If you want an interactive representation on the console, create a

copy of the object with JSON.stringify followed by
JSON.parse:

const exampleObject = { name: 'Usagi Tsukino' };

console.log(JSON.parse(JSON.stringify(exampleObject)));

exampleObject.name = 'Sailor Moon';

Obviously, this only works for objects that can be serialized as

JSON.
Inspect the DOM
In the next chapter, we will learn how to test Components. These
tests will render the Component into the DOM of the Jasmine
test runner page. This means you can briefly see the states of
the rendered Component in the browser.

In the screenshot above, you see the rendered Component on

the left side and the inspected DOM on the right side.

ROOT ELEMENT

The Component’s root element is rendered into the last element

in the document, below the Jasmine reporter output. Make sure
to set a focus on a single spec to see the rendered Component.
The rendered Component is interactive. For example, you can
click on buttons and the click handlers will be called. But as we
will learn later, there is no automatic change detection in the
testing environment. So you might not see the effect of the
interaction.

Jasmine debug runner

The Karma page at http://localhost:9876 loads an iframe with the
actual Jasmine instance, http://localhost:9876/context.html. This
iframe complicates debugging because the developer tools
operate on the topmost document per default.

In the developer tools, you can select the iframe window context
(Chrome is pictured):
This way you can access global objects and the DOM of the
document where the tests run.

DEBUG RUNNER WITHOUT IFRAME

Another helpful feature is Karma’s debug test runner. Click on

the big “DEBUG” button on the top-right. Then a new tab opens
with http://localhost:9876/debug.html.

The debug test runner does not have an iframe, it loads Jasmine
directly. Also it automatically logs spec runs on the shell.

If you change the test or implementation code, the debug

runner does not re-run the tests. You have to reload the page
manually.
Testing Components
LEARNING OBJECTIVES

Setting up a Component test using Angular’s testing Module

Getting familiar with Angular’s Component testing abstractions
Accessing the rendered DOM and checking text content
Simulating user input like clicks and form field input
Testing Component Input and Outputs
Using helpers functions for common Component testing tasks

Components are the power houses of an Angular application.

Components are composed to form the user interface.

A Component deals with several concerns, among others:

It renders the template into the HTML DOM.

It accepts data from parent Components using Input

properties.

It emits data to parent Components using Outputs.

It reacts to user input by registering event handlers.

It renders the content (ng-content) and templates (ng-

template) that are passed.

It binds data to form controls and allows the user to edit the
data.
It talks to Services or other state managers.

It uses routing information like the current URL and URL

parameters.

All these tasks need to be tested properly.

Unit test for the counter Component

As a first example, we are going to test the CounterComponent.

When designing a Component test, the guiding questions are:

What does the Component do, what needs to be tested? How do
I test this behavior?

COUNTER FEATURES

We will test the following features of the CounterComponent:

It displays the current count. The initial value is 0 and can be

set by an Input.

When the user activates the “+” button, the count increments.

When the user activates the “-” button, the count decrements.

When the user enters a number into the reset input field and
activates the reset button, the count is set to the given value.
When the user changes the count, an Output emits the new
count.

Writing down what the Component does already helps to

structure the unit test. The features above roughly translate to
specs in a test suite.

🔗 CounterComponent: full code

TestBed
Several chores are necessary to render a Component in Angular,
even the simple counter Component. If you look into the main.ts
and the AppModule of a typical Angular application, you find
that a “platform” is created, a Module is declared and this
Module is bootstrapped.

The Angular compiler translates the templates into JavaScript

code. To prepare the rendering, an instance of the Component is
created, dependencies are resolved and injected, inputs are set.

Finally, the template is rendered into the DOM. For testing, you
could do all that manually, but you would need to dive deeply
into Angular internals.

TESTBED
Instead, the Angular team provides the TestBed to ease unit
testing. The TestBed creates and configures an Angular
environment so you can test particular application parts like
Components and Services safely and easily.

🔗 Angular API reference: TestBed

🔗 Testing Utility APIs: TestBed

Configuring the testing Module

The TestBed comes with a testing Module that is configured like
normal Modules in your application: You can declare
Components, Directives and Pipes, provide Services and other
Injectables as well as import other Modules. TestBed has a
static method configureTestingModule that accepts a Module
definition:

TestBed.configureTestingModule({

imports: [ /*… */ ],

declarations: [ /*… */ ],

providers: [ /*… */ ],

});

DECLARE WHAT IS NECESSARY

In a unit test, add those parts to the Module that are strictly
necessary: the code under test, mandatory dependencies and
fakes. For example, when writing a unit test for
CounterComponent, we need to declare that Component class.
Since the Component does not have dependencies, does not
render other Components, Directives or Pipes, we are done.

TestBed.configureTestingModule({

declarations: [CounterComponent],

});

Our Component under test is now part of a Module. We are

ready to render it, right? Not yet. First we need to compile all
declared Components, Directives and Pipes:

TestBed.compileComponents();

This instructs the Angular compiler to translate the template files

into JavaScript code.

CONFIGURE AND COMPILE

Since configureTestingModule returns the TestBed again,

we can chain those two calls:

TestBed

.configureTestingModule({

declarations: [CounterComponent],

})

.compileComponents();

You will see this pattern in most Angular tests that rely on the
TestBed.
Rendering the Component
Now we have a fully-configured testing Module with compiled
Components. Finally, we can render the Component under test
using createComponent:

const fixture = TestBed.createComponent(CounterComponent);

createComponent returns a ComponentFixture, essentially a

wrapper around the Component with useful testing tools. We
will learn more about the ComponentFixture later.

createComponent renders the Component into a div container

element in the HTML DOM. Alas, something is missing. The
Component is not fully rendered. All the static HTML is present,
but the dynamic HTML is missing. The template bindings, like {{
count }} in the example, are not evaluated.

MANUAL CHANGE DETECTION

In our testing environment, there is no automatic change

detection. Even with the default change detection strategy, a
Component is not automatically rendered and re-rendered on
updates.

In testing code, we have to trigger the change detection

manually. This might be a nuisance, but it is actually a feature. It
allows us to test asynchronous behavior in a synchronous
manner, which is much simpler.

So the last thing we need to do is to trigger change detection:

fixture.detectChanges();

🔗 Angular API reference: ComponentFixture

TestBed and Jasmine

The code for rendering a Component using the TestBed is now
complete. Let us wrap the code in a Jasmine test suite.

describe('CounterComponent', () => {

let fixture: ComponentFixture<CounterComponent>;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [CounterComponent],

}).compileComponents();

fixture = TestBed.createComponent(CounterComponent);

fixture.detectChanges();

});

it('…', () => {

/* … */

});

});

Using describe, we define a test suite for the

CounterComponent. In contains a beforeEach block that
configures the TestBed and renders the Component.

ASYNC COMPILATION

You might wonder why the function passed to beforeEach is

marked as an async function. It is because
compileComponents is an asynchronous operation. To compile
the Components, Angular needs to fetch external the template
files referenced by templateUrl.

If you are using the Angular CLI, which is most likely, the
template files are already included in the test bundle. So they are
available instantly. If you are not using the CLI, the files have to
be loaded asynchronously.

This is an implementation detail that might change in the future.

The safe way is wait for compileComponents to complete.

ASYNC AND AWAIT

Per default, Jasmine expects that your testing code is

synchronous. The functions you pass to it but also
beforeEach, beforeAll, afterEach, afterAll need to finish
in a certain amount of time, also known as timeout. Jasmine also
supports asynchronous specs. If you pass an async function,
Jasmine waits for it to finish.
🔗 Test suites with Jasmine

ComponentFixture and
DebugElement
TestBed.createComponent(CounterComponent) returns a
fixture, an instance of ComponentFixture. What is the fixture
and what does it provide?

The term fixture is borrowed from real-world testing of

mechanical parts or electronic devices. A fixture is a standardized
frame into which the test object is mounted. The fixture holds
the object and connects to electrical contacts in order to provide
power and to take measurements.

COMPONENT­
F IXTURE

In the context of Angular, the ComponentFixture holds the

Component and provides a convenient interface to both the
Component instance and the rendered DOM.

The fixture references the Component instance via the

componentInstance property. In our example, it contains a
CounterComponent instance.

const component = fixture.componentInstance;

The Component instance is mainly used to set Inputs and

subscribe to Outputs, for example:

// This is a ComponentFixture<CounterComponent>

const component = fixture.componentInstance;

// Set Input

component.startCount = 10;

// Subscribe to Output

component.countChange.subscribe((count) => {

/* … */

});

We will learn more on testing Inputs and Outputs later.

DEBUGELEMENT

For accessing elements in the DOM, Angular has another

abstraction: The DebugElement wraps the native DOM element.
The fixture’s debugElement property returns the Component’s
host element. For the CounterComponent, this is the app-
counter element.

const { debugElement } = fixture;

The DebugElement offers handy properties like properties,

attributes, classes and styles to examine the DOM
element itself. The properties parent, children and
childNodes help navigating in the DOM tree. They return
DebugElements as well.

NATIVEELEMENT
Often it is necessary to unwrap the DebugElement to access the
native DOM element inside. Every DebugElement has a
nativeElement property:

const { debugElement } = fixture;

const { nativeElement } = debugElement;

console.log(nativeElement.tagName);

console.log(nativeElement.textContent);

console.log(nativeElement.innerHTML);

nativeElement is typed as any because Angular does not know

the exact type of the wrapped DOM element. Most of the time, it
is a subclass of HTMLElement.

When you use nativeElement, you need to learn about the

DOM interface of the specific element. For example, a button
element is represented as HTMLButtonElement in the DOM.

🔗 Angular API reference: ComponentFixture

🔗 Angular API reference: DebugElement

Writing the first Component spec

We have compiled a test suite that renders the
CounterComponent. We have met Angular’s primary testing
abstractions: TestBed, ComponentFixture and DebugElement.
Now let us roll up our sleeves and write the first spec! The main
feature of our little counter is the ability to increment the count.
Hence the spec:

it('increments the count', () => {

/* … */

});

The Arrange, Act and Assert phases help us to structure the

spec:

We have already covered the Arrange phase in the

beforeEach block that renders the Component.

In the Act phase, we click on the increment button.

In the Assert phase, we check that the displayed count has

incremented.

it('increments the count', () => {

// Act: Click on the increment button

// Assert: Expect that the displayed count now reads “1”.

});

To click on the increment button, two actions are necessary:

1. Find the increment button element in the DOM.

2. Fire a click event on it.

Let us learn about finding elements in the DOM first.

Querying the DOM with test ids
Every DebugElement features the methods query and
queryAll for finding descendant elements (children,
grandchildren and so forth).

QUERY AND QUERYALL

query returns the first descendant element that meets a

condition.

queryAll returns an array of all matching elements.

Both methods expect a predicate, that is a function judging

every element and returning true or false.

BY.CSS

Angular ships with predefined predicate functions to query the

DOM using familiar CSS selectors. For this purpose, pass
By.css('…') with a CSS selector to query and queryAll.

const { debugElement } = fixture;

// Find the first h1 element

const h1 = debugElement.query(By.css('h1'));

// Find all elements with the class .user

const userElements = debugElement.queryAll(By.css('.user'));

The return value of query is a DebugElement again, that of

queryAll is an array of DebugElements (DebugElement[] in
TypeScript notation).

In the example above, we have used a type selector (h1) and a

class selector (.user) to find elements in the DOM. For everyone
familiar with CSS, this is familiar as well.

While these selectors are fine when styling Components, using

them in a test needs to be challenged.

AVOID TIGHT COUPLING

Type and class selectors introduce a tight coupling between the

test and the template. HTML elements are picked for semantic
reasons. Classes are picked mostly for styling. Both change
frequently when the Component template is refactored. Should
the test fail if the element type or class changes?

Sometimes the element type and the class are crucial for the
feature under test. But most of the time, they are not relevant
for the feature. The test should better find the element by a
feature that never changes and that bears no additional
meaning: test ids.

TEST IDS

A test id is an identifier given to an element just for the purpose

of finding it in a test. The test will still find the element if the
element type or unrelated attributes change.
The preferred way to mark an HTML element is a data attribute.
In contrast to element types, class or id attributes, data
attributes do not come with any predefined meaning. Data
attributes never clash with each other.

DATA-TESTID

For the purpose of this guide, we use the data-testid

attribute. For example, we mark the increment button in the
CounterComponent with data-testid="increment-button":

<button (click)="increment()" data-testid="increment-button">+

</button>

In the test, we use the corresponding attribute selector:

const incrementButton = debugElement.query(

By.css('[data-testid="increment-button"]')

);

ESTABLISH A CONVENTION

There is a nuanced discussion around the best way to find

elements during testing. Certainly, there are several valid and
elaborate approaches. This guide will only present one possible
approach that is simple and approachable.

The Angular testing tools are neutral when it comes to DOM

querying. They tolerate different approaches. After
consideration, you should opt for one specific solution,
document it as a testing convention and apply it consistently
across all tests.

🔗 Angular API reference: By.css

Triggering event handlers

Now that we have marked and got hold of the increment button,
we need to click on it.

It is a common task in tests to simulate user input like clicking,

typing in text, moving pointers and pressing keys. From an
Angular perspective, user input causes DOM events.

The Component template registers event handlers using the

schema (event)="handler($event)". In the test, we need to
simulate an event to call these handlers.

TRIGGER EVENT HANDLER

DebugElement has a useful method for firing events:

triggerEventHandler. This method calls all event handlers for
a given event type like click. As a second parameter, it expects
a fake event object that is passed to the handlers:

incrementButton.triggerEventHandler('click', {

/* … Event properties … */

});

This example fires a click event on the increment button. Since

the template contains (click)="increment()", the
increment method of CounterComponent will be called.

EVENT OBJECT

The increment method does not access the event object. The
call is simply increment(), not increment($event).
Therefore, we do not need to pass a fake event object, we can
simply pass null:

incrementButton.triggerEventHandler('click', null);

It is worth noting that triggerEventHandler does not dispatch

a synthetic DOM event. The effect stays on the DebugElement
abstraction level and does not touch the native DOM.

NO BUBBLING

This is fine as long as the event handler is registered on the

element itself. If the event handler is registered on a parent and
relies on event bubbling, you need to call
triggerEventHandler directly on that parent.
triggerEventHandler does not simulate event bubbling or
any other effect a real event might have.

Expecting text output

We have completed the Act phase in which the test clicks on the
increment button. In the Assert phase, we need to expect that
the displayed count changes from “0” to “1”.

In the template, the count is rendered into a strong element:

<strong>{{ count }}</strong>

FIND BY TEST ID

In our test, we need to find this element and read its text
content. For this purpose, we add a test id:

<strong data-testid="count">{{ count }}</strong>

We can now find the element as usual:

const countOutput = debugElement.query(

By.css('[data-testid="count"]')

);

TEXT CONTENT

The next step is to read the element’s content. In the DOM, the
count is a text node that is a child of strong.

Unfortunately, the DebugElement does not have a method or

property for reading the text content. We need to access the
native DOM element that has a convenient textContent
property.

countOutput.nativeElement.textContent

Finally, we expect that this string is "1" using Jasmine’s expect:

expect(countOutput.nativeElement.textContent).toBe('1');

The counter.component.spec.ts now looks like this:

/* Incomplete! */

describe('CounterComponent', () => {

let fixture: ComponentFixture<CounterComponent>;

let debugElement: DebugElement;

// Arrange

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [CounterComponent],

}).compileComponents();

fixture = TestBed.createComponent(CounterComponent);

fixture.detectChanges();

debugElement = fixture.debugElement;

});

it('increments the count', () => {

// Act

const incrementButton = debugElement.query(

By.css('[data-testid="increment-button"]')

);

incrementButton.triggerEventHandler('click', null);

// Assert

const countOutput = debugElement.query(

By.css('[data-testid="count"]')

);

expect(countOutput.nativeElement.textContent).toBe('1');

});

});

When we run that suite, the spec fails:

CounterComponent increments the count FAILED

Error: Expected '0' to be '1'.

What is wrong here? Is the implementation faulty? No, the test

just missed something important.

MANUAL CHANGE DETECTION

We have mentioned that in the testing environment, Angular

does not automatically detect changes in order to update the
DOM. Clicking the increment button changes the count property
of the Component instance. To update the template binding {{
count }}, we need to trigger the change detection manually.

fixture.detectChanges();

The full test suite now looks like this:

describe('CounterComponent', () => {

let fixture: ComponentFixture<CounterComponent>;

let debugElement: DebugElement;

// Arrange

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [CounterComponent],

}).compileComponents();

fixture = TestBed.createComponent(CounterComponent);

fixture.detectChanges();

debugElement = fixture.debugElement;

});

it('increments the count', () => {

// Act

const incrementButton = debugElement.query(

By.css('[data-testid="increment-button"]')

);

incrementButton.triggerEventHandler('click', null);

// Re-render the Component

fixture.detectChanges();

// Assert

const countOutput = debugElement.query(

By.css('[data-testid="count"]')

);

expect(countOutput.nativeElement.textContent).toBe('1');

});

});

Congratulations! We have written our first Component test. It is

not complete yet, but it already features a typical workflow. We
will make small improvements to the existing code with each
spec we add.

🔗 CounterComponent: test code

Testing helpers
The next CounterComponent feature we need to test is the
decrement button. It is very similar to the increment button, so
the spec looks almost the same.

First, we add a test id to the decrement button:

<button (click)="decrement()" data-testid="decrement-button">-

</button>

Then we write the spec:

it('decrements the count', () => {

// Act

const decrementButton = debugElement.query(

By.css('[data-testid="decrement-button"]')

);

decrementButton.triggerEventHandler('click', null);

// Re-render the Component

fixture.detectChanges();

// Assert

const countOutput = debugElement.query(

By.css('[data-testid="count"]')

);

expect(countOutput.nativeElement.textContent).toBe('-1');

});

There is nothing new here, only the test id, the variable names
and the expected output changed.

REPEATING PATTERNS
Now we have two specs that are almost identical. The code is
repetitive and the signal-to-noise ratio is low, meaning there is
much code that does little. Let us identify the patterns repeated
here:

1. Finding an element by test id

2. Clicking on an element found by test id

3. Expecting a given text content on an element found by test id

These tasks are highly generic and they will appear in almost
every Component spec. It is worth writing testing helpers for
them.

TESTING HELPERS

A testing helper is a piece of code that makes writing tests

easier. It makes test code more concise and more meaningful.
Since a spec should describe the implementation, a readable
spec is better than an obscure, convoluted one.

Your testing helpers should cast your testing conventions into

code. They not only improve the individual test, but make sure all
tests use the same patterns and work the same.

A testing helper can be a simple function, but it can also be an

abstraction class or a Jasmine extension. For the start, we extract
common tasks into plain functions.
FIND BY TEST ID

First, let us write a helper for finding an element by test id. We

have used this pattern multiple times:

const xyzElement = fixture.debugElement.query(

By.css('[data-testid="xyz"]')

);

We move this code into a reusable function:

function findEl<T>(

fixture: ComponentFixture<T>,

testId: string

): DebugElement {

return fixture.debugElement.query(

By.css(`[data-testid="${testId}"]`)

);

This function is self-contained. We need to pass in the

Component fixture explicitly. Since ComponentFixture<T>
requires a type parameter – the wrapped Component type –,
findEl also has a type parameter called T. TypeScript will infer
the Component type automatically when you pass a
ComponentFixture.

CLICK

Second, we write a testing helper that clicks on an element with

a given test id. This helper builds on findEl.
export function click<T>(

fixture: ComponentFixture<T>,

testId: string

): void {

const element = findEl(fixture, testId);

const event = makeClickEvent(element.nativeElement);

element.triggerEventHandler('click', event);

To create a fake click event object, click calls another function,

makeClickEvent.

export function makeClickEvent(

target: EventTarget

): Partial<MouseEvent> {

return {

preventDefault(): void {},

stopPropagation(): void {},

stopImmediatePropagation(): void {},

type: 'click',

target,

currentTarget: target,

bubbles: true,

cancelable: true,

button: 0

};

This function returns a partial MouseEvent fake object with the

most important methods and properties of real click events. It is
suitable for clicks on buttons and links when the pointer position
and modifier keys do not matter.
CLICK MEANS ACTIVATE

The click testing helper can be used on every element that has
a (click)="…" event handler. For accessibility, make sure the
element can be focussed and activated. This is already the case
for buttons (button element) and links (a elements).

Historically, the click event was only triggered by mouse input.

Today, it is a generic “activate” event. It is also triggered by touch
input (“tap”), keyboard input or voice input.

So in your Component, you do not need to listen for touch or

keyboard events separately. In the test, a generic click event
usually suffices.

EXPECT TEXT CONTENT

Third, we write a testing helper that expects a given text content

on an element with a given test id.

export function expectText<T>(

fixture: ComponentFixture<T>,

testId: string,

text: string,

): void {

const element = findEl(fixture, testId);

const actualText = element.nativeElement.textContent;

expect(actualText).toBe(text);

Again, this is a simple implementation we will improve later.

Using these helpers, we rewrite our spec:

it('decrements the count', () => {

// Act

click(fixture, 'decrement-button');

// Re-render the Component

fixture.detectChanges();

// Assert

expectText(fixture, 'count', '-1');

});

That is much better to read and less to write! You can tell what
the spec is doing at first glance.

🔗 CounterComponent: test code

🔗 Element spec helpers: full code

Filling out forms

We have tested the increment and decrement button
successfully. The remaining user-facing feature we need to test
is the reset feature.

In the user interface, there is a reset input field and a reset

button. The user enters a new number into the field, then clicks
on the button. The Component resets the count to the user-
provided number.
SET FIELD VALUE

We already know how to click a button, but how do we fill out a

form field? Unfortunately, Angular’s testing tools do not provide
a solution for filling out forms easily.

The answer depends on the field type and value. The generic
answer is: Find the native DOM element and set the value
property to the new value.

For the reset input, this means:

const resetInput = debugElement.query(

By.css('[data-testid="reset-input"]')

);

resetInput.nativeElement.value = '123';

With our testing helper:

const resetInputEl = findEl(fixture, 'reset-input').nativeElement;

resetInputEl.value = '123';

This fills in the value programmatically.

In CounterComponent’s template, the reset input has a template

reference variable, #resetInput:

<input type="number" #resetInput data-testid="reset-input" />

<button (click)="reset(resetInput.value)" data-testid="reset-

button">

Reset

</button>

The click handler uses resetInput to access the input

element, reads the value and passes it to the reset method.

The example already works because the form is very simple.

Setting a field’s value is not a full simulation of user input and
will not work with Template-driven or Reactive Forms yet.

FAKE INPUT EVENT

Angular forms cannot observe value changes directly. Instead,

Angular listens for an input event that the browser fires when a
field value changes.

For compatibility with Template-driven and Reactive Forms,

we need to dispatch a fake input event. Such events are also
called synthetic events.

In newer browsers, we create a fake input event with new

Event('input'). To dispatch the event, we use the
dispatchEvent method of the target element.

const resetInputEl = findEl(fixture, 'reset-input').nativeElement;

resetInputEl.value = '123';

resetInputEl.dispatchEvent(new Event('input'));

If you need to run your tests in legacy Internet Explorer, a bit

more code is necessary. Internet Explorer does not support new
Event('…'), but the document.createEvent method:
const event = document.createEvent('Event');

event.initEvent('input', true, false);

resetInputEl.dispatchEvent(event);

The full spec for the reset feature then looks like this:

it('resets the count', () => {

const newCount = '123';

// Act

const resetInputEl = findEl(fixture, 'reset-

input').nativeElement;

// Set field value

resetInputEl.value = newCount;

// Dispatch input event

const event = document.createEvent('Event');

event.initEvent('input', true, false);

resetInputEl.dispatchEvent(event);

// Click on reset button

click(fixture, 'reset-button');

// Re-render the Component

fixture.detectChanges();

// Assert

expectText(fixture, 'count', newCount);

});

Filling out forms is a common task in tests, so it makes sense to

extract the code and put it into a helper.

HELPER FUNCTIONS
The helper function setFieldValue takes a Component fixture,
a test id and a string value. It finds the corresponding element
using findEl. Using another helper, setFieldElementValue,
it sets the value and dispatches an input event.

export function setFieldValue<T>(

fixture: ComponentFixture<T>,

testId: string,

value: string,

): void {

setFieldElementValue(

findEl(fixture, testId).nativeElement,

value

);

You can find the full source code of the involved helper functions
in element.spec-helper.ts.

Using the newly created setFieldValue helper, we can simplify

the spec:

it('resets the count', () => {

const newCount = '123';

// Act

setFieldValue(fixture, 'reset-input', newCount);

click(fixture, 'reset-button');

fixture.detectChanges();

// Assert

expectText(fixture, 'count', newCount);

});

While the reset feature is simple, this is how to test most form
logic. Later, we will learn how to test complex forms.

INVALID INPUT

The CounterComponent checks the input value before it resets

the count. If the value is not a number, clicking the reset button
does nothing.

We need to cover this behavior with another spec:

it('does not reset if the value is not a number', () => {

const value = 'not a number';

// Act

setFieldValue(fixture, 'reset-input', value);

click(fixture, 'reset-button');

fixture.detectChanges();

// Assert

expectText(fixture, 'count', startCount);

});

The small difference in this spec is that we set the field value to
“not a number”, a string that cannot be parsed as a number, and
expect the count to remain unchanged.

This is it! We have tested the reset form with both valid and
invalid input.
🔗 CounterComponent: test code
🔗 Element spec helpers: full code

Testing Inputs
CounterComponent has an Input startCount that sets the
initial count. We need to test that the counter handles the Input
properly.

For example, if we set startCount to 123, the rendered count

needs to be 123 as well. If the Input is empty, the rendered
count needs to be 0, the default value.

SET INPUT VALUE

An Input is a special property of the Component instance. We

can set this property in the Arrange phase.

const component = fixture.componentInstance;

component.startCount = 10;

It is a good practice not to change an Input value within a

Component. An Input property should always reflect the data
passed in by the parent Component.

INPUT VS. COMPONENT STATE

That is why CounterComponent has a public Input named

startCount as well as an internal property named count. When
the user clicks the increment or decrement buttons, count is
changed, but startCount remains unchanged.

Whenever the startCount Input changes, count needs to be

set to startCount. The safe place to do that is the
ngOnChanges lifecycle method:

public ngOnChanges(): void {

this.count = this.startCount;

ngOnChanges is called whenever a “data-bound property”

changes, including Inputs.

Let us write a test for the startCount Input. We set the Input in
the beforeEach block, before calling detectChanges. The spec
itself checks that the correct count is rendered.

/* Incomplete! */

beforeEach(async () => {

/* … */

// Set the Input

component.startCount = startCount;

fixture.detectChanges();

});

it('shows the start count', () => {

expectText(fixture, 'count', String(count));

});

When we run this spec, we find that it fails:

CounterComponent > shows the start count

Expected '0' to be '123'.

NGONCHANGES

What is wrong here? Did we forget to call detectChanges

again? No, but we forgot to call ngOnChanges!

In the testing environment, ngOnChanges is not called

automatically. We have to call it manually after setting the Input.

Here is the corrected example:

describe('CounterComponent', () => {

let component: CounterComponent;

let fixture: ComponentFixture<CounterComponent>;

const startCount = 123;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [CounterComponent],

}).compileComponents();

fixture = TestBed.createComponent(CounterComponent);

component = fixture.componentInstance;

component.startCount = startCount;

// Call ngOnChanges, then re-render

component.ngOnChanges();

fixture.detectChanges();

});

/* … */

it('shows the start count', () => {

expectText(fixture, 'count', String(startCount));

});

});

The CounterComponent expects a number Input and renders it

into the DOM. When reading text from the DOM, we always deal
with strings. That is why we pass in a number 123 but expect to
find the string '123'.

🔗 CounterComponent: test code

Testing Outputs
While Inputs pass data from parent to child, Outputs send data
from child to parent. In combination, a Component can perform
a specific operation just with the required data.

For example, a Component may render a form so the user can

edit or review the data. Once completed, the Component emits
the data as an Output.

Outputs are not a user-facing feature, but a vital part of the

public Component API. Technically, Outputs are Component
instance properties. A unit test must inspect the Outputs
thoroughly to proof that the Component plays well with other
Components.

The CounterComponent has an output named countChange.

Whenever the count changes, the countChange Output emits
the new value.

export class CounterComponent implements OnChanges {

/* … */

@Output()

public countChange = new EventEmitter<number>();

/* … */

SUBSCRIBE TO OBSERVABLE

EventEmitter is a subclass of RxJS Subject, which itself

extends RxJS Observable. The Component uses the emit
method to publish new values. The parent Component uses the
subscribe method to listen for emitted values. In the testing
environment, we will do the same.

Let us write a spec for the countChange Output!

it('emits countChange events on increment', () => {

/* … */

});

Within the spec, we access the Output via

fixture.componentInstance.countChange. In the Arrange
phase, we subscribe to the EventEmitter.
it('emits countChange events on increment', () => {

// Arrange

component.countChange.subscribe((count) => {

/* … */

});

});

We need to verify that the observer function is called with the

right value when the increment button is clicked. In the Act
phase, we click on the button using our helper function:

it('emits countChange events on increment', () => {

// Arrange

component.countChange.subscribe((count) => {

/* … */

});

// Act

click(fixture, 'increment-button');

});

CHANGE VARIABLE VALUE

In the Assert phase, we expect that count has the correct value.
The easiest way is to declare a variable in the spec scope. Let us
name it actualCount. Initially, it is undefined. The observer
function sets a value – or not, if it is never called.

it('emits countChange events on increment', () => {

// Arrange

let actualCount: number | undefined;

component.countChange.subscribe((count: number) => {

actualCount = count;

});

// Act

click(fixture, 'increment-button');

// Assert

expect(actualCount).toBe(1);

});

EXPECT CHANGED VALUE

The click on the button emits the count and calls the observer
function synchronously. That is why the next line of code can
expect that actualCount has been changed.

You might wonder why we did not put the expect call in the
observer function:

/* Not recommended! */

it('emits countChange events on increment', () => {

// Arrange

component.countChange.subscribe((count: number) => {

// Assert

expect(count).toBe(1);

});

// Act

click(fixture, 'increment-button');

});

ALWAYS RUN EXPECTATION

This works as well. But if the feature under test is broken and the
Output does not emit, expect is never called.

Per default, Jasmine warns you that the spec has no expectations
but treats the spec as successful (see Configuring Karma and
Jasmine). We want the spec to fail explicitly in this case, so we
make sure the expectation is always run.

Now we have verified that countChange emits when the

increment button is clicked. We also need to proof that the
Output emits on decrement and reset. We can achieve that by
adding two more specs that copy the existing spec:

it('emits countChange events on decrement', () => {

// Arrange

let actualCount: number | undefined;

component.countChange.subscribe((count: number) => {

actualCount = count;

});

// Act

click(fixture, 'decrement-button');

// Assert

expect(actualCount).toBe(-1);

});

it('emits countChange events on reset', () => {

const newCount = '123';

// Arrange

let actualCount: number | undefined;

component.countChange.subscribe((count: number) => {

actualCount = count;

});

// Act

setFieldValue(fixture, 'reset-input', newCount);

click(fixture, 'reset-button');

// Assert

expect(actualCount).toBe(newCount);

});

🔗 CounterComponent: test code

Repetitive Component specs

Testing the countChange Output with three specs works fine,
but the code is highly repetitive. A testing helper can reduce the
repetition. Experts disagree on whether repetitive testing code is
a problem at all.

On the one hand, it is hard to grasp the essence of repetitive

specs. Testing helpers form a custom language for expressing
testing instructions clearly and briefly. For example, if your specs
find DOM elements via test ids, a testing helper establishes the
convention and hides the implementation details.
On the other hand, abstractions like helper functions make tests
more complex and therefore harder to understand. A developer
reading the specs needs to get familiar with the testing helpers
first. After all, tests should be more readable than the
implementation code.

DUPLICATION VS. ABSTRACTION

There is a controversial debate in software development

regarding repetition and the value of abstractions. As Sandi Metz
famously stated, “duplication is far cheaper than the wrong
abstraction”.

This is especially true when writing specs. You should try to

eliminate duplication and boilerplate code with
beforeEach/beforeAll, simple helper functions and even
testing libraries. But do not try to apply your optimization habits
and skills to test code.

A test is supposed to reproduce all relevant logical cases. Finding

a proper abstraction for all these diverse, sometimes mutually
exclusive cases is often futile.

CAREFULLY REDUCE REPETITION

Your mileage may vary on this question. For completeness, let us

discuss how to reduce the repetition in the countChange Output
specs.
An Output is an EventEmitter, that is a fully-functional RxJS
Observable. This allows us to transform the Observable as we
please. Specifically, we can click all three buttons and then
expect that the countChange Output has emitted three values.

it('emits countChange events', () => {

// Arrange

const newCount = 123;

// Capture all emitted values in an array

let actualCounts: number[] | undefined;

// Transform the Observable, then subscribe

component.countChange.pipe(

// Close the Observable after three values

take(3),

// Collect all values in an array

toArray()

).subscribe((counts) => {

actualCounts = counts;

});

// Act

click(fixture, 'increment-button');

click(fixture, 'decrement-button');

setFieldValue(fixture, 'reset-input', String(newCount));

click(fixture, 'reset-button');

// Assert

expect(actualCounts).toEqual([1, 0, newCount]);

});

This example requires some RxJS knowledge. We are going to

encounter RxJS Observables again and again when testing
Angular applications. If you do not understand the example
above, that is totally fine. It is just an optional way to merge
three specs into one.

🔗 CounterComponent: test code

Black vs. white box Component

testing
Component tests are most meaningful if they closely mimic how
the user interacts with the Component. The tests we have
written apply this principle. We have worked directly with the
DOM to read text, click on buttons and fill out form fields
because this is what the user does.

These tests are black box tests. We have already talked about
black box vs. white box testing in theory. Both are valid testing
methods. As stated, this guide advises to use black box testing
first and foremost.

A common technique to enforce black box testing is to mark

internal methods as private so they cannot be called in the
test. The test should only inspect the documented, public API.
INTERNAL YET PUBLIC

In Angular Components, the difference between external and

internal properties and methods does not coincide with their
TypeScript visibility (public vs. private). Properties and
methods need to be public so that the template is able to
access them.

This makes sense for Input and Output properties. They need to
be read and written from the outside, from your test. However,
internal properties and methods exist that are public only for
the template.

For example, the CounterComponent has an Input startCount

and an Output countChange. Both are public:

@Input()

public startCount = 0;

@Output()

public countChange = new EventEmitter<number>();

They form the public API. However, there are several more
properties and methods that are public:

public count = 0;

public increment(): void { /* … */ }

public decrement(): void { /* … */ }

public reset(newCount: string): void { /* … */ }

PUBLIC FOR THE TEMPLATE

These properties and methods are internal, they are used only
within the Component. Yet they need to be public so the
template may access them. Angular compiles templates into
TypeScript code, and TypeScript ensures that the template code
only accesses public properties and methods.

In our CounterComponent black box test, we increment the

count by clicking on the “+” button. In contrast, many Angular
testing tutorials conduct Component white box tests. They call
the increment method directly:

/* Not recommended! */

describe('CounterComponent', () => {

/* … */

it('increments the count', () => {

component.increment();

fixture.detectChanged();

expectText(fixture, 'count', '1');

});

});

This white box test reaches into the Component to access an

internal, yet public method. This is sometimes valuable, but
most of the time it is misused.

INPUTS, OUTPUTS, DOM

As we have learned, a Component test is meaningful if it

interacts with the Component via Inputs, Outputs and the
rendered DOM. If the Component test calls internal methods or
accesses internal properties instead, it often misses important
template logic and event handling.

The white box spec above calls the increment method, but does
not test the corresponding template code, the increment button:

<button (click)="increment()" data-testid="increment-button">+

</button>

If we remove the increment button from the template entirely,

the feature is obviously broken. But the white box test does not
fail.

START WITH BLACK BOX TESTS

When applied to Angular Components, black box testing is more

intuitive and easier for beginners. When writing a black box test,
ask what the Component does for the user and for the parent
Component. Then imitate the usage in your test.

A white box test does not examine the Component strictly from
the DOM perspective. Thereby, it runs the risk of missing crucial
Component behavior. It gives the illusion that all code is tested.

That being said, white box testing is a viable advanced

technique. Experienced testers can write efficient white box
specs that still test out all Component features and cover all
code.
The following table shows which properties and methods of an
Angular Component you should access or not in a black box test.

RECOMMENDATION

Black box testing an Angular Component

Class member Access from test

@Input properties Yes (write)

@Output properties Yes (subscribe)

Lifecycle methods Avoid except for ngOnChanges

Other public methods Avoid

Private properties

No access
and methods
Testing Components with
children
LEARNING OBJECTIVES

Rendering a Component with or without its children

Checking that the parent and its children are wired up correctly
Replacing child Components with fakes
Using the ng-mocks library to fake dependencies

PRESENTATIONAL COMPONENTS

So far, we have tested an independent Component that renders

plain HTML elements, but no child Components. Such low-level
Components are the workhorses of an Angular application.

They directly render what the user sees and interacts with.

They are often highly generic and reusable.

They are controlled through Inputs and report back using

Outputs.

They have little to none dependencies.

They are easy to reason about and therefore easy to test.

The preferred way of testing them is a unit test.

These Components are called presentational Components
since they directly present a part of the user interface using
HTML and CSS. Presentational Components need to be
combined and wired to form a working user interface.

CONTAINER COMPONENTS

This is the duty of container Components. These high-level

Components bring multiple low-level Components together.
They pull data from different sources, like Services and state
managers, and distribute it to their children.

Container Components have several types of dependencies.

They depend on the nested child Components, but also
Injectables. These are classes, functions, objects, etc. provided
via dependency injection, like Services. These dependencies
make testing container Components complicated.

SHALLOW VS. DEEP RENDERING

There are two fundamental ways to test Components with

children:

A unit test using shallow rendering. The child Components

are not rendered.

An integration test using deep rendering. The child

Components are rendered.
Again, both are valid approaches we are going to discuss.

Shallow vs. deep rendering

In the counter example application, the HomeComponent
contains CounterComponents, ServiceCounterComponents
and NgRxCounterComponents.

From the template:

<app-counter

[startCount]="5"

(countChange)="handleCountChange($event)"

></app-counter>

<!-- … -->

<app-service-counter></app-service-counter>

<!-- … -->

<app-ngrx-counter></app-ngrx-counter>

These custom app-* elements end up in the DOM tree. They

become the host elements of the child Components.

CHECK WIRING ONLY

A unit test of HomeComponent does not render these children.

The host elements are rendered, but they remain empty. You
might wonder, what is the point of such a test? What does it do
after all?
From HomeComponent’s perspective, the inner workings of its
children are not relevant. We need to test that the template
contains the children. Also, we need to check that
HomeComponent and its children are wired up correctly using
Inputs and Outputs.

In particular, the HomeComponent unit test checks that an app-

counter element is present, that the startCount Input is
passed correctly and that HomeComponent handles the
countChange event. The same is done for the other children,
app-service-counter and app-ngrx-counter.

RENDER CHILDREN

An integration test of HomeComponent renders the child

Components. The host elements are filled with the output of
CounterComponent, ServiceCounterComponent and
NgRxCounterComponent, respectively. This integration test is
actually testing all four Components.

TEST COOPERATION

We need to decide the level of detail for testing the nested

Components. If separate unit tests for them exist, we do not
need to click on each respective increment button. After all, the
integration test needs to prove that the four Component work
together, without going into the child Component details.
🔗 HomeComponent: implementation and test code

Unit test
Let us write a unit test for HomeComponent first. The setup looks
familiar to the CounterComponent test suite. We are using
TestBed to configure a testing Module and to render the
Component under test.

describe('HomeComponent', () => {

let fixture: ComponentFixture<HomeComponent>;

let component: HomeComponent;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [HomeComponent],

}).compileComponents();

fixture = TestBed.createComponent(HomeComponent);

component = fixture.componentInstance;

fixture.detectChanges();

});

it('renders without errors', () => {

expect(component).toBeTruthy();

});

});

SMOKE TEST
This suite has one spec that acts as a smoke test. It checks the
presence of a Component instance. It does not assert anything
specific about the Component behavior yet. It merely proves that
the Component renders without errors.

If the smoke test fails, you know that something is wrong with
the testing setup.

UNKNOWN CUSTOM ELEMENTS

From Angular 9 on, the spec passes but produces a bunch of

warnings on the shell:

'app-counter' is not a known element:

1. If 'app-counter' is an Angular component, then

verify that it is part of this module.

2. If 'app-counter' is a Web Component then add

'CUSTOM_ELEMENTS_SCHEMA' to the
'@NgModule.schemas' of this component to suppress
this message.

We get the same warning regarding app-service-counter

and app-ngrx-counter. Another warning reads:

Can't bind to 'startCount' since it isn't a known

property of 'app-counter'.
What do these warnings mean? Angular does not recognize the
custom elements app-counter, app-service-counter and
app-ngrx-counter because we have not declared Components
that match these selectors. The warning points at two solutions:

1. Either declare the child Components in the testing Module.

This turns the test into an integration test.

2. Or tell Angular to ignore the unknown elements. This turns

the test into a unit test.

IGNORE CHILD ELEMENTS

Since we plan to write a unit test, we opt for the second.

When configuring the testing Module, we can specify schemas

to tell Angular how to deal with elements that are not handled by
Directives or Components.

The warning suggests CUSTOM_ELEMENTS_SCHEMA, but the

elements in question are not Web Components. We want
Angular to simply ignore the elements. Therefore we use the
NO_ERRORS_SCHEMA, “a schema that allows any property on any
element”.

await TestBed.configureTestingModule({

declarations: [HomeComponent],

schemas: [NO_ERRORS_SCHEMA],

}).compileComponents();

With this addition, our smoke test passes.

Now let us write a more meaningful spec! We start with the

nested app-counter. This is the code we need to cover:

<app-counter

[startCount]="5"

(countChange)="handleCountChange($event)"

></app-counter>

CHILD PRESENCE

First of all, we need to test the presence of app-counter, the

independent counter. We create a new spec for that purpose:

it('renders an independent counter', () => {

/* … */

});

To verify that an app-counter element exists in the DOM, we

use the familiar query method of the topmost DebugElement.

const { debugElement } = fixture;

const counter = debugElement.query(By.css('app-counter'));

This code uses the app-counter type selector to find the

element. You might wonder, why not use a test id and the
findEl helper?

FIND BY ELEMENT TYPE

In this rare occasion, we need to enforce the element app-
counter because this is CounterComponent’s selector.

Using a test id makes the element type arbitrary. This makes

tests more robust in other case. When testing the existence of
child Components though, it is the element type that invokes the
child.

Our spec still lacks an expectation. The query method returns a

DebugElement or null. We simply expect the return value to be
truthy:

it('renders an independent counter', () => {

const { debugElement } = fixture;

const counter = debugElement.query(By.css('app-counter'));

expect(counter).toBeTruthy();

});

Finding a child Component is a common task. Such repeating

patterns are good candidates for testing helpers. Not because it
is much code, but because the code has a specific meaning we
would like to convey.

debugElement.query(By.css('app-counter')) is not
particularly descriptive. The reader has to think for a moment to
realize that the code tries to find a nested Component.

FINDCOMPONENT

So let us introduce a helper function named findComponent.

export function findComponent<T>(

fixture: ComponentFixture<T>,

selector: string,

): DebugElement {

return fixture.debugElement.query(By.css(selector));

Our spec now looks like this:

it('renders an independent counter', () => {

const counter = findComponent(fixture, 'app-counter');

expect(counter).toBeTruthy();

});

CHECK INPUTS

The next feature we need to test is the startCount Input. In

particular, the property binding [startCount]="5" in
HomeComponent’s template. Let us create a new spec:

it('passes a start count', () => {

const counter = findComponent(fixture, 'app-counter');

/* … */

});

PROPERTIES

How do we read the Input value? Each DebugElement has a

properties object that contains DOM properties together with
its values. In addition, it contains certain property bindings. (The
type is { [key: string]: any }).
In a unit test with shallow rendering, properties contains the
Inputs of a child Component. First, we find app-counter to
obtain the corresponding DebugElement. Then we check the
Input value, properties.startCount.

it('passes a start count', () => {

const counter = findComponent(fixture, 'app-counter');

expect(counter.properties.startCount).toBe(5);

});

That was quite easy! Last but not least, we need to test the
Output.

OUTPUT EVENT

From HomeComponent’s perspective, reacting to the Output is

like handling an event on the app-counter element. The
template uses the familiar (event)="handler($event)"
syntax:

<app-counter

[startCount]="5"

(countChange)="handleCountChange($event)"

></app-counter>

The handleCountChange method is defined in the Component

class. It simply calls console.log to prove that the child-parent
communication worked:

export class HomeComponent {

public handleCountChange(count: number): void {

console.log('countChange event from CounterComponent', count);

Let us add a new spec for testing the Output:

it('listens for count changes', () => {

/* … */

});

The spec needs to do two things:

1. Act: Find the child Component and let the countChange

Output emit a value.

2. Assert: Check that console.log has been called.

From the parent’s viewpoint, countChange is simply an event.

Shallow rendering means there is no CounterComponent
instance and no EventEmitter named countChange. Angular
only sees an element, app-counter, with an event handler,
(countChange)="handleCountChange($event)".

SIMULATE OUTPUT

In this setup, we can simulate the Output using the known

triggerEventHandler method.

it('listens for count changes', () => {

/* … */

const counter = findComponent(fixture, 'app-counter');

const count = 5;

counter.triggerEventHandler('countChange', 5);

/* … */

});

The spec finds the app-counter element and triggers the

countChange event handler.

The second triggerEventHandler parameter, 5, is not an

event object as we know from DOM events like click. It is a
value that the Output would emit. The countChange Output has
the type EventEmitter<number>, so we use the fixed number 5
for testing purposes.

OUTPUT EFFECT

Under the hood, triggerEventHandler runs

handleCountChange($event) with $event being 5.
handleCountChange calls console.log. This is the observable
effect we need to test.

How do we verify that console.log has been called? We can

spy on existing methods with Jasmine’s spyOn.

spyOn(console, 'log');

This overwrites console.log with a spy for the duration of the

test run. We need to set up the spy in the Arrange phase, at the
beginning of our spec.
it('listens for count changes', () => {

spyOn(console, 'log');

const counter = findComponent(fixture, 'app-counter');

const count = 5;

counter.triggerEventHandler('countChange', count);

/* … */

});

In the Assert phase, we expect that the spy has been called with a
certain text and the number the Output has emitted.

it('listens for count changes', () => {

spyOn(console, 'log');

const counter = findComponent(fixture, 'app-counter');

const count = 5;

counter.triggerEventHandler('countChange', count);

expect(console.log).toHaveBeenCalledWith(

'countChange event from CounterComponent',

count,

);

});

So much for testing the CounterComponent child. The

HomeComponent also renders a ServiceCounterComponent
and an NgRxCounterComponent like this:

<app-service-counter></app-service-counter>

<!-- … -->

<app-ngrx-counter></app-ngrx-counter>

CHILD PRESENCE
Since they do not have Inputs or Outputs, we merely need to test
whether they are mentioned in the template. We add two
additional specs that check the presence of these app-
service-counter and app-ngrx-counter elements,
respectively.

it('renders a service counter', () => {

const serviceCounter = findComponent(fixture, 'app-service-

counter');

expect(serviceCounter).toBeTruthy();

});

it('renders a NgRx counter', () => {

const ngrxCounter = findComponent(fixture, 'app-ngrx-counter');

expect(ngrxCounter).toBeTruthy();

});

This is it! We have written a unit test with shallow rendering that
proves that HomeComponent correctly embeds several child
Components.

Note that this is one possible testing method. As always, it has

pros and cons. Compared with a full integration test, there is
little setup. The specs can use Angular’s DebugElement
abstraction to test presence as well as Inputs and Outputs.

UNIT TEST CONFIDENCE

However, the unit test gives little confidence that

HomeComponent works in production. We have instructed
Angular to ignore the elements app-counter, app-service-
counter and app-ngrx-counter.

What if HomeComponent uses a wrong element name and the

test copies that error? The test would pass incorrectly. We need
to render the involved Components together to spot the error.

🔗 HomeComponent: implementation and test code

🔗 Element spec helpers: full code

Faking a child Component

There is a middle ground between a naive unit test and an
integration test. Instead of working with empty custom
elements, we can render fake child Components.

A fake Component has the same selector, Inputs and Outputs,

but has no dependencies and does not have to render anything.
When testing a Component with children, we substitute the
children for fake Components.

Let us reduce the CounterComponent to an empty shell that

offers the same public API:

@Component({

selector: 'app-counter',

template: '',

})

class FakeCounterComponent implements Partial<CounterComponent> {

@Input()

public startCount = 0;

@Output()

public countChange = new EventEmitter<number>();

This fake Component lacks a template and any logic, but has the
same selector, Input and Output.

SAME PUBLIC API

Remember the rules for faking dependencies? We need to make

sure the fake resembles the original. FakeCounterComponent
implements Partial<CounterComponent> requires the class
to implement a subset of CounterComponent. TypeScript
enforces that the given properties and methods have the same
types as in the original class.

DECLARE FAKE COMPONENT

In our test suite, we place the FakeCounterComponent before

the describe block. The next step is to add the Component to
the testing Module:

TestBed.configureTestingModule({

declarations: [HomeComponent, FakeCounterComponent],

schemas: [NO_ERRORS_SCHEMA],

}).compileComponents();

When Angular encounters an app-counter element, it

instantiates and mounts a FakeCounterComponent. The
element stays empty since the fake template is empty as well.
The startCount Input property is set and the parent
HomeComponent subscribes to the countChange Output.

We need to adapt the test suite now that child Component are
rendered. Instead of searching for an app-counter element
and inspecting its properties, we explicitly search for a
FakeCounterComponent instance.

So far, we have used DebugElement’s query method to find

nested elements. For example:

const element = fixture.debugElement.query(By.css('…'));

Our helpers findEl and findComponent are using this pattern

as well.

FIND BY DIRECTIVE

Now we want to find a nested Component. We can use query

together with the By.directive predicate function:

const counterEl = fixture.debugElement.query(

By.directive(FakeCounterComponent)

);

By.directive finds all kinds of Directives. A Component is a

kind of Directive.
query returns a DebugElement or null in case no match was
found. As we have learned, a DebugElement always wraps a
native DOM element. When we query for
FakeCounterComponent, we get a DebugElement that wraps
the app-counter element – just as By.css('app-counter')
would return.

CHILD COMPONENT INSTANCE

The difference is that we can now access the rendered

FakeCounterComponent via the componentInstance property:

const counterEl = fixture.debugElement.query(

By.directive(FakeCounterComponent)

);

const counter: CounterComponent = counterEl.componentInstance;

Angular does not know the type of the Component,

componentInstance has the type any. So we add an explicit
type annotation.

CHILD PRESENCE

Having access to the child Component instance, we can make

expectations against it. First of all, we verify the presence.

it('renders an independent counter', () => {

const counterEl = fixture.debugElement.query(

By.directive(FakeCounterComponent)

);

const counter: CounterComponent = counterEl.componentInstance;

expect(counter).toBeTruthy();

});

This is a smoke test that fails early if no instance of

FakeCounterComponent was found. query would return null
and counterEl.componentInstance would fail with a
TypeError: counterEl is null.

CHECK INPUTS

The second spec checks the Input. An Input is a property of the

Component instance, so counter.startCount gives us the
value of the startCount Input.

it('passes a start count', () => {

const counterEl = fixture.debugElement.query(

By.directive(FakeCounterComponent)

);

const counter: CounterComponent = counterEl.componentInstance;

expect(counter.startCount).toBe(5);

});

The third spec checks the Output handling: If the counter emits a
value, the HomeComponent passes it to console.log.

EMIT OUTPUT

As mentioned earlier, an Output is an EventEmitter property

on the Component instance. Previously, we have simulated an
Output event using the triggerEventHandler abstraction.
Now we can access the Output directly and call its emit method,
just like the code in the child Component does.

it('listens for count changes', () => {

const counterEl = fixture.debugElement.query(

By.directive(FakeCounterComponent)

);

const counter: CounterComponent = counterEl.componentInstance;

spyOn(console, 'log');

const count = 5;

counter.countChange.emit(5);

expect(console.log).toHaveBeenCalledWith(

'countChange event from CounterComponent',

count,

);

});

We are done! Here is the HomeComponent test suite that vets the
CounterComponent child. To minimize repetition and noise, we
move the query part into the beforeEach block.

@Component({

selector: 'app-counter',

template: '',

})

class FakeCounterComponent implements Partial<CounterComponent> {

@Input()

public startCount = 0;

@Output()

public countChange = new EventEmitter<number>();

describe('HomeComponent (faking a child Component)', () => {

let fixture: ComponentFixture<HomeComponent>;

let component: HomeComponent;

let counter: FakeCounterComponent;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [HomeComponent, FakeCounterComponent],

schemas: [NO_ERRORS_SCHEMA],

}).compileComponents();

fixture = TestBed.createComponent(HomeComponent);

component = fixture.componentInstance;

fixture.detectChanges();

const counterEl = fixture.debugElement.query(

By.directive(FakeCounterComponent)

);

counter = counterEl.componentInstance;

});

it('renders an independent counter', () => {

expect(counter).toBeTruthy();

});

it('passes a start count', () => {

expect(counter.startCount).toBe(5);

});

it('listens for count changes', () => {

spyOn(console, 'log');

const count = 5;

counter.countChange.emit(count);

expect(console.log).toHaveBeenCalledWith(

'countChange event from CounterComponent',

count,

);

});

});

Let us recap what we have gained with this type of testing the
HomeComponent.

We have replaced a Component dependency with a fake that

behaves the same, as far as HomeComponent is concerned. The
fake child is rendered, but the template may be empty.

The original child Component, CounterComponent, is imported

only to create the derived fake Component. Our test remains a
fast and short unit test.

ADVANTAGES

Instead of searching for an element named app-counter, we

search for a Component instance. This is more robust. The
presence of the host element is a good indicator, but it is more
relevant that a Component has been rendered into this element.

Working with the Component instance is more intuitive than

working with the DebugElement abstraction. We can read
Component properties to learn about Inputs and Outputs. Basic
JavaScript and Angular knowledge suffices to write specs against
such an instance.

MANUAL FAKING DRAWBACKS

Our simple approach to faking a child Component has its flaws.

We have created the fake manually. This is tedious and time-
consuming, but also risky. The fake is only partly tied to the
original.

For example, if the original changes its selector app-counter,

the test should fail and remind us to adapt the template.
Instead, it passes incorrectly since we did not inherit the
Component metadata, { selector: 'app-counter', … },
but duplicated it in the test.

We are going to address these shortcomings in the next chapter.

🔗 HomeComponent spec that fakes a child Component

Faking a child Component with ng-

mocks
We have manually created a Component fake. This is an
important exercise to understand how faking Components
works, but it does not produce a robust, versatile fake. In this
guide, we cannot discuss all necessary bits and pieces of
creating airtight fake Components.

Instead, we will use a mature solution: ng-mocks is a feature-rich

library for
testing Components with fake dependencies.
(Remember, this guide uses the umbrella term “fake” while other
articles and tools use terms like “mock” or “stub”.)

CREATE FAKE FROM ORIGINAL

Among other things, ng-mocks helps creating fake Components

to substitute children. The MockComponent function expects the
original Component and returns a fake that resembles the
original.

Instead of creating a FakeCounterComponent, we call

MockComponent(CounterComponent) and add the fake to the
testing Module.

import { MockComponent } from 'ng-mocks';

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [HomeComponent, MockComponent(CounterComponent)],

schemas: [NO_ERRORS_SCHEMA],

}).compileComponents();

});

We can then query the rendered DOM for an instance of

CounterComponent. The found instance is in fact a fake created
by ng-mocks.
Still, we can declare the type CounterComponent.

describe('HomeComponent with ng-mocks', () => {

let fixture: ComponentFixture<HomeComponent>;

let component: HomeComponent;

// Original type!

let counter: CounterComponent;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [HomeComponent,
MockComponent(CounterComponent)],

schemas: [NO_ERRORS_SCHEMA],

}).compileComponents();

fixture = TestBed.createComponent(HomeComponent);

component = fixture.componentInstance;

fixture.detectChanges();

const counterEl = fixture.debugElement.query(

// Original class!

By.directive(CounterComponent)

);

counter = counterEl.componentInstance;

});

/* … */

});

From a TypeScript viewpoint, the fake conforms to the

CounterComponent type. TypeScript uses a structural type
system that checks if all type requirements are met.
TYPE EQUIVALENCE

Every proposition that holds true for a CounterComponent

holds true for the fake as well. The fake has all properties and
methods that the original has. That is why we can safely replace
the original with the fake and treat the fake the same in our test.

The full code:

describe('HomeComponent with ng-mocks', () => {

let fixture: ComponentFixture<HomeComponent>;

let component: HomeComponent;

let counter: CounterComponent;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [HomeComponent, Mock(CounterComponent)],

schemas: [NO_ERRORS_SCHEMA],

}).compileComponents();

fixture = TestBed.createComponent(HomeComponent);

component = fixture.componentInstance;

fixture.detectChanges();

const counterEl = fixture.debugElement.query(

By.directive(CounterComponent)

);

counter = counterEl.componentInstance;

});

it('renders an independent counter', () => {

expect(counter).toBeTruthy();

});

it('passes a start count', () => {

expect(counter.startCount).toBe(5);

});

it('listens for count changes', () => {

spyOn(console, 'log');

const count = 5;

counter.countChange.emit(count);

expect(console.log).toHaveBeenCalledWith(

'countChange event from CounterComponent',

count,

);

});

});

We have eliminated the manual FakeCounterComponent. We

are using MockComponent(CounterComponent) to create the
fake and the original class CounterComponent. The specs itself
did not change.

This was only a glimpse of ng-mocks. The library not only helps
with nested Components, but provides high-level helpers for
setting up the Angular test environment. ng-mocks replaces the
conventional setup with TestBed.configureTestingModule
and helps faking Modules, Components, Directives, Pipes and
Services.

🔗 HomeComponent spec with ng-mocks

🔗 ng-mocks
Testing Components depending
on Services
LEARNING OBJECTIVES

Choosing between a unit or an integration test for Components that talk to

Services
Creating fake Services to test the Component in isolation
Verifying that the Component correctly interacts with the Service
Understanding different approaches for faking a Service dependency

We have successfully tested the independent

CounterComponent as well as the container HomeComponent.
The next Component on our list is the
ServiceCounterComponent.

As the name suggests, this Component depends on the

CounterService. The counter state is not stored in the
Component itself, but in the central Service.

SHARED CENTRAL STATE

Angular’s dependency injection maintains only one app-wide

instance of the Service, a so-called singleton. Therefore, multiple
instances of ServiceCounterComponent share the same
counter state. If the user increments the count with one
instance, the count also changes in the other instance.
Again, there are two fundamental ways to test the Component:

A unit test that replaces the CounterService dependency

with a fake.

An integration test that includes a real CounterService.

This guide will demonstrate both. For your Components, you

need to make a decision on an individual basis. These questions
may guide you: Which type of test is more beneficial, more
meaningful? Which test is easier to set up and maintain in the
long run?

Service dependency integration test

For the ServiceCounterComponent, the integration test is
much easier to set up than the unit test. The trivial
CounterService has little logic and no further dependencies. It
does not have side effects we need to suppress in the testing
environment, like HTTP requests. It only changes its internal
state.

The integration test looks almost identical to the

CounterComponent test we have already written.

describe('ServiceCounterComponent: integration test', () => {

let component: ServiceCounterComponent;

let fixture: ComponentFixture<ServiceCounterComponent>;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [ServiceCounterComponent],

providers: [CounterService],

}).compileComponents();

fixture = TestBed.createComponent(ServiceCounterComponent);

component = fixture.componentInstance;

fixture.detectChanges();

});

it('shows the start count', () => {

expectText(fixture, 'count', '0');

});

it('increments the count', () => {

click(fixture, 'increment-button');

fixture.detectChanges();

expectText(fixture, 'count', '1');

});

it('decrements the count', () => {

click(fixture, 'decrement-button');

fixture.detectChanges();

expectText(fixture, 'count', '-1');

});

it('resets the count', () => {

const newCount = 456;

setFieldValue(fixture, 'reset-input', String(newCount));

click(fixture, 'reset-button');

fixture.detectChanges();

expectText(fixture, 'count', String(newCount));

});

});

Compared to the CounterComponent test, there is nothing new

here except for one line:

providers: [CounterService],

PROVIDE SERVICE

This line adds the CounterService to the testing Module.

Angular creates an instance of the Service and injects it into the
Component under test. The test is shorter because the
ServiceCounterComponent does not have Inputs or Outputs
to test.

As the CounterService always starts with the count 0, the test

needs to take that for granted. Neither the Component nor the
Service allow a different start count.

INTERACTION WITH SERVICE

The integration test does not examine the Component’s inner

workings. It only provides the Service but does not check how
the Component and the Service interact. The Component might
not talk to the Service at all.

If we want an integration test to verify that the Component

stores the count in the Service, we would need a test with two
ServiceCounterComponents: When increasing the count using
one Component, the displayed count in the other should change
accordingly.

🔗 ServiceCounterComponent: integration test

Faking Service dependencies

Let us move on to the unit test for the
ServiceCounterComponent. To tackle this challenge, we need
to learn the art of faking Service dependencies.

There are several practical approaches with pros and cons. We

have discussed two main requirements on fake dependencies:

1. Equivalence of fake and original: The fake must have a type

derived from the original.

2. Effective faking: the original stays untouched.

RECOMMENDED FAKING APPROACH

This guide will present one solution that implements these

requirements. Note that other solutions might meet these
requirements as well.

The dependency we need to fake, CounterService, is a simple

class annotated with @Injectable(). This is the outer shape of
CounterService:

class CounterService {

public getCount(): Observable<number> { /* … */ }

public increment(): void { /* … */ }

public decrement(): void { /* … */ }

public reset(newCount: number): void { /* … */ }

private notify(): void { /* … */ }

We need to build a fake that meets the mentioned needs.

FAKE INSTANCE

The simplest way to create a fake is an object literal {…} with

methods:

const currentCount = 123;

const fakeCounterService = {

getCount() {

return of(currentCount);

},

increment() {},

decrement() {},

reset() {},

};

getCount returns a fixed value from a constant named

currentCount. We will use the constant later to check whether
the Component uses the value correctly.
This fake is far from perfect, but already a viable replacement for
a CounterService instance. It walks like the original and talks
like the original. The methods are empty or return fixed data.

TYPE EQUIVALENCE

The fake implementation above happens to have the same

shape as the original. As discussed, it is of utter importance that
the fake remains up to date with the original.

The equivalence is not yet enforced by TypeScript. We want

TypeScript to check whether the fake properly replicates the
original. The first attempt would be to add a type declaration:

ERRONEOUS CODE

// Error!

const fakeCounterService: CounterService = {

getCount() {

return of(currentCount);

},

increment() {},

decrement() {},

reset() {},

};

Unfortunately, this does not work. TypeScript complains that

private methods and properties are missing:

Type '{ getCount(): Observable<number>;

increment(): void; decrement(): void; reset():
void; }' is missing the following properties from
type 'CounterService': count, subject, notify

That is correct. But we cannot add private members to an object

literal, nor should we.

PICK PUBLIC MEMBERS

Luckily, we can use a TypeScript trick to fix this problem. Using

Pick and keyof, we create a derived type that only contains the
public members:

const fakeCounterService:

Pick<CounterService, keyof CounterService> = {

getCount() {

return of(currentCount);

},

increment() {},

decrement() {},

reset() {},

};

KEEP FAKE IN SYNC

When the CounterService changes its public API, the

dependent ServiceCounterComponent needs to be adapted.
Likewise, the fakeCounterService needs to reflect the change.
The type declaration reminds you to update the fake. It prevents
the fake to get out of sync with the original.

FAKE WHAT IS NECESSARY

ServiceCounterComponent calls all existing public
CounterService methods, so we have added them to the fake.

If the code under test does not use the full API, the fake does not
need to replicate the full API either. Only declare those methods
and properties the code under test actually uses.

For example, if the code under test only calls getCount, just
provide this method. Make sure to add a type declaration that
picks the method from the original type:

const fakeCounterService: Pick<CounterService, 'getCount'> = {

getCount() {

return of(currentCount);

},

};

Pick and other mapped types help to bind the fake to the
original type in a way that TypeScript can check the equivalence.

SPY ON METHODS

A plain object with methods is an easy way to create a fake

instance. The spec needs to verify that the methods have been
called with the right parameters.

Jasmine spies are suitable for this job. A first approach fills the
fake with standalone spies:
const fakeCounterService:

Pick<CounterService, keyof CounterService> = {

getCount:

jasmine.createSpy('getCount').and.returnValue(of(currentCount)),

increment: jasmine.createSpy('increment'),

decrement: jasmine.createSpy('decrement'),

reset: jasmine.createSpy('reset'),

};

CREATESPYOBJ

This is fine, but overly verbose. Jasmine provides a handy helper

function for creating an object with multiple spy methods,
createSpyObj. It expects a descriptive name and an object with
method names and return values:

const fakeCounterService = jasmine.createSpyObj<CounterService>(

'CounterService',

getCount: of(currentCount),

increment: undefined,

decrement: undefined,

reset: undefined,

);

The code above creates an object with four methods, all of them
being spies. They return the given values: getCount returns an
Observable<number>. The other methods return undefined.

TYPE EQUIVALENCE
createSpyObj accepts a TypeScript type variable to declare the
type of the created object. We pass CounterService between
angle brackets so TypeScript checks that the fake matches the
original.

Let us put our fake to work. In the Arrange phase, the fake is
created and injected into the testing Module.

describe('ServiceCounterComponent: unit test', () => {

const currentCount = 123;

let component: ServiceCounterComponent;

let fixture: ComponentFixture<ServiceCounterComponent>;

// Declare shared variable

let fakeCounterService: CounterService;

beforeEach(async () => {

// Create fake

fakeCounterService = jasmine.createSpyObj<CounterService>(

'CounterService',

getCount: of(currentCount),

increment: undefined,

decrement: undefined,

reset: undefined,

);

await TestBed.configureTestingModule({

declarations: [ServiceCounterComponent],

// Use fake instead of original

providers: [

{ provide: CounterService, useValue: fakeCounterService }

],

}).compileComponents();

fixture = TestBed.createComponent(ServiceCounterComponent);

component = fixture.componentInstance;

fixture.detectChanges();

});

/* … */

});

There is a new pattern in the providers sections of the testing

Module:

providers: [

{ provide: CounterService, useValue: fakeCounterService }

PROVIDE FAKE INSTEAD

This is the crucial moment where we tell Angular: For the

CounterService dependency, use the value
fakeCounterService instead. This is how we replace the
original with a fake.

Normally, Angular instantiates and injects a CounterService

instance whenever a Component, Service, etc. asks for the
CounterService. By using { provide: …, useValue: … },
we skip the instantiation and directly provide the value to inject.

The Arrange phase is complete now, let us write the actual specs.
The Act phase is the same as in the other counter Component
tests: We click on buttons and fill out form fields.

VERIFY SPIES

In the Assert phase, we need to verify that the Service methods

have been called. Thanks to jasmine.createSpyObj, all
methods of fakeCounterService are spies. We use expect
together with an appropriate matcher like toHaveBeenCalled,
toHaveBeenCalledWith, etc.

expect(fakeCounterService.getCount).toHaveBeenCalled();

Applied to all specs, the test suite looks like this:

describe('ServiceCounterComponent: unit test', () => {

const currentCount = 123;

let component: ServiceCounterComponent;

let fixture: ComponentFixture<ServiceCounterComponent>;

// Declare shared variable

let fakeCounterService: CounterService;

beforeEach(async () => {

// Create fake

fakeCounterService = jasmine.createSpyObj<CounterService>(

'CounterService',

getCount: of(currentCount),

increment: undefined,

decrement: undefined,

reset: undefined,

);

await TestBed.configureTestingModule({

declarations: [ServiceCounterComponent],

// Use fake instead of original

providers: [

{ provide: CounterService, useValue: fakeCounterService }

],

}).compileComponents();

fixture = TestBed.createComponent(ServiceCounterComponent);

component = fixture.componentInstance;

fixture.detectChanges();

});

it('shows the count', () => {

expectText(fixture, 'count', String(currentCount));

expect(fakeCounterService.getCount).toHaveBeenCalled();

});

it('increments the count', () => {

click(fixture, 'increment-button');

expect(fakeCounterService.increment).toHaveBeenCalled();

});

it('decrements the count', () => {

click(fixture, 'decrement-button');

expect(fakeCounterService.decrement).toHaveBeenCalled();

});

it('resets the count', () => {

const newCount = 456;

setFieldValue(fixture, 'reset-input', String(newCount));

click(fixture, 'reset-button');

expect(fakeCounterService.reset).toHaveBeenCalledWith(newCount);

});

});

🔗 ServiceCounterComponent: implementation and test code

🔗 Angular guide: Dependency providers

Fake Service with minimal logic

The specs above check whether user interaction calls the Service
methods. They do not check whether the Component re-renders
the new count after having called the Service.

ServiceCounter’s getCount method returns an

Observable<number> and pushes a new value through the
Observable whenever the count changes. The spec it('shows
the count', …) has proven that the Component obtained the
count from the Service and renders it.

In addition, we will check that the Component updates when

new values are pushed. This is not strictly necessary in our
simple ServiceCounterComponent and CounterService
example. But it is important in more complex interactions
between a Component and a Service.

COMPONENT UPDATE
The fake getCount method returns of(currentCount), an
Observable with the fixed value 123. The Observable completes
immediately and never pushes another value. We need to
change that behavior in order to demonstrate the Component
update.

The fake CounterService, devoid of logic so far, needs to gain

some logic. getCount needs to return an Observable that emits
new values when increment, decrement and reset are called.

BEHAVIORSUBJECT

Instead of a fixed Observable, we use a BehaviorSubject, just

like in the original CounterService implementation. The
BehaviorSubject has a next method for pushing new values.

We declare a variable fakeCount$ in the scope of the test suite

and assign a BehaviorSubject in the first beforeEach block:

describe('ServiceCounterComponent: unit test with minimal Service

logic', () => {

/* … */

let fakeCount$: BehaviorSubject<number>;

beforeEach(async () => {

fakeCount$ = new BehaviorSubject(0);

/* … */

});

/* … */

});

Then we change the fakeCounterService so the methods

push new values through fakeCount$.

const newCount = 123;

/* … */

fakeCounterService = {

getCount(): Observable<number> {

return fakeCount$;

},

increment(): void {

fakeCount$.next(1);

},

decrement(): void {

fakeCount$.next(-1);

},

reset(): void {

fakeCount$.next(Number(newCount));

},

};

The fake above is an object with plain methods. We are not using
createSpyObj any longer because it does not allow fake
method implementations.

SPY ON METHODS

We have lost the Jasmine spies and need to bring them back.
There are several ways to wrap the methods in spies. For
simplicity, we install spies on all methods using spyOn:

spyOn(fakeCounterService, 'getCount').and.callThrough();

spyOn(fakeCounterService, 'increment').and.callThrough();

spyOn(fakeCounterService, 'decrement').and.callThrough();

spyOn(fakeCounterService, 'reset').and.callThrough();

Remember to add .and.callThrough() so the underlying fake

methods are called.

Now our fake Service sends new counts to the Component. We

can reintroduce the checks for the Component output:

fixture.detectChanges();

expectText(fixture, 'count', '…');

Assembling all parts, the full ServiceCounterComponent unit

test:

describe('ServiceCounterComponent: unit test with minimal Service

logic', () => {

const newCount = 456;

let component: ServiceCounterComponent;

let fixture: ComponentFixture<ServiceCounterComponent>;

let fakeCount$: BehaviorSubject<number>;

let fakeCounterService: Pick<CounterService, keyof

CounterService>;

beforeEach(async () => {

fakeCount$ = new BehaviorSubject(0);

fakeCounterService = {

getCount(): Observable<number> {

return fakeCount$;

},

increment(): void {

fakeCount$.next(1);

},

decrement(): void {

fakeCount$.next(-1);

},

reset(): void {

fakeCount$.next(Number(newCount));

},

};

spyOn(fakeCounterService, 'getCount').and.callThrough();

spyOn(fakeCounterService, 'increment').and.callThrough();

spyOn(fakeCounterService, 'decrement').and.callThrough();

spyOn(fakeCounterService, 'reset').and.callThrough();

await TestBed.configureTestingModule({

declarations: [ServiceCounterComponent],

providers: [

{ provide: CounterService, useValue: fakeCounterService }

],

}).compileComponents();

fixture = TestBed.createComponent(ServiceCounterComponent);

component = fixture.componentInstance;

fixture.detectChanges();

});

it('shows the start count', () => {

expectText(fixture, 'count', '0');

expect(fakeCounterService.getCount).toHaveBeenCalled();

});

it('increments the count', () => {

click(fixture, 'increment-button');

fakeCount$.next(1);

fixture.detectChanges();

expectText(fixture, 'count', '1');

expect(fakeCounterService.increment).toHaveBeenCalled();

});

it('decrements the count', () => {

click(fixture, 'decrement-button');

fakeCount$.next(-1);

fixture.detectChanges();

expectText(fixture, 'count', '-1');

expect(fakeCounterService.decrement).toHaveBeenCalled();

});

it('resets the count', () => {

setFieldValue(fixture, 'reset-input', newCount);

click(fixture, 'reset-button');

fixture.detectChanges();

expectText(fixture, 'count', newCount);

expect(fakeCounterService.reset).toHaveBeenCalledWith(newCount);

});

});

Again, this example is intentionally verbose. The fake re-

implements a large part of the original logic. This is because the
original CounterService has little logic itself.

In reality, Services are more complex and Components process

the data they receive from the Services. Then, the effort of faking
essential logic is worthwhile.

🔗 ServiceCounterComponent: unit test

Faking Services: Summary

Creating fake Service dependencies and verifying their usage is
one of the most challenging problems when testing Angular
applications. This guide can only catch a glimpse on the subject.

TESTABLE SERVICES

Faking Services requires effort and steady practice. The more

unit tests you write, the more experience you gain. More
importantly, the practice teaches you to write simple Services that
are easy to fake: Services with a clear API and an obvious
purpose.

Unfortunately, there are no best practices when it comes to

faking Services. You will find plenty of approaches online that
have their strengths and weaknesses. The associated unit tests
have different degrees of accuracy and completeness.

Arguing about the “right” way of faking a Service is pointless. You

need to decide on a faking method that suits the Service on a
case-by-case basis.
GUIDELINES

There are two guidelines that may help you:

1. Is the test valuable? Does it cover the important interaction

between Component and Service? Decide whether to test the
interaction superficially or in-depth.

2. Whichever approach you choose, make sure to meet the

basic requirements:

1. Equivalence of fake and original: The fake must have a

type derived from the original.

2. Effective faking: the original stays untouched.

Testing complex forms
LEARNING OBJECTIVES

Filling out and submitting forms in a Component test

Testing synchronous and asynchronous field validation and error messages
Testing dynamic form logic
Using tools to ensure that forms are accessible to everyone

Forms are the powerhouses of large web applications. Especially

enterprise applications revolve around entering and editing data
via forms. Therefore, implementing complex forms is a vital
feature of the Angular framework.

We have already learned how to fill out form fields when testing
the counter Component. In doing so, we developed the
setFieldValue testing helper.

The simple forms we have dealt with served the purpose of

entering one value. We have tested them by filling out the field
and submitting the form. Now we will look at a more complex
example.

SIGN-UP FORM

We are introducing and testing a sign-up form for a fictional

online service.

🔗 Sign-up form: Source code

🔗 Sign-up form: Run the app
The sign-up form features are:

Different types of input fields: text, radio buttons,

checkboxes, select boxes

Field validation with synchronous and asynchronous

validators

Accessible form structure, field labels and error messages

Dynamic relations between fields

The form consists of four sections:

1. The plan selection: “Personal”, “Business” or “Education &

Non-profit”

2. The login credentials: username, email and password

3. The billing address

4. Terms of Services and submit button

IMPRACTICAL

Please note that this form is for demonstration purposes only.

While it follows best practices regarding validation and
accessibility, it is not practical from a design and user experience
perspective. Among other things, it is way too complex to get
new users onboard.
CLIENT & SERVER

In contrast to the other example repositories, this one is split

into a client and a server directory:

The client directory contains a standard Angular app

created with Angular CLI.

The server directory contains a simple Node.js service that

simulates the user management and account creation.

Again, the Node.js service is for demonstration purposes only.

The service holds the created user accounts in memory and
discards them when stopped. Please do not use it in production.

With 12 form controls, the sign-up form is not particularly large.

But there are subtle details we are going to explore.

Sign-up form Component

The form logic lies in the SignupFormComponent. The
Component depends on the SignupService for communicating
with the back-end service.

You might remember that there are two fundamental

approaches to forms in Angular: Template-driven Forms and
Reactive Forms.
While both approaches look quite different in practice, they are
based on the same underlying concepts: Form groups
(FormGroup objects) and form controls (FormControl objects).

REACTIVE FORM

The SignupFormComponent is a Reactive Form that explictly

creates the groups and controls in the Component class. This
way, it is easier to specify custom validators and to set up
dynamic field relations.

As with other Angular core concepts, this guide assumes you

have a basic understanding of Reactive Forms. Please refer to
the official guide on Reactive Forms to brush up your knowledge.

The important bits of the SignupFormComponent class are:

@Component({

selector: 'app-signup-form',

templateUrl: './signup-form.component.html',

styleUrls: ['./signup-form.component.scss'],

})

export class SignupFormComponent {

/* … */

public form = this.formBuilder.group({

plan: ['personal', required],

username: [

null,

[required, pattern('[a-zA-Z0-9.]+'), maxLength(50)],

(control: AbstractControl) =>

this.validateUsername(control.value),

],

email: [

null,

[required, email, maxLength(100)],

(control: AbstractControl) =>

this.validateEmail(control.value),

],

password: [

null,

required,

() => this.validatePassword()

],

tos: [null, requiredTrue],

address: this.formBuilder.group({

name: [null, required],

addressLine1: [null],

addressLine2: [null, required],

city: [null, required],

postcode: [null, required],

region: [null],

country: [null, required],

}),

});

/* … */

constructor(

private signupService: SignupService,

private formBuilder: FormBuilder) {

/* … */

/* … */

FORM GROUPS AND CONTROLS

Using Angular’s FormBuilder, we create the form property, the
topmost form group. Inside, there is another form group for the
address-related fields.

The form controls are declared with their initial values and their
validators. For example, the password control:

password: [

// The initial value (null means empty)

null,

// The synchronous validator

required,

// The asynchronous validator

() => this.validatePassword()

],

The SignupFormComponent template uses the formGroup,

formGroupName and formControlName directives to associate
elements with a form group or control, respectively.

The stripped-down form structure with only one control looks

like this:

<form [formGroup]="form">

<fieldset formGroupName="address">

<label>

Full name

<input type="text" formControlName="name" />

</label>

</fieldset>

</form>

FORM SUBMISSION

When the form is filled out correctly and all validations pass, the
user is able to submit to the form. It produces an object
described by the SignupData interface:

export interface SignupData {

plan: Plan;

username: string;

email: string;

password: string;

tos: true;

address: {

name: string;

addressLine1?: string;

addressLine2: string;

city: string;

postcode: string;

region?: string;

country: string;

};

Plan is a union of strings:

export type Plan = 'personal' | 'business' | 'non-profit';

The SignupService’s signup method takes the SignupData

and sends it to the server. For security reasons, the server
validates the data again. But we will focus on the front-end in
this guide.

🔗 SignupFormComponent: full code

🔗 Angular documentation: Reactive forms

Form validation and errors

SYNC VALIDATORS

Several form controls have synchronous validators. required,

email, maxLength, pattern etc. are built-in, synchronous
validators provided by Angular:

import { Validators } from '@angular/forms';

const {

email, maxLength, pattern, required, requiredTrue

} = Validators;

These validators take the control value, a string most of the time,
and return a ValidationErrors object with potential error
messages. The validation happens synchronously on the client.

ASYNC VALIDATORS

For the username, the email and the password, there are custom
asynchronous validators. They check whether the username and
email are available and whether the password is strong enough.

The asynchronous validators use the SignupService to talk to

the back-end service. These HTTP requests turn the validation
asynchronous.
ERROR RENDERING

When a validator returns any errors, corresponding messages

are shown below the form control. This repetitive task is
outsourced to another Component.

INVALID && (TOUCHED || DIRTY)

The ControlErrorsComponent displays the errors when the

form control is invalid and either touched or dirty.

Touched means the user has focussed the control but it has
lost the focus again (the blur event fired).

Dirty means the user has changed the value.

For example, for the name control, the interaction between the
input element and the ControlErrorsComponent looks like
this:

<label>

Full name

<input

type="text"

formControlName="name"

aria-required="true"

appErrorMessage="name-errors"

/>

</label>

<!-- … -->

<app-control-errors controlName="name" id="name-errors">

<ng-template let-errors>

<ng-container *ngIf="errors.required">

Name must be given.

</ng-container>

</ng-template>

</app-control-errors>

ARIA ATTRIBUTES

The appErrorMessage attribute activates the

ErrorMessageDirective. When the form control is invalid and
either touched or dirty, the Directive adds aria-invalid and
aria-errormessage attributes.

aria-invalid marks the control as invalid for assistive

technologies like screen readers. aria-errormessage points to
another element that contains the error messages.

CONNECT CONTROL WITH ERRORS

In case of an error, the Directive sets aria-errormessage to

the id of the corresponding app-control-errors element. In
the example above, the id is name-errors. This way, a screen
reader user finds the associated error messages quickly.

The control-specific error messages are still located in signup-

form.component.html. They are passed to
ControlErrorsComponent as an ng-template. The
ControlErrorsComponent renders the template dynamically,
passing the errors object as a variable:
<ng-template let-errors>

<ng-container *ngIf="errors.required">

Name must be given.

</ng-container>

</ng-template>

You do not have to understand the details of this particular

implementation. The solution in the sign-up form is just one
possibility to display errors, avoid repetition and set ARIA
attributes for accessibility.

From the user perspective and also from a testing perspective, it

does not matter how you implement the rendering of error
messages – as long as they are present and accessible.

IMPLEMENTATION DETAILS

We are going to test the SignupFormComponent in conjunction

with ControlErrorsComponent and ErrorMessageDirective
in a black-box integration test. For this test, the latter two will
be irrelevant implementation details.

🔗 Angular guide: Validating form input

🔗 MDN: Introduction to ARIA
🔗 MDN: aria-invalid
🔗 ARIA specification: aria-errormessage
🔗 ErrorMessageDirective: full code
🔗 ControlErrorsComponent: full code
Test plan
What are the important parts of the sign-up form that need to be
tested?

1. Form submission

Successful submission

Do not submit the invalid form

Submission failure

2. Required fields are marked as such and display error

messages

3. Asynchronous validation of username, email and password

4. Dynamic field relations

5. Password type toggle

6. Accessibility of the form structure, field labels and error

messages

Test setup
Before writing the individual specs, we need to set up the suite
in signup-form.component.spec.ts. Let us start with the
testing Module configuration.

await TestBed.configureTestingModule({

imports: [ReactiveFormsModule],

declarations: [

SignupFormComponent,

ControlErrorsComponent,

ErrorMessageDirective

],

providers: [

{ provide: SignupService, useValue: signupService }

],

}).compileComponents();

The Component under test contains a Reactive Form. That is why

we import the ReactiveFormsModule:

imports: [ReactiveFormsModule],

DEEP RENDERING

As described, we are writing an integration test, so we declare

the Component and its child components:

declarations: [

SignupFormComponent,

ControlErrorsComponent,

ErrorMessageDirective

],

FAKE SERVICE
The SignupFormComponent depends on the SignupService.
We do not want HTTP requests to the back-end when the tests
run, so we replace the Service with a fake instance.

providers: [

{ provide: SignupService, useValue: signupService }

],

A possible SignupService fake looks like this:

const signupService:

Pick<SignupService, keyof SignupService> = {

isUsernameTaken() {

return of(false);

},

isEmailTaken() {

return of(false);

},

getPasswordStrength() {

return of(strongPassword);

},

signup() {

return of({ success: true });

},

};

This fake implements the success case: the username and email
are available, the password is strong enough and the form
submission was successful.

Since we are going to test several error cases as well, we need to

create SignupService fakes dynamically. Also we need Jasmine
spies to verify that the Service methods are called correctly.

CREATESPYOBJ

This is a job for Jasmine’s createSpyObj (see Faking Service

dependencies).

const signupService = jasmine.createSpyObj<SignupService>(

'SignupService',

// Successful responses per default

isUsernameTaken: of(false),

isEmailTaken: of(false),

getPasswordStrength: of(strongPassword),

signup: of({ success: true }),

);

SETUP FUNCTION

Together with the testing Module configuration, we put this code

into a setup function. To adjust the SignupService fake
behavior, we allow passing method return values.

describe('SignupFormComponent', () => {

let fixture: ComponentFixture<SignupFormComponent>;

let signupService: jasmine.SpyObj<SignupService>;

const setup = async (

signupServiceReturnValues?:

jasmine.SpyObjMethodNames<SignupService>,

) => {

signupService = jasmine.createSpyObj<SignupService>(

'SignupService',

// Successful responses per default

isUsernameTaken: of(false),

isEmailTaken: of(false),

getPasswordStrength: of(strongPassword),

signup: of({ success: true }),

// Overwrite with given return values

...signupServiceReturnValues,

);

await TestBed.configureTestingModule({

imports: [ReactiveFormsModule],

declarations: [

SignupFormComponent,

ControlErrorsComponent,

ErrorMessageDirective

],

providers: [

{ provide: SignupService, useValue: signupService }

],

}).compileComponents();

fixture = TestBed.createComponent(SignupFormComponent);

fixture.detectChanges();

};

/* … */

});

In all following specs, we are going to call setup first. If we

simply write async setup(), the SignupService fake returns
successful responses.

We can pass an object with different return values to simulate

failure. For example, when testing that the username is taken:

await setup({

// Let the API return that the username is taken

isUsernameTaken: of(true),

});

Such a setup function is just one way to create fakes and avoid
repetition. You might come up with a different solution that
serves the same purpose.

🔗 SignupFormComponent: test code

Successful form submission

The first case we need to test is the successful form submission.
If the user fills out all required fields and the validations pass, we
expect the Component to call SignupService’s signup method
with the entered form data.

TEST DATA

The first step is to define valid test data we can fill into the form.
We put this in a separate file, signup-data.spec-helper.ts:
export const username = 'quickBrownFox';

export const password = 'dog lazy the over jumps fox brown quick
the';

export const email = '[email protected]';

export const name = 'Mr. Fox';

export const addressLine1 = '';

export const addressLine2 = 'Under the Tree 1';

export const city = 'Farmtown';

export const postcode = '123456';

export const region = 'Upper South';

export const country = 'Luggnagg';

export const signupData: SignupData = {

plan: 'personal',

username,

email,

password,

address: {

name, addressLine1, addressLine2,

city, postcode, region, country

},

tos: true,

};

In the signup-form.component.html template, all field elements

need to be marked with test ids so we can find them and enter
the values programmatically.

For example, the username input gets the test id username, the
email input gets email and so on.
Back in signup-form.component.spec.ts, we create a new
spec that calls the setup function.

it('submits the form successfully', async () => {

await setup();

/* … */

});

FILL OUT FORM

Next, we fill out all required fields with valid values. Since we
need to do that in several upcoming specs, let us create a
reusable function.

const fillForm = () => {

setFieldValue(fixture, 'username', username);

setFieldValue(fixture, 'email', email);

setFieldValue(fixture, 'password', password);

setFieldValue(fixture, 'name', name);

setFieldValue(fixture, 'addressLine1', addressLine1);

setFieldValue(fixture, 'addressLine2', addressLine2);

setFieldValue(fixture, 'city', city);

setFieldValue(fixture, 'postcode', postcode);

setFieldValue(fixture, 'region', region);

setFieldValue(fixture, 'country', country);

checkField(fixture, 'tos', true);

};

The fillForm function lies in the scope of describe so it may

access the fixture variable. It uses the setFieldValue and
checkField element testing helpers.
In the spec, we call fillForm:

it('submits the form successfully', async () => {

await setup();

fillForm();

/* … */

});

Let us try to submit the form immediately after. The form under
test listens for an ngSubmit event at the form element. This
boils down to a native submit event.

SUBMIT FORM

We find the form element by its test id and simulate a submit

event (see Triggering event handlers).

Then we expect the signup spy to have been called with the
entered data.

it('submits the form successfully', async () => {

await setup();

fillForm();

findEl(fixture, 'form').triggerEventHandler('submit', {});

expect(signupService.signup).toHaveBeenCalledWith(signupData);

});

If we run this spec, we find that is fails:

Expected spy SignupService.signup to have been called with:

[ Object({ plan: 'personal', … }) ]

but it was never called.

The spec fails because the form is still in the invalid state even
though we have filled out all fields correctly.

ASYNC VALIDATORS

The cause are the asynchronous validators for username,

email and password. When the user stops typing into these
fields, they wait for one second before sending a request to the
server.

In production, the HTTP request takes additional time, but our

fake SignupService returns the response instantly.

ONE SECOND DEBOUNCE

This technique to reduce the amount of requests is called

debouncing. For example, typing the username “fox” should send
one request with “fox”, not three subsequent requests with “f”,
“fo”, “fox”.

The spec above submits the form immediately after filling out
the fields. At this point in time, the asynchronous validators have
been called but have not returned a value yet. They are still
waiting for the debounce period to pass.
In consequence, the test needs to wait one second for the
asynchronous validators. An easy way would be to write an
asynchronous test that uses setTimeout(() => { /* … */},
1000). But this would slow down our specs.

FAKEASYNC AND TICK

Instead, we are going to use Angular’s fakeAsync and tick

functions to simulate the passage of time. They are a powerful
couple to test asynchronous behavior.

fakeAsync freezes time. It hooks into the processing of

asynchronous tasks created by timers, intervals, Promises and
Observables. It prevents these tasks from being executed.

SIMULATE PASSAGE OF TIME

Inside the time warp created by fakeAsync, we use the tick

function to simulate the passage of time. The scheduled tasks
are executed and we can test their effect.

The specialty of fakeAsync and tick is that the passage of time

is only virtual. Even if one second passes in the simulation, the
spec still completes in a few milliseconds.

fakeAsync wraps the spec function which is also an async

function due to the setup call. After filling out the form, we
simulate the waiting with tick(1000).
it('submits the form successfully', fakeAsync(async () => {

await setup();

fillForm();

// Wait for async validators

tick(1000);

findEl(fixture, 'form').triggerEventHandler('submit', {});

expect(signupService.signup).toHaveBeenCalledWith(signupData);

}));

This spec passes! Now we should add some expectations to test

the details.

First, we expect the asynchronous validators to call the

SignupService methods with the user input. The methods are
isUsernameTaken, isEmailTaken and
getPasswordStrength.

it('submits the form successfully', fakeAsync(async () => {

await setup();

fillForm();

// Wait for async validators

tick(1000);

findEl(fixture, 'form').triggerEventHandler('submit', {});

expect(signupService.isUsernameTaken).toHaveBeenCalledWith(username
);

expect(signupService.isEmailTaken).toHaveBeenCalledWith(email);

expect(signupService.getPasswordStrength).toHaveBeenCalledWith(pass
word);

expect(signupService.signup).toHaveBeenCalledWith(signupData);

}));

SUBMIT BUTTON

Next, we make sure that the submit button is disabled initially.

After successful validation, the button is enabled. (The submit
button carries the test id submit.)

STATUS MESSAGE

Also, when the form has been submitted successfully, the status
message “Sign-up successful!” needs to appear. (The status
message carries the test id status.)

This brings us to the final spec:

it('submits the form successfully', fakeAsync(async () => {

await setup();

fillForm();

fixture.detectChanges();

expect(findEl(fixture, 'submit').properties.disabled).toBe(true);

// Wait for async validators

tick(1000);

fixture.detectChanges();

expect(findEl(fixture,
'submit').properties.disabled).toBe(false);

findEl(fixture, 'form').triggerEventHandler('submit', {});

fixture.detectChanges();

expectText(fixture, 'status', 'Sign-up successful!');

expect(signupService.isUsernameTaken).toHaveBeenCalledWith(username
);

expect(signupService.isEmailTaken).toHaveBeenCalledWith(email);

expect(signupService.getPasswordStrength).toHaveBeenCalledWith(pass
word);

expect(signupService.signup).toHaveBeenCalledWith(signupData);

}));

Because we are testing DOM changes, we have to call

detectChanges after each Act phase.

🔗 SignupFormComponent: test code

🔗 Angular API reference: fakeAsync
🔗 Angular API reference: tick

Invalid form
Now that we have tested the successful form submission, let us
check the handling of an invalid form. What happens if we do
not fill out any fields, but submit the form?

We create a new spec for this case:

it('does not submit an invalid form', fakeAsync(async () => {

await setup();

// Wait for async validators

tick(1000);

findEl(fixture, 'form').triggerEventHandler('submit', {});

expect(signupService.isUsernameTaken).not.toHaveBeenCalled();

expect(signupService.isEmailTaken).not.toHaveBeenCalled();

expect(signupService.getPasswordStrength).not.toHaveBeenCalled();

expect(signupService.signup).not.toHaveBeenCalled();

}));

This spec does less than the previous. We wait for a second and
submit the form without entering data. Finally, we expect that no
SignupService method has been called.

🔗 SignupFormComponent: test code

Form submission failure

We have already tested the successful form submission. Now let
us test the form submission failure.

REASONS FOR FAILURE

Despite correct input, the submission may fail for several
reasons:

The network is unavailable

The back-end processed the request but returned an error:

The server-side validation failed

The request structure is not as expected

The server code has bugs, has crashed or is frozen

OBSERVABLE

When the user submits the form, the Component under tests
calls the SignupService’s signup method.

In the success case, the signup method returns an

Observable that emits the value { success: true } and
completes. The form displays a status message “Sign-up
successful!”.

In the error case, the Observable fails with an error. The form
displays a status message “Sign-up error”.

Let us test the latter case in a new spec. The structure resembles
the spec for the successful submission. But we configure the
fake signup method to return an Observable that fails with an
error.

import { throwError } from 'rxjs';

it('handles signup failure', fakeAsync(async () => {

await setup({

// Let the API report a failure

signup: throwError(new Error('Validation failed')),

});

/* … */

});

We fill out the form, wait for the validators and submit the form.

fillForm();

// Wait for async validators

tick(1000);

findEl(fixture, 'form').triggerEventHandler('submit', {});

fixture.detectChanges();

STATUS MESSAGE

Finally, we expect the “Sign-up error” status message to appear.

Also, we verify that the relevant SignupService methods have
been called.

expectText(fixture, 'status', 'Sign-up error');

expect(signupService.isUsernameTaken).toHaveBeenCalledWith(username
);

expect(signupService.getPasswordStrength).toHaveBeenCalledWith(pass
word);

expect(signupService.signup).toHaveBeenCalledWith(signupData);

The full spec:

it('handles signup failure', fakeAsync(async () => {

await setup({

// Let the API report a failure

signup: throwError(new Error('Validation failed')),

});

fillForm();

// Wait for async validators

tick(1000);

findEl(fixture, 'form').triggerEventHandler('submit', {});

fixture.detectChanges();

expectText(fixture, 'status', 'Sign-up error');

expect(signupService.isUsernameTaken).toHaveBeenCalledWith(username
);

expect(signupService.getPasswordStrength).toHaveBeenCalledWith(pass
word);

expect(signupService.signup).toHaveBeenCalledWith(signupData);

}));

🔗 SignupFormComponent: test code

Required fields
A vital form logic is that certain fields are required and that the
user interface conveys the fact clearly. Let us write a spec that
checks whether required fields as marked as such.

REQUIREMENTS

The requirements are:

A required field has an aria-required attribute.

A required, invalid field has an aria-errormessage

attribute. It contains the id of another element.

This element contains an error message “… must be given”.

(The text for the Terms of Services checkbox reads “Please
accept the Terms and Services” instead.)

Our spec needs to verify all required fields, so we compile a list

of their respective test ids:

const requiredFields = [

'username',

'email',

'name',

'addressLine2',

'city',

'postcode',

'country',

'tos',

];

INVALID && (TOUCHED ||  DIRTY)

Before examining the fields, we need to trigger the display of

form errors. As described in Form validation and errors, error
messages are shown when the field is invalid and either touched
or dirty.

Luckily, the empty, but required fields are already invalid.

Entering text would make them dirty but also valid.

MARK AS TOUCHED

So we need to touch the fields. If a field is focussed and loses

focus again, Angular considers it as touched. Under the hood,
Angular listens for the blur event.

In our spec, we simulate a blur event using the

dispatchFakeEvent testing helper. Let us put the call in a
reusable function:

const markFieldAsTouched = (element: DebugElement) => {

dispatchFakeEvent(element.nativeElement, 'blur');

};

We can now write the Arrange and Act phases of the spec:

it('marks fields as required', async () => {

await setup();

// Mark required fields as touched

requiredFields.forEach((testId) => {

markFieldAsTouched(findEl(fixture, testId));

});

fixture.detectChanges();

/* … */

});

A forEach loop walks through the required field test ids, finds
the element and marks the field as touched. We call
detectChanges afterwards so the error messages appear.

ARIA-REQUIRED

Next, the Assert phase. Again we walk through the required fields
to examine each one of them. Let us start with the aria-
required attribute.

requiredFields.forEach((testId) => {

const el = findEl(fixture, testId);

// Check aria-required attribute

expect(el.attributes['aria-required']).toBe(

'true',

`${testId} must be marked as aria-required`,

);

/* … */

});

findEl returns a DebugElement with an attributes property.

This object contains all attributes set by the template. We expect
the attribute aria-required="true" to be present.

ARIA-ERRORMESSAGE

The next part tests the error message with three steps:

1. Read the aria-errormessage attribute. Expect that it is set.

2. Find the element that aria-errormessage refers to. Expect

that it exists.

3. Read the text content. Expect an error message.

Step 1 looks like this:

// Check aria-errormessage attribute

const errormessageId = el.attributes['aria-errormessage'];

if (!errormessageId) {

throw new Error(`Error message id for ${testId} not present`);

Normally, we would use a Jasmine expectation like

expect(errormessageId).toBeDefined(). But
errormessageId has the type string | null whereas we
need a string in the upcoming commands.

TYPE ASSERTIONS
We need a TypeScript type assertion that rules out the null case
and narrows down the type to string. If the attribute is absent
or empty, we throw an exception. This fails the test with the
given error and ensures that errormessageId is a string for the
rest of the spec.

Step 2 finds the error message element:

// Check element with error message

const errormessageEl = document.getElementById(errormessageId);

if (!errormessageEl) {

throw new Error(`Error message element for ${testId} not found`);

We use the native DOM method document.getElementById to

find the element. errormessageEl has the type HTMLElement
| null, so we rule out the null case to work with
errormessageEl.

ERROR MESSAGE

Finally, we ensure that the element contains an error message,

with a special treatment of the Terms and Services message.

if (errormessageId === 'tos-errors') {

expect(errormessageEl.textContent).toContain(

'Please accept the Terms and Services',

);

} else {

expect(errormessageEl.textContent).toContain('must be given');

The full spec looks like this:

it('marks fields as required', async () => {

await setup();

// Mark required fields as touched

requiredFields.forEach((testId) => {

markFieldAsTouched(findEl(fixture, testId));

});

fixture.detectChanges();

requiredFields.forEach((testId) => {

const el = findEl(fixture, testId);

// Check aria-required attribute

expect(el.attributes['aria-required']).toBe(

'true',

`${testId} must be marked as aria-required`,

);

// Check aria-errormessage attribute

const errormessageId = el.attributes['aria-errormessage'];

if (!errormessageId) {

throw new Error(

`Error message id for ${testId} not present`

);

// Check element with error message

const errormessageEl = document.getElementById(errormessageId);

if (!errormessageEl) {

throw new Error(

`Error message element for ${testId} not found`

);

if (errormessageId === 'tos-errors') {

expect(errormessageEl.textContent).toContain(

'Please accept the Terms and Services',

);

} else {

expect(errormessageEl.textContent).toContain('must be
given');

});

});

🔗 SignupFormComponent: test code

Asynchronous validators
The sign-up form features asynchronous validators for
username, email and password. They are asynchronous because
they wait for a second and make an HTTP request. Under the
hood, they are implemented using RxJS Observables.

ASYNC VALIDATION FAILURE

We have already covered the “happy path” in which the entered

username and email are available and the password is strong
enough. We need to write three specs for the error cases:
Username or email are taken and the password is too weak.

The validators call SignupService methods. Per default, the

SignupService fake returns successful responses.
const setup = async (

signupServiceReturnValues?:

jasmine.SpyObjMethodNames<SignupService>,

) => {

signupService = jasmine.createSpyObj<SignupService>(

'SignupService',

// Successful responses per default

isUsernameTaken: of(false),

isEmailTaken: of(false),

getPasswordStrength: of(strongPassword),

signup: of({ success: true }),

// Overwrite with given return values

...signupServiceReturnValues,

);

/* … */

};

The setup function allows us to overwrite the fake behavior. It

accepts an object with SignupService method return values.

We add three specs that configure the fake accordingly:

it('fails if the username is taken', fakeAsync(async () => {

await setup({

// Let the API return that the username is taken

isUsernameTaken: of(true),

});

/* … */

}));

it('fails if the email is taken', fakeAsync(async () => {

await setup({

// Let the API return that the email is taken

isEmailTaken: of(true),

});

/* … */

}));

it('fails if the password is too weak', fakeAsync(async () => {

await setup({

// Let the API return that the password is weak

getPasswordStrength: of(weakPassword),

});

/* … */

}));

The rest is the same for all three specs. Here is the first spec:

it('fails if the username is taken', fakeAsync(async () => {

await setup({

// Let the API return that the username is taken

isUsernameTaken: of(true),

});

fillForm();

// Wait for async validators

tick(1000);

fixture.detectChanges();

expect(findEl(fixture, 'submit').properties.disabled).toBe(true);

findEl(fixture, 'form').triggerEventHandler('submit', {});

expect(signupService.isUsernameTaken).toHaveBeenCalledWith(username
);

expect(signupService.isEmailTaken).toHaveBeenCalledWith(email);

expect(signupService.getPasswordStrength).toHaveBeenCalledWith(pass
word);

expect(signupService.signup).not.toHaveBeenCalled();

}));

We fill out the form, wait for the async validators and try to
submit the form.

We expect that the three async validators call the respective

SignupService methods.

The username validation fails, so we expect that the Component

prevents the form submission. The signup method must not be
called.

As stated above, the two other specs it('fails if the

email is taken', /* … */) and it('fails if the
password is too weak', /* … */) look the same apart
from the fake setup.

🔗 SignupFormComponent: test code

🔗 Angular documentation: Creating asynchronous validators

Dynamic field relations

The sign-up form has a fixed set of fields. But the addressLine1
field depends on the value of the plan field:

If the selected plan is “Personal”, the field is optional and the

label reads “Address line 1”.

If the selected plan is “Business”, the field is required and the

label reads “Company”.

If the selected plan is “Education & Non-profit”, the field is

required and the label reads “Organization”.

The implementation in the Component class looks like this:

this.plan.valueChanges.subscribe((plan: Plan) => {

if (plan !== this.PERSONAL) {

this.addressLine1.setValidators(required);

} else {

this.addressLine1.setValidators(null);

this.addressLine1.updateValueAndValidity();

});

We listen for value changes of the plan control. Depending on

the selection, we either add the required validator to the
addressLine1 control or remove all validators.

Finally, we need to tell Angular to revalidate the field value, now

that the validators have changed.
Let us write a spec to ensure that addressLine1 is required for
certain plans.

it('requires address line 1 for business and non-profit plans',

async () => {

await setup();

/* … */

});

First, we need inspect the initial state: The “Personal” plan is

selected and addressLine1 is optional.

We do so by looking at attributes of the addressLine1 field

element: The ng-invalid class and the aria-required
attribute must be absent.

// Initial state (personal plan)

const addressLine1El = findEl(fixture, 'addressLine1');

expect('ng-invalid' in addressLine1El.classes).toBe(false);

expect('aria-required' in addressLine1El.attributes).toBe(false);

From this baseline, let us change the plan from “Personal” to

“Business”. We use the checkField spec helper to activate the
corresponding radio button.

// Change plan to business

checkField(fixture, 'plan-business', true);

fixture.detectChanges();

To see the effect of the change, we need to tell Angular to

update the DOM. Then we expect the ng-invalid class and the
aria-required to be present.

expect(addressLine1El.attributes['aria-required']).toBe('true');

expect(addressLine1El.classes['ng-invalid']).toBe(true);

We perform the same check for the “Education & Non-profit”

plan.

// Change plan to non-profit

checkField(fixture, 'plan-non-profit', true);

fixture.detectChanges();

expect(addressLine1El.attributes['aria-required']).toBe('true');

expect(addressLine1El.classes['ng-invalid']).toBe(true);

This is it! Here is the full spec:

it('requires address line 1 for business and non-profit plans',

async () => {

await setup();

// Initial state (personal plan)

const addressLine1El = findEl(fixture, 'addressLine1');

expect('ng-invalid' in addressLine1El.classes).toBe(false);

expect('aria-required' in addressLine1El.attributes).toBe(false);

// Change plan to business

checkField(fixture, 'plan-business', true);

fixture.detectChanges();

expect(addressLine1El.attributes['aria-required']).toBe('true');

expect(addressLine1El.classes['ng-invalid']).toBe(true);

// Change plan to non-profit

checkField(fixture, 'plan-non-profit', true);

fixture.detectChanges();

expect(addressLine1El.attributes['aria-required']).toBe('true');

expect(addressLine1El.classes['ng-invalid']).toBe(true);

});

We have already checked the presence of aria-required

attributes when testing the required fields. For consistency, we
check for aria-required in this spec as well.

As a second indicator, we check for the ng-invalid class. This

class is set by Angular itself on invalid form fields without us
having to add it via the template. Note that the mere presence of
the class does not imply that the invalid state is conveyed
visually.

Alternatively, we could check for the presence of an error

message, like we did in the required fields spec.

🔗 SignupFormComponent: test code

Password type toggle

Another small feature of the sign-up form is the password type
switcher. This button toggles the visibility of the entered
password. Under the hood, it changes the input type from
password to text and vice versa.

The Component class stores the visibility in a boolean property:

public showPassword = false;

In the template, the input type depends on the property

(shortened code):

<input [type]="showPassword ? 'text' : 'password'" />

Finally, the button toggles the boolean value (shortened code):

<button

type="button"

(click)="showPassword = !showPassword"

>

{{ showPassword ? '🔒 Hide password' : '👁️ Show password' }}

</button>

To test this feature, we create a new spec:

it('toggles the password display', async () => {

await setup();

/* … */

});

Initially, the field has the password type so the entered text is
obfuscated. Let us test this baseline.

First, we enter a password into the field. This is not strictly

necessary but makes the test more realistic and debugging
easier. (The password field has the test id password.)

setFieldValue(fixture, 'password', 'top secret');

We find the input element by its test id again to check the type
attribute.

const passwordEl = findEl(fixture, 'password');

expect(passwordEl.attributes.type).toBe('password');

Now we click on the toggle button for the first time. We let
Angular update the DOM and check the input type again.

click(fixture, 'show-password');

fixture.detectChanges();

expect(passwordEl.attributes.type).toBe('text');

We expect that the type has changed from password to text.

The password is now visible.

With a second click on the toggle button, the type switches back
to password.

click(fixture, 'show-password');

fixture.detectChanges();

expect(passwordEl.attributes.type).toBe('password');

This is the whole spec:

it('toggles the password display', async () => {

await setup();

setFieldValue(fixture, 'password', 'top secret');

const passwordEl = findEl(fixture, 'password');

expect(passwordEl.attributes.type).toBe('password');

click(fixture, 'show-password');

fixture.detectChanges();

expect(passwordEl.attributes.type).toBe('text');

click(fixture, 'show-password');

fixture.detectChanges();

expect(passwordEl.attributes.type).toBe('password');

});

🔗 SignupFormComponent: test code

Testing form accessibility

Web accessibility means that all people can use a web site,
regardless of their physical or mental abilities or web access
technologies. It is is part of a greater effort called Inclusive
Design, the process of creating information systems that
account for people with diverse abilities and needs.

Designing web forms is a usability and accessibility challenge.

Web forms often pose a barrier for users with disabilities and
users of assistive technologies.

ACCESSIBLE FORM

The sign-up form has several accessibility features, among

others:

The form is well-structured with heading, fieldset and

legend elements.

All fields have proper labels, e.g. “Username (required)”.

Some fields have additional descriptions. The descriptions are

linked with aria-describedby attributes.

Required fields are marked with aria-required="true".

Invalid fields are marked with aria-invalid="true". The

error messages are linked with aria-errormessage
attributes.

When the form is submitted, the result is communicated

using a status message with role="status".
The structure and styling clearly conveys the current focus as
well as the validity state.

AUTOMATED ACCESSIBILITY TESTING

There are many more accessibility requirements and best

practices that we have not mentioned. Since this guide is not
about creating accessible forms primarily, let us explore how to
test accessibility in an automated way.

We have tested some of the features above in the

SignupFormComponent’s integration test. Instead of writing
more specs for accessibility requirements by hand, let us test the
accessibility with a proper tool.

🔗 Inclusive Design Principles

pa11y
In this guide, we will look at pa11y, a Node.js program that
checks the accessibility of a web page.

TESTS IN CHROME

pa11y starts and remotely-controls a Chrome or Chromium

browser. The browser navigates to the page under test. pa11y
then injects axe-core and/or HTML CodeSniffer, two accessibility
testing engines.
These engines check compliance with the Web Content
Accessibility Guidelines (WCAG), the authoritative technical
standard for web accessibility.

CLI VS. CI

pa11y has two modes of operation: The command line interface

(CLI) for checking one web page and the continuous integration
(CI) mode for checking multiple web pages.

For quickly testing a single page of your Angular application, use

the command line interface. When testing the whole application
on a regular basis, use the continuous integration mode.

To use the command line interface, install pa11y as a global npm

module:

npm install -g pa11y

TEST SINGLE PAGE

This installs the global command pa11y. To test a page on the

local Angular development server, run:

pa11y http://localhost:4200/

For the sign-up form, pa11y does not report any errors:

Welcome to Pa11y

> Running Pa11y on URL http://localhost:4200/

No issues found!

ERROR REPORT

If one of the form fields did not have a proper label, pa11y would
complain:

• Error: This textinput element does not have a name available to

an accessibility API. Valid names are: label element,

title undefined, aria-label undefined, aria-labelledby

undefined.

├── WCAG2AA.Principle4.Guideline4_1.4_1_2.H91.InputText.Name

├── html > body > app-root > main > app-signup-form > form >
fieldset:nth-child(2) > div:nth-child(2) > p > span > input

└── <input _ngcontent-srr-c42="" type="text"

formcontrolname="username" …

• Error: This form field should be labelled in some way.

Use the label element (either with a "for" attribute or

wrapped around the form field), or "title", "aria-label"

or "aria-labelledby" attributes as appropriate.

├── WCAG2AA.Principle1.Guideline1_3.1_3_1.F68

├── html > body > app-root > main > app-signup-form > form >
fieldset:nth-child(2) > div:nth-child(2) > p > span > input

└── <input _ngcontent-srr-c42="" type="text"

formcontrolname="username" …

Each error message contains the violated WCAG rule, the DOM
path to the violating element and its HTML code.

🔗 pa11y: Accessibility testing tools

🔗 axe-core: Accessibility engine for automated Web UI testing
🔗 HTML CodeSniffer: Accessibility auditor
🔗 Web Content Accessibility Guidelines (WCAG) 2.1

pa11y-ci
For comprehensive test runs both during development and on a
build server, we will set up pa11y in the continuous integration
mode.

In your Angular project directory, install the pa11y-ci package:

npm install pa11y-ci

pa11y-ci expects a configuration file named .pa11yci in the

project directory. Create the file and paste this JSON:

"defaults": {

"runner": [

"axe",

"htmlcs"

},

"urls": [

"http://localhost:4200"

TEST MULTIPLE URLS

This configuration tells pa11y to check the URL

http://localhost:4200 and to use both available testing engines,
axe and htmlcs. You can add many URLs to the urls array.

We can now run pa11y-ci with:

npx pa11y-ci

For the sign-up form, we get this output:

Running Pa11y on 1 URLs:

> http://localhost:4200 - 0 errors

✔ 1/1 URLs passed

🔗 pa11y-ci: CI-centric accessibility test runner

Start server and run pa11y-ci

The configuration above expects that the development server is
already running at http://localhost:4200. Both in development
and on a build server, it is useful to start the Angular server, run
the accessibility tests and then stop the server again.

We can achieve this with another handy Node.js package,

start-server-and-test.

npm install start-server-and-test

start-server-and-test first runs an npm script that is

supposed to start an HTTP server. Then it waits for the server to
boot up. Once a given URL is available, it runs another npm
script.

In our case, the first script is start, an alias for ng serve. We

need to create the second script to run pa11y-ci.

NPM SCRIPTS

We edit package.json, and add two scripts:

"scripts": {

"a11y": "start-server-and-test start http-get://localhost:4200/

pa11y-ci",

"pa11y-ci": "pa11y-ci"

},

Now, npm run a11y starts the Angular development server,

then runs pa11y-ci, finally stops the server. The audit result is
written to the standard output.

🔗 start-server-and-test: Starts server, waits for URL, then runs test command

Form accessibility: Summary

pa11y is a powerful set of tools with many options. We have
barely touched on its features.
Automated accessibility testing is a valuable addition to unit,
integration and end-to-end tests. You should run an accessibility
tester like pa11y against the pages of your Angular application.
It is especially helpful to ensure the accessibility of complex
forms.

Bear in mind that automated testing only points out certain

accessibility barriers that can be detected programmatically.

The Web Content Accessibility Guidelines (WCAG) establish –

 from abstract to specific – principles, guidelines and success
criteria. The latter are the practical rules some of which can be
checked automatically.

The WCAG success criteria are accompanied by techniques for

HTML, CSS, JavaScript etc. For JavaScript web applications,
techniques like ARIA are especially relevant.

In summary, you need to learn about accessibility and Inclusive

Design first, apply the rules while designing and implementing
the application. Then check the compliance manually and
automatically.

🔗 Web Content Accessibility Guidelines (WCAG) 2.1

🔗 Quick Reference: How to Meet WCAG
🔗 WebAIM: Introduction to ARIA - Accessible Rich Internet Applications
🔗 Web Accessibility Tutorial: Forms
Testing Components with
Spectator
LEARNING OBJECTIVES

Simplifying Component tests with the Spectator library

Using the unified Spectator interface
Interacting with the Component and the rendered DOM
Dispatching synthetic DOM events to simulate user input
Using Spectator and ng-mocks to fake child Components and Services

We have used Angular’s testing tools to set up modules, render

Components, query the DOM and more. These tools are
TestBed, ComponentFixture and DebugElement, also
HttpClientTestingModule and RouterTestingModule.

STRUCTURAL WEAKNESSES

The built-in tools are fairly low-level and unopinionated. They

have several drawbacks:

TestBed requires a large amount of boilerplate code to set

up a common Component or Service test.

DebugElement lacks essential features and is a “leaky”

abstraction. You are forced to work with the wrapped native
DOM element for common tasks.
There are no default solutions for faking Components and
Service dependencies safely.

The tests itself get verbose and repetitive. You have to

establish testing conventions and write helpers yourself.

We have already used small element testing helpers. They solve

isolated problems in order to write more consistent and compact
specs.

If you write hundreds or thousands of specs, you will find that

these helper functions do not suffice. They do not address the
above-mentioned structural problems.

UNIFIED TESTING API

Spectator is an opinionated library for testing Angular

applications. Technically, it sits on top of TestBed,
ComponentFixture and DebugElement. But the main idea is to
unify all these APIs in one consistent, powerful and user-friendly
interface – the Spectator object.

Spectator simplifies testing Components, Services, Directives,

Pipes, routing and HTTP communication. Spectator’s strength
are Component tests with Inputs, Outputs, children, event
handling, Service dependencies and more.
For faking child Components, Spectator resorts to the ng-mocks
library just like we did.

This guide cannot introduce all Spectator features, but we will

discuss the basics of Component testing using Spectator.

Both example applications are tested with our element helpers

and also with Spectator. The former specs use the suffix
.spec.ts, while the latter use the suffix .spectator.spec.ts.
This way, you can compare the tests side-by-side.

In this chapter, we will discuss testing the Flickr search with

Spectator.

Component with an Input

Let us start with the FullPhotoComponent because it is a
presentational Component, a leaf in the Component tree. It
expects a Photo object as Input and renders an image as well as
the photo metadata. No Outputs, no children, no Service
dependencies.

The FullPhotoComponent suite with our helpers looks like this:

describe('FullPhotoComponent', () => {

let component: FullPhotoComponent;

let fixture: ComponentFixture<FullPhotoComponent>;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [FullPhotoComponent],

schemas: [NO_ERRORS_SCHEMA],

}).compileComponents();

fixture = TestBed.createComponent(FullPhotoComponent);

component = fixture.componentInstance;

component.photo = photo1;

fixture.detectChanges();

});

it('renders the photo information', () => {

expectText(fixture, 'full-photo-title', photo1.title);

const img = findEl(fixture, 'full-photo-image');

expect(img.properties.src).toBe(photo1.url_m);

expect(img.properties.alt).toBe(photo1.title);

expectText(fixture, 'full-photo-ownername', photo1.ownername);

expectText(fixture, 'full-photo-datetaken', photo1.datetaken);

expectText(fixture, 'full-photo-tags', photo1.tags);

const link = findEl(fixture, 'full-photo-link');

expect(link.properties.href).toBe(photo1Link);

expect(link.nativeElement.textContent.trim()).toBe(photo1Link);

});

});

This suite already benefits from expectText and findEl, but it

is still using the leaky DebugElement abstraction.

COMPONENT FACTORY
When using Spectator, the Module configuration and the
Component creation looks different. In the scope of the test
suite, we create a Component factory:

import { createComponentFactory } from '@ngneat/spectator';

describe('FullPhotoComponent with spectator', () => {

/* … */

const createComponent = createComponentFactory({

component: FullPhotoComponent,

shallow: true,

});

/* … */

});

createComponentFactory expects a configuration object.

component: FullPhotoComponent specifies the Component
under test. shallow: true means we want shallow, not deep
rendering. It does not make a difference for
FullPhotoComponent though since it has no children.

The configuration object may include more options for the

testing Module, as we will see later.

Internally, createComponentFactory creates a beforeEach

block that calls TestBed.configureTestingModule and
TestBed.compileComponents, just like we did manually.
createComponentFactory returns a factory function for
creating a FullPhotoComponent. We save that function in the
createComponent constant.

CREATE COMPONENT

The next step is to add a beforeEach block that creates the

Component instance. createComponent again takes an options
object. To set the photo Input property, we pass props: {
photo: photo1 }.

import { createComponentFactory, Spectator } from

'@ngneat/spectator';

describe('FullPhotoComponent with spectator', () => {

let spectator: Spectator<FullPhotoComponent>;

const createComponent = createComponentFactory({

component: FullPhotoComponent,

shallow: true,

});

beforeEach(() => {

spectator = createComponent({ props: { photo: photo1 } });

});

/* … */

});

SPECTATOR
createComponent returns a Spectator object. This is the
powerful interface we are going to use in the specs.

The spec it('renders the photo information', /* …

*/) repeats three essential tasks several times:

1. Find an element by test id

2. Check its text content

3. Check its attribute value

First, the spec finds the element with the test id full-photo-
title and expects it to contain the photo’s title.

With Spectator, it reads:

expect(

spectator.query(byTestId('full-photo-title'))

).toHaveText(photo1.title);

SPECTATOR.QUERY

The central spectator.query method finds an element in the

DOM. This guide recommends to find elements by test ids
(data-testid attributes).

Spectator supports test ids out of the box, so we write:

spectator.query(byTestId('full-photo-title'))

spectator.query returns a native DOM element or null in

case no match was found. Note that it does not return a
DebugElement.

When using Spectator, you work directly with DOM element

objects. What seems cumbersome at first glance, in fact lifts the
burden of the leaky DebugElement abstraction.

JASMINE MATCHERS

Spectator makes it easy to work with plain DOM elements.

Several matchers are added to Jasmine to create expectations on
an element.

For checking an element’s text content, Spectator provides the

toHaveText matcher. This leads us to the following expectation:

expect(

spectator.query(byTestId('full-photo-title'))

).toHaveText(photo1.title);

This code is equivalent to our expectText helper, but more

idiomatic and fluent to read.

Next, we need to verify that the Component renders the full

photo using an img element.

const img = spectator.query(byTestId('full-photo-image'));

expect(img).toHaveAttribute('src', photo1.url_m);

expect(img).toHaveAttribute('alt', photo1.title);

Here, we find the element with the test id full-photo-image to

check its src and alt attributes. We use Spectator’s matcher
toHaveAttribute for this purpose.

The rest of the spec finds more elements to inspect their

contents and attributes.

The full test suite using Spectator (only imports from Spectator
are shown):

import {

byTestId, createComponentFactory, Spectator

} from '@ngneat/spectator';

describe('FullPhotoComponent with spectator', () => {

let spectator: Spectator<FullPhotoComponent>;

const createComponent = createComponentFactory({

component: FullPhotoComponent,

shallow: true,

});

beforeEach(() => {

spectator = createComponent({ props: { photo: photo1 } });

});

it('renders the photo information', () => {

expect(

spectator.query(byTestId('full-photo-title'))

).toHaveText(photo1.title);

const img = spectator.query(byTestId('full-photo-image'));

expect(img).toHaveAttribute('src', photo1.url_m);

expect(img).toHaveAttribute('alt', photo1.title);

expect(

spectator.query(byTestId('full-photo-ownername'))

).toHaveText(photo1.ownername);

expect(

spectator.query(byTestId('full-photo-datetaken'))

).toHaveText(photo1.datetaken);

expect(

spectator.query(byTestId('full-photo-tags'))

).toHaveText(photo1.tags);

const link = spectator.query(byTestId('full-photo-link'));

expect(link).toHaveAttribute('href', photo1Link);

expect(link).toHaveText(photo1Link);

});

});

Compared to the version with custom testing helpers, the

Spectator version is not necessarily shorter. But it works on a
consistent abstraction level.

Instead of a wild mix of TestBed, ComponentFixture,

DebugElement plus helper functions, there is the
createComponentFactory function and one Spectator
instance.

Spectator avoids wrapping DOM elements, but offers convenient

Jasmine matchers for common DOM expectations.

🔗 FullPhotoComponent: implementation code and the two tests

🔗 Spectator: Queries
🔗 Spectator: Custom matchers

Component with children and

Service dependency
Spectator really shines when testing container Components.
These are Components with children and Service dependencies.

In the Flickr search, the topmost FlickrSearchComponent calls

the FlickrService and holds the state. It orchestrates three
other Components, passes down the state and listens for
Outputs.

The FlickrSearchComponent template:

<app-search-form (search)="handleSearch($event)"></app-search-form>

<div class="photo-list-and-full-photo">

<app-photo-list

[title]="searchTerm"

[photos]="photos"

(focusPhoto)="handleFocusPhoto($event)"

class="photo-list"

></app-photo-list>

<app-full-photo

*ngIf="currentPhoto"

[photo]="currentPhoto"

class="full-photo"

data-testid="full-photo"

></app-full-photo>

</div>

The FlickrSearchComponent class:

@Component({

selector: 'app-flickr-search',

templateUrl: './flickr-search.component.html',

styleUrls: ['./flickr-search.component.css'],

})

export class FlickrSearchComponent {

public searchTerm = '';

public photos: Photo[] = [];

public currentPhoto: Photo | null = null;

constructor(private flickrService: FlickrService) {}

public handleSearch(searchTerm: string): void {

this.flickrService.searchPublicPhotos(searchTerm).subscribe(

(photos) => {

this.searchTerm = searchTerm;

this.photos = photos;

this.currentPhoto = null;

);

public handleFocusPhoto(photo: Photo): void {

this.currentPhoto = photo;

CHILD COMPONENTS

Since this is the Component where all things come together,

there is much to test.

1. Initially, the SearchFormComponent and the

PhotoListComponent are rendered, not the
FullPhotoComponent. The photo list is empty.

2. When the SearchFormComponent emits the search Output,

the FlickrService is called with the search term.

3. The search term and the photo list are passed down to the
PhotoListComponent via Inputs.

4. When the PhotoListComponent emits the focusPhoto

Output, the FullPhotoComponent is rendered. The selected
photo is passed down via Input.

WITHOUT SPECTATOR

The FlickrSearchComponent test suite with our helpers looks

like this:

describe('FlickrSearchComponent', () => {

let fixture: ComponentFixture<FlickrSearchComponent>;

let component: FlickrSearchComponent;

let fakeFlickrService: Pick<FlickrService, keyof FlickrService>;

let searchForm: DebugElement;

let photoList: DebugElement;

beforeEach(async () => {

fakeFlickrService = {

searchPublicPhotos: jasmine

.createSpy('searchPublicPhotos')

.and.returnValue(of(photos)),

};

await TestBed.configureTestingModule({

imports: [HttpClientTestingModule],

declarations: [FlickrSearchComponent],

providers: [

{ provide: FlickrService, useValue: fakeFlickrService }

],

schemas: [NO_ERRORS_SCHEMA],

}).compileComponents();

});

beforeEach(() => {

fixture = TestBed.createComponent(FlickrSearchComponent);

component = fixture.debugElement.componentInstance;

fixture.detectChanges();

searchForm = findComponent(fixture, 'app-search-form');

photoList = findComponent(fixture, 'app-photo-list');

});

it('renders the search form and the photo list, not the full
photo', () => {

expect(searchForm).toBeTruthy();

expect(photoList).toBeTruthy();

expect(photoList.properties.title).toBe('');

expect(photoList.properties.photos).toEqual([]);

expect(() => {

findComponent(fixture, 'app-full-photo');

}).toThrow();

});

it('searches and passes the resulting photos to the photo list',

() => {

const searchTerm = 'beautiful flowers';

searchForm.triggerEventHandler('search', searchTerm);

fixture.detectChanges();

expect(fakeFlickrService.searchPublicPhotos).toHaveBeenCalledWith(s
earchTerm);

expect(photoList.properties.title).toBe(searchTerm);

expect(photoList.properties.photos).toBe(photos);

});

it('renders the full photo when a photo is focussed', () => {

expect(() => {

findComponent(fixture, 'app-full-photo');

}).toThrow();

photoList.triggerEventHandler('focusPhoto', photo1);

fixture.detectChanges();

const fullPhoto = findComponent(fixture, 'app-full-photo');

expect(fullPhoto.properties.photo).toBe(photo1);

});

});

Without going too much into detail, a few notes:

We use shallow rendering. The child Components are not
declared and only empty shell elements are rendered (app-
search-form, app-photo-list and app-full-photo). This
lets us check their presence, their Inputs and Outputs.

We use our findComponent testing helper to find the child

elements.

To check the Input values, we use the properties of

DebugElements.

To simulate that an Output emits, we use

triggerEventListener on DebugElements.

We provide our own fake FlickrService. It contains one

Jasmine spy that returns a Observable with a fixed list of
photos.

fakeFlickrService = {

searchPublicPhotos: jasmine

.createSpy('searchPublicPhotos')

.and.returnValue(of(photos)),

};

WITH SPECTATOR

Rewriting this suite with Spectator brings two major changes:

1. We replace the child Components with fakes created by ng-

mocks. The fake Components mimic the originals regarding
their Inputs and Outputs, but they do not render anything.
We will work with these Component instances instead of
operating on DebugElements.

2. We use Spectator to create the fake FlickrService.

The test suite setup:

import {

createComponentFactory, mockProvider, Spectator

} from '@ngneat/spectator';

describe('FlickrSearchComponent with spectator', () => {

/* … */

const createComponent = createComponentFactory({

component: FlickrSearchComponent,

shallow: true,

declarations: [

MockComponents(

SearchFormComponent, PhotoListComponent, FullPhotoComponent

),

],

providers: [mockProvider(FlickrService)],

});

/* … */

});

Again, we use Spectator’s createComponentFactory. This time,

we replace the child Components with fakes created by ng-
mocks’ MockComponents function.
MOCKPROVIDER

Then we use Spectator’s mockProvider function to create a fake

FlickrService. Under the hood, this works roughly the same
as our manual fakeFlickrService. It creates an object that
resembles the original, but the methods are replaced with
Jasmine spies.

In a beforeEach block, the Component is created.

import {

createComponentFactory, mockProvider, Spectator

} from '@ngneat/spectator';

describe('FlickrSearchComponent with spectator', () => {

let spectator: Spectator<FlickrSearchComponent>;

let searchForm: SearchFormComponent | null;

let photoList: PhotoListComponent | null;

let fullPhoto: FullPhotoComponent | null;

const createComponent = createComponentFactory(/* … */);

beforeEach(() => {

spectator = createComponent();

spectator.inject(FlickrService).searchPublicPhotos.and.returnValue(
of(photos));

searchForm = spectator.query(SearchFormComponent);

photoList = spectator.query(PhotoListComponent);

fullPhoto = spectator.query(FullPhotoComponent);

});

/* … */

});

spectator.inject is the equivalent of TestBed.inject. We

get hold of the FlickrService fake instance and configure the
searchPublicPhotos spy to return fixed data.

FIND CHILDREN

spectator.query not only finds elements in the DOM, but also

child Components and other nested Directives. We find the three
child Components and save them in variables since they will be
used in all specs.

Note that searchForm, photoList and fullPhoto are typed as

Component instances, not DebugElements. This is accurate
because the fakes have the same public interfaces, the same
Inputs and Output.

Due to the equivalence of fake and original, we can access

Inputs with the pattern componentInstance.input. And we let
an Output emit with the pattern
componentInstance.output.emit(…).

The first spec checks the initial state:

it('renders the search form and the photo list, not the full
photo', () => {

if (!(searchForm && photoList)) {

throw new Error('searchForm or photoList not found');

expect(photoList.title).toBe('');

expect(photoList.photos).toEqual([]);

expect(fullPhoto).not.toExist();

});

spectator.query(PhotoListComponent) either returns the

Component instance or null if there is no such nested
Component. Hence, the photoList variable is typed as
PhotoListComponent | null.

MANUAL TYPE GUARD

Unfortunately, expect is not a TypeScript type guard. Jasmine

expectations cannot narrow down the type from
PhotoListComponent | null to PhotoListComponent.

We cannot call expect(photoList).not.toBe(null) and

continue with expect(photoList.title).toBe(''). The first
expectation throws an error in the null case, but TypeScript
does not know this. TypeScript still assumes the type
PhotoListComponent | null, so it would complain about
photoList.title.

This is why we manually throw an error when photoList is

null. TypeScript infers that the type must be
PhotoListComponent in the rest of the spec.
In contrast, our findComponent helper function throws an
exception directly if no match was found, failing the test early. To
verify that a child Component is absent, we had to expect this
exception:

expect(() => {

findComponent(fixture, 'app-full-photo');

}).toThrow();`.

The Spectator spec goes on and uses

expect(fullPhoto).not.toExist(), which is equivalent to
expect(fullPhoto).toBe(null). The Jasmine matcher
toExist comes from Spectator.

TEST SEARCH

The second spec covers the search:

it('searches and passes the resulting photos to the photo list', ()

=> {

if (!(searchForm && photoList)) {

throw new Error('searchForm or photoList not found');

const searchTerm = 'beautiful flowers';

searchForm.search.emit(searchTerm);

spectator.detectChanges();

const flickrService = spectator.inject(FlickrService);

expect(flickrService.searchPublicPhotos).toHaveBeenCalledWith(searc
hTerm);

expect(photoList.title).toBe(searchTerm);

expect(photoList.photos).toBe(photos);

});

When the SearchFormComponent emits a search term, we

expect that the FlickrService has been called. In addition, we
expect that the search term and the photo list from Service are
passed to the PhotoListComponent.

spectator.detectChanges() is just Spectator’s shortcut to

fixture.detectChanges().

TEST FOCUS PHOTO

The last spec focusses a photo:

it('renders the full photo when a photo is focussed', () => {

expect(fullPhoto).not.toExist();

if (!photoList) {

throw new Error('photoList not found');

photoList.focusPhoto.emit(photo1);

spectator.detectChanges();

fullPhoto = spectator.query(FullPhotoComponent);

if (!fullPhoto) {

throw new Error('fullPhoto not found');

expect(fullPhoto.photo).toBe(photo1);

});

Again, the main difference is that we directly work with Inputs

and Outputs.

🔗 FlickrSearchComponent: implementation code and the two tests

🔗 ng-mocks: How to mock a component
🔗 Spectator: Mocking providers

Event handling with Spectator

Most Components handle input events like mouse clicks,
keypresses or form field changes. To simulate them, we have
used the triggerEventHandler method on DebugElements.
This method does not actually simulate DOM events, it merely
calls the event handlers registered by
(click)="handler($event)" and the like.

triggerEventHandler requires you to create an event object

that becomes $event in the template. For this reason, we have
introduced the click and makeClickEvent helpers.

SYNTHETIC EVENTS

Spectator takes a different approach: It dispatches synthetic

DOM events. This makes the test more realistic. Synthetic events
can bubble up in the DOM tree like real events. Spectator creates
the event objects for you while you can configure the details.
SPECTATOR.CLICK

To perform a simple click, we use spectator.click and pass

the target element or a byTestId selector. An example from the
PhotoItemComponent test:

describe('PhotoItemComponent with spectator', () => {

/* … */

it('focusses a photo on click', () => {

let photo: Photo | undefined;

spectator.component.focusPhoto.subscribe((otherPhoto: Photo) =>

{

photo = otherPhoto;

});

spectator.click(byTestId('photo-item-link'));

expect(photo).toBe(photo1);

});

/* … */

});

Another common task is to simulate form field input. So far, we

have used the setFieldValue helper for this purpose.

SPECTATOR.​
T YPEINELEMENT

Spectator has an equivalent method named

spectator.typeInElement. It is used by the
SearchFormComponent test:
describe('SearchFormComponent with spectator', () => {

/* … */

it('starts a search', () => {

let actualSearchTerm: string | undefined;

spectator.component.search.subscribe((otherSearchTerm: string)
=> {

actualSearchTerm = otherSearchTerm;

});

spectator.typeInElement(searchTerm, byTestId('search-term-
input'));

spectator.dispatchFakeEvent(byTestId('form'), 'submit');

expect(actualSearchTerm).toBe(searchTerm);

});

});

DISPATCH NGSUBMIT

The spec simulates typing the search term into the search field.
Then it simulates an ngSubmit event at the form element. We
use the generic method spectator.dispatchFakeEvent for
this end.

Spectator offers many more convenient shortcuts for triggering

events. The Flickr search Spectator tests just use the most
common ones.

🔗 PhotoItemComponent: implementation code and the two tests

🔗 SearchFormComponent: implementation code and the two tests
🔗 Spectator: Events API

Spectator: Summary
Spectator is a mature library that addresses the practical needs
of Angular developers. It offers solutions for common Angular
testing problems. The examples above presented only a few of
Spectator’s features.

Test code should be both concise and easy to understand.

Spectator provides an expressive, high-level language for writing
Angular tests. Spectator makes simple tasks simple without
losing any power.

Spectator’s success underlines that the standard Angular testing

tools are cumbersome and inconsistent. Alternative concepts are
both necessary and beneficial.

Once you are familiar with the standard tools, you should try out
alternatives like Spectator and ng-mocks. Then decide whether
you stick with isolated testing helpers or switch to more
comprehensive testing libraries.

🔗 Spectator project site

🔗 ng-mocks project site
Testing Services
LEARNING OBJECTIVES

Writing tests for Services with internal state

Testing Observables returned by Services
Verifying HTTP requests and payload processing
Covering HTTP success and error cases

In an Angular application, Services are responsible for fetching,

storing and processing data. Services are singletons, meaning
there is only one instance of a Service during runtime. They are
fit for central data storage, HTTP and WebSocket communication
as well as data validation.

SINGLETON

The single Service instance is shared among Components and

other application parts. Therefore, a Service is used when
Components that are not parent and child need to communicate
with each other and exchange data.

INJECTABLE

“Service” is an umbrella term for any object that serves a specific

purpose and is injected as a dependency. Technically, Services
have little in common. There are no rules regarding the structure
or behavior of a Service.
Typically, Services are classes, but not necessarily. While
Modules, Components and Directives are marked with respective
decorators – @Module, @Component, @Directive –, Services are
marked with the generic @Injectable.

RESPONSIBILITIES

So what does a Service do and how do we test it? Services are

diverse, but some patterns are widespread.

Services have public methods that return values.

In the test, we check whether a method returns correct data.

Services store data. They hold an internal state. We can get or

set the state.

In the test, we check whether the state is changed correctly.

Since the state should be held in private properties, we
cannot access the state directly. We test the state change by
calling public methods. We should not peek into the black
box.

Services interact with dependencies. These are often other

Services. For example, a Service might send HTTP requests
via Angular’s HttpClient.

In the unit test, we replace the dependency with a fake that

returns canned responses.
Testing a Service with internal state
Let us start with testing the CounterService. By now, you
should be familiar with the Service. As a reminder, here is the
shape including private members:

class CounterService {

private count: number;

private subject: BehaviorSubject<number>;

public getCount(): Observable<number> { /* … */ }

public increment(): void { /* … */ }

public decrement(): void { /* … */ }

public reset(newCount: number): void { /* … */ }

private notify(): void { /* … */ }

We need to identify what the Service does, what we need test

and how we test it.

WHAT IT DOES

The Service holds an internal state, namely in the private

count and subject properties. We cannot and should not
access these properties in the test.

For reading the state, the Service has the getCount method.
It does not return a synchronous value, but an RxJS
Observable. We will use getCount to get the current count
and also to subscribe to changes.
For changing the state, the Service provides the methods
increment, decrement and reset. We will call them and
check whether the state has changed accordingly.

Let us write the test code! We create a file called

counter.service.spec.ts and fill it with test suite boilerplate
code:

describe('CounterService', () => {

/* … */

});

We already know what the Service does and what needs to be

tested. So we add specs for all features:

describe('CounterService', () => {

it('returns the count', () => { /* … */ });

it('increments the count', () => { /* … */ });

it('decrements the count', () => { /* … */ });

it('resets the count', () => { /* … */ });

});

INSTANTIATE WITHOUT TESTBED

In the Arrange phase, each spec needs to create an instance of

CounterService. The simplest way to do that is:

const counterService = new CounterService();

This is fine for simple Services without dependencies. For testing

Services with dependencies, we will use the TestBed later.
We create the fresh instance in a beforeEach block since every
spec needs it:

describe('CounterService', () => {

let counterService: CounterService;

beforeEach(() => {

counterService = new CounterService();

});

it('returns the count', () => { /* … */ });

it('increments the count', () => { /* … */ });

it('decrements the count', () => { /* … */ });

it('resets the count', () => { /* … */ });

});

Let us start with writing the spec it('returns the count',

/* … */). It tests the getCount method that returns an
Observable.

CHANGE VARIABLE VALUE

For testing the Observable, we use the same pattern that we

have used for testing a Component Output:

1. We declare a variable actualCount that is initially undefined.

2. We subscribe to the Observable. We assign the emitted value

to the actualCount variable.
3. Finally, outside of the subscriber function, we compare the
actual to the expected value.

it('returns the count', () => {

let actualCount: number | undefined;

counterService.getCount().subscribe((count) => {

actualCount = count;

});

expect(actualCount).toBe(0);

});

This works because the Observable is backed by a

BehaviorSubject that stores the latest value and sends it to
new subscribers immediately.

STATE CHANGE

The next spec tests the increment method. We call the method
and verify that the count state has changed.

As mentioned before, we cannot access the private properties

for this purpose. Just like in the spec above, we need to use the
public getCount method to read the count.

it('increments the count', () => {

counterService.increment();

let actualCount: number | undefined;

counterService.getCount().subscribe((count) => {

actualCount = count;

});

expect(actualCount).toBe(1);

});

EXPECT CHANGED VALUE

The order here is important: First, we call increment, then we

subscribe to the Observable to read and verify the changed
value. Again, the BehaviorSubject emits the current value to
new subscribers synchronously.

The two remaining specs work almost the same. We just call the
respective methods.

it('decrements the count', () => {

counterService.decrement();

let actualCount: number | undefined;

counterService.getCount().subscribe((count) => {

actualCount = count;

});

expect(actualCount).toBe(-1);

});

it('resets the count', () => {

const newCount = 123;

counterService.reset(newCount);

let actualCount: number | undefined;

counterService.getCount().subscribe((count) => {

actualCount = count;

});

expect(actualCount).toBe(newCount);

});

REPEATING PATTERNS

We quickly notice that the specs are highly repetitive and noisy.
In every spec’s Assert phase, we are using this pattern to inspect
the Service state:

let actualCount: number | undefined;

counterService.getCount().subscribe((count) => {

actualCount = count;

});

expect(actualCount).toBe(/* … */);

This is a good candidate for a helper function. Let us call it

expectCount.

function expectCount(count: number): void {

let actualCount: number | undefined;

counterService.getCount().subscribe((actualCount2) => {

actualCount = actualCount2;

});

expect(actualCount).toBe(count);

The pattern has one variable bit, the expected count. That is why
the helper function has one parameter.

UNSUBSCRIBE

Now that we have pulled out the code into a central helper
function, there is one optimization we should add. The First Rule
of RxJS Observables states: “Anyone who subscribes, must
unsubscribe as well”.
In expectCount, we need to get the current count only once.
We do not want to create a long-lasting subscription. We are not
interested in future changes.

If we call expectCount only once per spec, this is not a huge

problem. If we wrote a more complex spec with several
expectCount calls, we would create pointless subscriptions.
This is likely to cause confusion when debugging the subscriber
function.

In short, we want to fetch the count and then unsubscribe to

reduce unwanted subscriptions.

UNSUBSCRIBE MANUALLY

One possible solution is unsubscribing immediately after

subscribing. The subscribe method returns a Subscription
with the useful unsubscribe method.

function expectCount(count: number): void {

let actualCount: number | undefined;

counterService

.getCount()

.subscribe((actualCount2) => {

actualCount = actualCount2;

})

.unsubscribe();

expect(actualCount).toBe(count);

RXJS OPERATOR
A more idiomatic way is to use an RxJS operator that completes
the Observable after the first value: first.

import { first } from 'rxjs/operators';

function expectCount(count: number): void {

let actualCount: number | undefined;

counterService

.getCount()

.pipe(first())

.subscribe((actualCount2) => {

actualCount = actualCount2;

});

expect(actualCount).toBe(count);

If you are not familiar with this arcane RxJS magic, do not worry.
In the simple CounterService test, unsubscribing is not strictly
necessary. But it is a good practice that avoids weird errors when
testing more complex Services that make use of Observables.

The complete test suite now looks like this:

describe('CounterService', () => {

let counterService: CounterService;

function expectCount(count: number): void {

let actualCount: number | undefined;

counterService

.getCount()

.pipe(first())

.subscribe((actualCount2) => {

actualCount = actualCount2;

});

expect(actualCount).toBe(count);

beforeEach(() => {

counterService = new CounterService();

});

it('returns the count', () => {

expectCount(0);

});

it('increments the count', () => {

counterService.increment();

expectCount(1);

});

it('decrements the count', () => {

counterService.decrement();

expectCount(-1);

});

it('resets the count', () => {

const newCount = 123;

counterService.reset(newCount);

expectCount(newCount);

});

});

🔗 CounterService: test code

Testing a Service that sends HTTP
requests
Services without dependencies, like CounterService, are
relatively easy to test. Let us examine a more complex Service
with a dependency.

In the Flickr search, the FlickrService is responsible for searching

photos via the Flickr API. It makes an HTTP GET request to
www.flickr.com. The server responds with JSON. Here is the full
code:

@Injectable()

export class FlickrService {

constructor(private http: HttpClient) {}

public searchPublicPhotos(searchTerm: string):

Observable<Photo[]> {

return this.http

.get<FlickrAPIResponse>(

'https://www.flickr.com/services/rest/',

params: {

tags: searchTerm,

method: 'flickr.photos.search',

format: 'json',

nojsoncallback: '1',

tag_mode: 'all',

media: 'photos',

per_page: '15',

extras: 'tags,date_taken,owner_name,url_q,url_m',

api_key: 'XYZ',

},

.pipe(map((response) => response.photos.photo));

The Service is marked with @Injectable() so it takes part in

Angular’s Dependency Injection. It depends on Angular’s
standard HTTP library, HttpClient from the
@angular/common/http package. Most Angular applications
use HttpClient to communicate with HTTP APIs.

There are two ways to test the FlickrService: an integration

test or a unit test.

REQUESTS AGAINST PRODUCTION

An integration test provides the real HttpClient. This leads to

HTTP requests to the Flickr API when the running the tests. This
makes the whole test unreliable.

The network or the web service might be slow or unavailable.

Also the Flickr API endpoint returns a different response for each
request. It is hard to expect a certain FlickrService behavior if
the input is unknown.
Requests to third-party production APIs make little sense in a
testing environment. If you want to write an integration test for
a Service that makes HTTP request, better use a dedicated
testing API that returns fixed data. This API can run on the same
machine or in the local network.

INTERCEPT REQUESTS

In the case of FlickrService, we better write a unit test.

Angular has a powerful helper for testing code that depends on
HttpClient: the HttpClientTestingModule.

For testing a Service with dependencies, it is tedious to

instantiate the Service with new. Instead, we use the TestBed to
set up a testing Module.

In place of the HttpClient, we import the

HttpClientTestingModule.

TestBed.configureTestingModule({

imports: [HttpClientTestingModule],

providers: [FlickrService],

});

The HttpClientTestingModule provides a fake

implementation of HttpClient. It does not actually send out
HTTP requests. It merely intercepts them and records them
internally.
In the test, we inspect that record of HTTP requests. We respond
to pending requests manually with fake data.

FIND, RESPOND, VERIFY

Our test will perform the following steps:

1. Call the method under test that sends HTTP requests

2. Find pending requests

3. Respond to these requests with fake data

4. Check the result of the method call

5. Verify that all requests have been answered

🔗 Angular guide: Communicating with backend services using HTTP

🔗 Angular API reference: HttpClient
🔗 Angular guide: Testing HTTP requests
🔗 Angular API reference: HttpClientTestingModule

Call the method under test

In the first step, we call the method under test,
searchPublicPhotos. The search term is simply a fixed string.

const searchTerm = 'dragonfly';

describe('FlickrService', () => {

let flickrService: FlickrService;

beforeEach(() => {

TestBed.configureTestingModule({

imports: [HttpClientTestingModule],

providers: [FlickrService],

});

flickrService = TestBed.inject(FlickrService);

});

it('searches for public photos', () => {

flickrService.searchPublicPhotos(searchTerm).subscribe(

(actualPhotos) => {

/* … */

);

/* … */

});

});

We subscribe to the Observable returned by

searchPublicPhotos so the (fake) HTTP request is sent. We will
investigate the response, actualPhotos, later in step four.

Find pending requests

In the second step, we find the pending request using the
HttpTestingController. This class is part of the
HttpClientTestingModule. We get hold of the instance by
calling TestBed.inject(HttpTestingController).
EXPECTONE

The controller has methods to find requests by different criteria.

The simplest is expectOne. It finds a request matching the given
criteria and expects that there is exactly one match.

In our case, we search for a request with a given URL of the Flickr
API.

const searchTerm = 'dragonfly';

const expectedUrl = `https://www.flickr.com/services/rest/?

tags=${searchTerm}&method=flickr.photos.search&format=json&nojsonca
llback=1&tag_mode=all&media=photos&per_page=15&extras=tags,date_tak
en,owner_name,url_q,url_m&api_key=XYZ`;

describe('FlickrService', () => {

let flickrService: FlickrService;

let controller: HttpTestingController;

beforeEach(() => {

TestBed.configureTestingModule({

imports: [HttpClientTestingModule],

providers: [FlickrService],

});

flickrService = TestBed.inject(FlickrService);

controller = TestBed.inject(HttpTestingController);

});

it('searches for public photos', () => {

flickrService.searchPublicPhotos(searchTerm).subscribe(

(actualPhotos) => {

/* … */

);

const request = controller.expectOne(expectedUrl);

/* … */

});

});

expectOne returns the found request, that is an instance of

TestRequest. If there is no pending request that matches the
URL, expectOne throws an exception, failing the spec.

🔗 Angular API reference: HttpTestingController

🔗 Angular API reference: TestRequest

Respond with fake data

Now that we have the pending request at hand, we respond to it
with an object that mimics the original API response. The Flickr
API returns a complex object with an array of photos objects
deep within. In the FlickrService test, we only care about the
payload, the photos array.

The Flickr search repository contains fake photo objects that are
used throughout the tests. For the FlickrService test, we
import the photos array with two fake photo objects.

We use the request’s flush method to respond with fake data.

This simulates a successful “200 OK” server response.
request.flush({ photos: { photo: photos } });

Check the result of the method call

The spec has proven that searchPublicPhotos makes a
request to the expected URL. It still needs to prove that the
method passes through the desired part of the API response. In
particular, it needs to prove that the Observable emits the
photos array.

We have already subscribed to the Observable:

flickrService.searchPublicPhotos(searchTerm).subscribe(

(actualPhotos) => {

/* … */

);

We expect that the Observable emits a photos array that equals

to the one from the API response:

flickrService.searchPublicPhotos(searchTerm).subscribe(

(actualPhotos) => {

expect(actualPhotos).toEqual(photos);

);

This leads to a problem that is known from testing Outputs: If

the code under test is broken, the Observable never emits. The
next callback with expect will not be called. Despite the defect,
Jasmine thinks that all is fine.

EXPECT CHANGED VALUE

There are several ways to solve this problem. We have opted for
a variable that is undefined initially and is assigned a value.

let actualPhotos: Photo[] | undefined;

flickrService.searchPublicPhotos(searchTerm).subscribe(

(otherPhotos) => {

actualPhotos = otherPhotos;

);

const request = controller.expectOne(expectedUrl);

// Answer the request so the Observable emits a value.

request.flush({ photos: { photo: photos } });

// Now verify emitted valued.

expect(actualPhotos).toEqual(photos);

The expect call is located outside of the next callback function

to ensure it is definitely called. If the Observable emits no value
or a wrong value, the spec fails.

Verify that all requests have been

answered
In the last step, we ensure that there are no pending requests
left. We expect the method under test to make one request to a
specific URL. We have found the request with expectOne and
have answered it with flush.

Finally, we call:

controller.verify();

This fails the test if there are any outstanding requests.

verify guarantees that the code under test is not making

excess requests. But it also guarantees that your spec checks all
requests, for example by inspecting their URLs.

Putting the parts together, the full test suite:

const searchTerm = 'dragonfly';

const expectedUrl = `https://www.flickr.com/services/rest/?

tags=${searchTerm}&method=flickr.photos.search&format=json&nojsonca
llback=1&tag_mode=all&media=photos&per_page=15&extras=tags,date_tak
en,owner_name,url_q,url_m&api_key=XYZ`;

describe('FlickrService', () => {

let flickrService: FlickrService;

let controller: HttpTestingController;

beforeEach(() => {

TestBed.configureTestingModule({

imports: [HttpClientTestingModule],

providers: [FlickrService],

});

flickrService = TestBed.inject(FlickrService);

controller = TestBed.inject(HttpTestingController);

});

it('searches for public photos', () => {

let actualPhotos: Photo[] | undefined;

flickrService.searchPublicPhotos(searchTerm).subscribe(

(otherPhotos) => {

actualPhotos = otherPhotos;

);

const request = controller.expectOne(expectedUrl);

request.flush({ photos: { photo: photos } });

controller.verify();

expect(actualPhotos).toEqual(photos);

});

});

🔗 FlickrService: test code

🔗 Photo spec helper

Testing the error case

Are we done with testing searchPublicPhotos? We have
tested the success case in which the server returns a 200 OK.
But we have not tested the error case yet!

UNHAPPY PATH
searchPublicPhotos passes through the error from
HttpClient. If the Observable returned by this.http.get
fails with an error, the Observable returned by
searchPublicPhotos fails with the same error.

Whether there is custom error handling in the Service or not, the

unhappy path should be tested.

Let us simulate a “500 Internal Server Error”. Instead of

responding to the request with flush, we let it fail by calling
error.

const status = 500;

const statusText = 'Internal Server Error';

const errorEvent = new ErrorEvent('API error');

/* … */

const request = controller.expectOne(expectedUrl);

request.error(

errorEvent,

{ status, statusText }

);

The TestRequest’s error method expects an ErrorEvent, and

an optional options object.

ErrorEvent is a special type of Error. For testing purposes, we

create an instance using new ErrorEvent('…'). The
constructor parameter is a string message that describes the
error case.
The second parameter, the options object, allows us to set the
HTTP status (like 500), the statusText (like 'Internal
Server Error') and response headers. In the example above,
we set status and statusText.

EXPECT OBSERVABLE ERROR

Now we check that the returned Observable behaves correctly. It

must not emit a next value and must not complete. It must fail
with an error.

We achieve that by subscribing to next, error and complete

events:

flickrService.searchPublicPhotos(searchTerm).subscribe(

() => {

/* next handler must not be called! */

},

(error) => {

/*

error handler must be called!

Also, we need to inspect the error.

*/

},

() => {

/* complete handler must not be called! */

},

);

FAIL
When the next or complete handlers are called, the spec must
fail immediately. There is a handy global Jasmine function for
this purpose: fail.

For inspecting the error, we use the same pattern as above,

saving the error in a variable in the outer scope.

let actualError: HttpErrorResponse | undefined;

flickrService.searchPublicPhotos(searchTerm).subscribe(

() => {

fail('next handler must not be called');

},

(error) => {

actualError = error;

},

() => {

fail('complete handler must not be called');

},

);

After answering the request with a server error, we check that

the error is passed through. The error handler receives an
HttpErrorResponse object that reflects the ErrorEvent as
well as the status information.

if (!actualError) {

throw new Error('Error needs to be defined');

expect(actualError.error).toBe(errorEvent);

expect(actualError.status).toBe(status);

expect(actualError.statusText).toBe(statusText);

TYPE GUARD

Since actualError is defined as HttpErrorResponse |

undefined, we need to rule out the undefined case first before
accessing the properties.

expect(actualError).toBeDefined() would accomplish

that. But the TypeScript compiler does not know that this rules
out the undefined case. So we need to throw an exception
manually.

This is the full spec for the error case:

it('passes through search errors', () => {

const status = 500;

const statusText = 'Server error';

const errorEvent = new ErrorEvent('API error');

let actualError: HttpErrorResponse | undefined;

flickrService.searchPublicPhotos(searchTerm).subscribe(

() => {

fail('next handler must not be called');

},

(error) => {

actualError = error;

},

() => {

fail('complete handler must not be called');

},

);

controller.expectOne(expectedUrl).error(

errorEvent,

{ status, statusText }

);

if (!actualError) {

throw new Error('Error needs to be defined');

expect(actualError.error).toBe(errorEvent);

expect(actualError.status).toBe(status);

expect(actualError.statusText).toBe(statusText);

});

This example is deliberately verbose. It shows you how to test all

details. It fails fast and provides helpful error messages.

This approach is recommended for Service methods that have a

dedicated error handling. For example, a Service might
distinguish between successful responses (like “200 OK”), client
errors (like “404 Not Found”) and server errors (like “500 Server
error”).

🔗 FlickrService: implementation and test

🔗 Angular API reference: HttpErrorResponse
🔗 MDN reference: ErrorEvent

Alternatives for finding pending requests

We have used controller.expectOne to find a request that
matches the expected URL. Sometimes it is necessary to specify
more criteria, like the method (GET, POST, etc.), headers or the
request body.

expectOne has several signatures. We have used the simplest, a

string that is interpreted as URL:

controller.expectOne('https://www.example.org')

To search for a request with a given method and url, pass an

object with these properties:

controller.expectOne({

method: 'GET',

url: 'https://www.example.org'

})

If you need to find one request by looking at its details, you can
pass a function:

controller.expectOne(

(requestCandidate) =>

requestCandidate.method === 'GET' &&

requestCandidate.url === 'https://www.example.org' &&

requestCandidate.headers.get('Accept') === 'application/json',

);

This predicate function is called for each request, decides

whether the candidate matches and returns a boolean.
This lets you sift through all requests programmatically and
check all criteria. The candidate is an HttpRequest instance with
properties like method, url, headers, body, params, etc.

There are two possible approaches: Either you use expectOne

with many criteria, like in the predicate example. If some request
detail does not match, expectOne throws an exception and fails
the test.

Or you use expectOne with few criteria, passing { method:

'…', url: '…' }. To check the request details, you can still
use Jasmine expectations.

expectOne returns a TestRequest instance. This object only

has methods to answer the request, but no direct information
about the request. Use the request property to access the
underlying HttpRequest.

// Get the TestRequest.

const request = controller.expectOne({

method: 'GET',

url: 'https://www.example.org'

});

// Get the underlying HttpRequest. Yes, this is confusing.

const httpRequest = request.request;

expect(httpRequest.headers.get('Accept')).toBe('application/json');

request.flush({ success: true });

This is equivalent to the predicate example above, but gives a

more specific error message if the header is incorrect.

MATCH

In addition to expectOne, there is the match method for finding

multiple requests that match certain criteria. It returns an array
of requests. If there are no matches, the array is empty, but the
spec does not fail. Hence, you need to add Jasmine expectations
to check the array and the requests therein.

Assume there is a CommentService with a method

postTwoComments. The code under test makes two requests to
the same URL, but with a different body.

@Injectable()

class CommentService() {

constructor(private http: HttpClient) {}

public postTwoComments(firstComment: string, secondComment:

string) {

return combineLatest([

this.http.post('/comments/new', { comment: firstComment }),

this.http.post('/comments/new', { comment: secondComment }),

]);

The spec could contain:

const firstComment = 'First comment!';

const secondComment = 'Second comment!';

commentService

.postTwoComments(firstComment, secondComment)

.subscribe();

const requests = controller.match({

method: 'POST',

url: '/comments/new',

});

expect(requests.length).toBe(2);

expect(requests[0].request.body).toEqual({ comment: firstComment

});

expect(requests[1].request.body).toEqual({ comment: secondComment

});

requests[0].flush({ success: true });

requests[1].flush({ success: true });

We verify the number of requests and also the body of each

request. If these checks pass, we answer each request.

🔗 Angular API reference: HttpRequest

🔗 Angular API reference: TestRequest

Testing Services: Summary

All in all, testing Services is easier than testing other Angular
application parts. Most Services have a clear purpose and a well-
defined public API.

If the Service under test depends on another Service, a unit test

needs to the fake the dependency. This is probably the hardest
part, but takes the same effort as faking Services that are
Component dependencies.

PREDEFINED TESTING MODULES

Angular ships with crucial Services that are commonly used in

your own Services. Since Angular intends to be testable, Angular
also offers tools to replace them with fakes.

We have used the HttpClientTestingModule for testing a

Service that depends on HttpClient. To name another
example, there is the RouterTestingModule for testing
Services that depend on Router and Location.
Testing Pipes
LEARNING OBJECTIVES

Verifying the output of synchronous, pure Pipes

Testing asynchronous, impure Pipes that load data from a Service

An Angular Pipe is a special function that is called from a

Component template. Its purpose is to transform a value: You
pass a value to the Pipe, the Pipe computes a new value and
returns it.

The name Pipe originates from the vertical bar “|” that sits
between the value and the Pipe’s name. The concept as well as
the “|” syntax originate from Unix pipes and Unix shells.

In this example, the value from user.birthday is transformed

by the date Pipe:

{{ user.birthday | date }}

FORMATTING

Pipes are often used for internationalization, including

translation of labels and messages, formatting of dates, times
and various numbers. In these cases, the Pipe input value should
not be shown to the user. The output value is user-readable.
Examples for built-in Pipes are DatePipe, CurrencyPipe and
DecimalPipe. They format dates, amounts of money and
numbers, respectively, according to the localization settings.
Another well-known Pipe is the AsyncPipe which unwraps an
Observable or Promise.

PURE PIPES

Most Pipes are pure, meaning they merely take a value and
compute a new value. They do not have side effects: They do not
change the input value and they do not change the state of
other application parts. Like pure functions, pure Pipes are
relatively easy to test.

GreetPipe
Let us study the structure of a Pipe first to find ways to test it. In
essence, a Pipe is class with a public transform method. Here is
a simple Pipe that expects a name and greets the user.

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

@Pipe({ name: 'greet' })

export class GreetPipe implements PipeTransform {

transform(name: string): string {

return `Hello, ${name}!`;

In a Component template, we transform a value using the Pipe:

{{ 'Julie' | greet }}

The GreetPipe take the string 'Julie' and computes a new

string, 'Hello, Julie!'.

SIMPLE VS. COMPLEX SETUP

There are two important ways to test a Pipe:

1. Create an instance of the Pipe class manually. Then call the

transform method.

This way is fast and straight-forward. It requires minimal

setup.

2. Set up a TestBed. Render a host Component that uses the

Pipe. Then check the text content in the DOM.

This way closely mimics how the Pipe is used in practice. It

also tests the name of the Pipe, as declared in the @Pipe()
decorator.

Both ways allow to test Pipes that depend on Services. Either we

provide the original dependencies, writing an integration test. Or
we provide fake dependencies, writing a unit test.
GreetPipe test
The GreetPipe does not have any dependencies. We opt for the
first way and write a unit test that examines the single instance.

First, we create a Jasmine test suite. In a beforeEach block, we

create an instance of GreetPipe. In the specs, we scrutinize the
transform method.

describe('GreetPipe', () => {

let greetPipe: GreetPipe;

beforeEach(() => {

greetPipe = new GreetPipe();

});

it('says Hello', () => {

expect(greetPipe.transform('Julie')).toBe('Hello, Julie!');

});

});

We call the transform method with the string 'Julie' and

expect the output 'Hello, Julie!'.

This is everything that needs to be tested in the GreetPipe

example. If the transform method contains more logic that
needs to be tested, we add more specs that call the method with
different input.
Testing Pipes with dependencies
Many Pipes depend on local settings, including the user
interface language, date and number formatting rules, as well as
the selected country, region or currency.

We are introducing and testing the TranslatePipe, a complex

Pipe with a Service dependency.

🔗 TranslatePipe: Source code

🔗 TranslatePipe: Run the app
The example application lets you change the user interface
language during runtime. A popular solution for this task is the
ngx-translate library. For the purpose of this guide, we will adopt
ngx-translate’s proven approach but implement and test the
code ourselves.

TranslateService
The current language is stored in the TranslateService. This
Service also loads and holds the translations for the current
language.

The translations are stored in a map of keys and translation

strings. For example, the key greeting translates to “Hello!” if
the current language is English.

The TranslateService looks like this:

import { HttpClient } from '@angular/common/http';

import { EventEmitter, Injectable } from '@angular/core';

import { Observable, of } from 'rxjs';

import { map, take } from 'rxjs/operators';

export interface Translations {

[key: string]: string;

@Injectable()

export class TranslateService {

/** The current language */

private currentLang = 'en';

/** Translations for the current language */

private translations: Translations | null = null;

/** Emits when the language change */

public onTranslationChange = new EventEmitter<Translations>();

constructor(private http: HttpClient) {

this.loadTranslations(this.currentLang);

/** Changes the language */

public use(language: string): void {

this.currentLang = language;

this.loadTranslations(language);

/** Translates a key asynchronously */

public get(key: string): Observable<string> {

if (this.translations) {

return of(this.translations[key]);

return this.onTranslationChange.pipe(

take(1),

map((translations) => translations[key])

);

/** Loads the translations for the given language */

private loadTranslations(language: string): void {

this.translations = null;

this.http

.get<Translations>(`assets/${language}.json`)

.subscribe((translations) => {

this.translations = translations;

this.onTranslationChange.emit(translations);

});

This is what the Service provides:

1. use method: Set the current language and load the

translations as JSON via HTTP.

2. get method: Get the translation for a key.

3. onTranslationChange EventEmitter: Observing changes

on the translations as a result of use.
In the example project, the AppComponent depends on the
TranslateService. On creation, the Service loads the English
translations. The AppComponent renders a select field allowing
the user to change the language.

🔗 TranslateService: implementation code

🔗 TranslateService: test code

TranslatePipe
To show a translated label, a Component could call the Service’s
get method manually for each translation key. Instead, we
introduce the TranslatePipe to do the heavy lifting. It lets us
write:

{{ 'greeting' | translate }}

This translates the key 'greeting'.

Here is the code:

import {

ChangeDetectorRef,

OnDestroy,

Pipe,

PipeTransform,

} from '@angular/core';

import { Subscription } from 'rxjs';

import { TranslateService } from './translate.service';

@Pipe({

name: 'translate',

pure: false,

})

export class TranslatePipe implements PipeTransform, OnDestroy {

private lastKey: string | null = null;

private translation: string | null = null;

private onTranslationChangeSubscription: Subscription;

private getSubscription: Subscription | null = null;

constructor(

private changeDetectorRef: ChangeDetectorRef,

private translateService: TranslateService

) {

this.onTranslationChangeSubscription =

this.translateService.onTranslationChange.subscribe(

() => {

if (this.lastKey) {

this.getTranslation(this.lastKey);

);

public transform(key: string): string | null {

if (key !== this.lastKey) {

this.lastKey = key;

this.getTranslation(key);

return this.translation;

private getTranslation(key: string): void {

this.getSubscription?.unsubscribe();

this.getSubscription = this.translateService

.get(key)

.subscribe((translation) => {

this.translation = translation;

this.changeDetectorRef.markForCheck();

this.getSubscription = null;

});

public ngOnDestroy(): void {

this.onTranslationChangeSubscription.unsubscribe();

this.getSubscription?.unsubscribe();

ASYNC TRANSLATION

The TranslatePipe is impure because the translations are

loaded asynchronously. When called the first time, the
transform method cannot return the correct translation
synchronously. It calls the TranslateService’s get method
which returns an Observable.

TRIGGER CHANGE DETECTION

Once the translation is loaded, the TranslatePipe saves it and

notifies the Angular change detector. In particular, it marks the
corresponding view as changed by calling
ChangeDetectorRef’s markForCheck method.
In turn, Angular re-evaluates every expression that uses the
Pipe, like 'greeting' | translate, and calls the transform
method again. Finally, transform returns the right translation
synchronously.

TRANSLATION CHANGES

The same process happens when the user changes the language
and new translations are loaded. The Pipe subscribes to
TranslateService’s onTranslationChange and calls the
TranslateService again to get the new translation.

🔗 TranslatePipe: implementation code

🔗 Angular API reference: ChangeDetectorRef

TranslatePipe test
Now let us test the TranslatePipe! We can either write a test
that integrates the TranslateService dependency. Or we
write a unit test that replaces the dependency with a fake.

TranslateService performs HTTP requests to load the

translations. We should avoid these side effects when testing
TranslatePipe. So let us fake the Service to write a unit test.

let translateService: Pick<

TranslateService, 'onTranslationChange' | 'get'

>;

/* … */

translateService = {

onTranslationChange: new EventEmitter<Translations>(),

get(key: string): Observable<string> {

return of(`Translation for ${key}`);

},

};

The fake is a partial implementation of the original. The

TranslatePipe under test only needs the
onTranslationChange property and the get method. The
latter returns a fake translation including the key so we can test
that the key was passed correctly.

HOST COMPONENT

Now we need to decide whether to test the Pipe directly or

within a host Component. Neither solution is significantly easier
or more robust. You will find both solutions in the example
project. In this guide, we will discuss the solution with TestBed
and host Component.

Let us start with the host Component:

const key1 = 'key1';

const key2 = 'key2';

@Component({

template: '{{ key | translate }}',

})

class HostComponent {

public key = key1;

This Component uses the TranslatePipe to translate its key

property. Per default, it is set to key1. There is also a second
constant key2 for testing the key change later.

Let us set up the test suite:

describe('TranslatePipe: with TestBed and HostComponent', () => {

let fixture: ComponentFixture<HostComponent>;

let translateService: Pick<

TranslateService, 'onTranslationChange' | 'get'

>;

beforeEach(async () => {

translateService = {

onTranslationChange: new EventEmitter<Translations>(),

get(key: string): Observable<string> {

return of(`Translation for ${key}`);

},

};

await TestBed.configureTestingModule({

declarations: [TranslatePipe, HostComponent],

providers: [

{ provide: TranslateService, useValue: translateService }

],

}).compileComponents();

translateService = TestBed.inject(TranslateService);

fixture = TestBed.createComponent(HostComponent);

});

/* … */

});

In the testing Module, we declare the Pipe under test and the
HostComponent. For the TranslateService, we provide a fake
object instead. Just like in a Component test, we create the
Component and examine the rendered DOM.

SYNC AND ASYNC TRANSLATION

What needs to be tested? We need to check that {{ key |

translate }} evaluates to Translation for key1. There are
two cases that need to be tested though:

1. The translations are already loaded. The Pipe’s transform

method returns the correct translation synchronously. The
Observable returned by TranslateService’s get emits the
translation and completes immediately.

2. The translations are pending. transform returns null (or an

outdated translation). The Observable completes at any time
later. Then, the change detection is triggered, transform is
called the second time and returns the correct translation.

In the test, we write specs for both scenarios:

it('translates the key, sync service response', /* … */);

it('translates the key, async service response', /* … */);

Let us start with the first case. The spec is straight-forward.

it('translates the key, sync service response', () => {

fixture.detectChanges();

expectContent(fixture, 'Translation for key1');

});

Remember, the TranslateService fake returns an Observable

created with of.

return of(`Translation for ${key}`);

This Observable emits one value and completes immediately.

This mimics the case in which the Service has already loaded the
translations.

We merely need to call detectChanges. Angular calls the Pipe’s

transform method, which calls TranslateService’s get. The
Observable emits the translation right away and transform
passes it through.

Finally, we use the expectContent Component helper to test

the DOM output.

SIMULATE DELAY

Testing the second case is trickier because the Observable needs

to emit asynchronously. There are numerous ways to achieve
this. We will use the RxJS delay operator for simplicity.
At the same time, we are writing an asynchronous spec. That is,
Jasmine needs to wait for the Observable and the expectations
before the spec is finished.

FAKEASYNC AND TICK

Again, there are several ways how to accomplish this. We are

going to use Angular’s fakeAsync and tick functions. We have
introduced them when testing a form with async validators.

A quick recap: fakeAsync freezes time and prevents

asynchronous tasks from being executed. The tick function
then simulates the passage of time, executing the scheduled
tasks.

fakeAsync wraps the function passed to it:

it('translates the key, async service response', fakeAsync(() => {

/* … */

});

Next, we need to change the TranslateService’s get method

to make it asynchronous.

it('translates the key, async service response', fakeAsync(() => {

translateService.get = (key) =>

of(`Async translation for ${key}`).pipe(delay(100));

/* … */

});

DELAY OBSERVABLE
We still use of, but we delay the output by 100 milliseconds. The
exact number does not matter as long as there is some delay
greater or equal 1.

Now, we can call detectChanges for the first time.

it('translates the key, async service response', fakeAsync(() => {

translateService.get = (key) =>

of(`Async translation for ${key}`).pipe(delay(100));

fixture.detectChanges();

/* … */

});

The Pipe’s transform method is called for the first time and
returns null since the Observable does not emit a value
immediately.

So we expect that the output is empty:

it('translates the key, async service response', fakeAsync(() => {

translateService.get = (key) =>

of(`Async translation for ${key}`).pipe(delay(100));

fixture.detectChanges();

expectContent(fixture, '');

/* … */

});

LET TIME PASS

Here comes the interesting part. We want the Observable to

emit a value now. We simulate the passage of 100 milliseconds
with tick(100).
it('translates the key, async service response', fakeAsync(() => {

translateService.get = (key) =>

of(`Async translation for ${key}`).pipe(delay(100));

fixture.detectChanges();

expectContent(fixture, '');

tick(100);

/* … */

});

This causes the Observable to emit the translation and complete.

The Pipe receives the translation and saves it.

To see a change in the DOM, we start a second change

detection. The Pipe’s transform method is called for the second
time and returns the correct translation.

it('translates the key, async service response', fakeAsync(() => {

translateService.get = (key) =>

of(`Async translation for ${key}`).pipe(delay(100));

fixture.detectChanges();

expectContent(fixture, '');

tick(100);

fixture.detectChanges();

expectContent(fixture, 'Async translation for key1');

}));

Testing these details may seem pedantic at first. But the logic in
TranslatePipe exists for a reason.

There are two specs left to write:

it('translates a changed key', /* … */);

it('updates on translation change', /* … */);

The TranslatePipe receives the translation asynchronously

and stores both the key and the translation. When Angular calls
transform with the same key again, the Pipe returns the
translation synchronously. Since the Pipe is marked as impure,
Angular does not cache the transform result.

DIFFERENT KEY

When translate is called with a different key, the Pipe needs to

fetch the new translation. We simulate this case by changing the
HostComponent’s key property from key1 to key2.

it('translates a changed key', () => {

fixture.detectChanges();

fixture.componentInstance.key = key2;

fixture.detectChanges();

expectContent(fixture, 'Translation for key2');

});

After a change detection, the DOM contains the updated

translation for key2.

TRANSLATION CHANGE

Last but no least, the Pipe needs to fetch a new translation from
the TranslateService when the user changes the language
and new translations have been loaded. For this purpose, the
Pipe subscribes to the Service’s onTranslationChange emitter.
Our TranslateService fake supports onTranslationChange
as well, hence we call the emit method to simulate a translation
change. Before, we let the Service return a different translation
in order to see a change in the DOM.

it('updates on translation change', () => {

fixture.detectChanges();

translateService.get = (key) =>

of(`New translation for ${key}`);

translateService.onTranslationChange.emit({});

fixture.detectChanges();

expectContent(fixture, 'New translation for key1');

});

We made it! Writing these specs is challenging without doubt.

TranslateService and TranslatePipe are non-trivial

examples with a proven API. The original classes from ngx-
translate are more powerful. If you look for a robust and flexible
solution, you should use the ngx-translate library directly.

🔗 TranslatePipe: test code

🔗 Angular API reference: fakeAsync
🔗 Angular API reference: tick
🔗 RxJS: delay operator
🔗 ngx-translate
Testing Directives
LEARNING OBJECTIVES

Testing the effect of an Attribute Directive

Testing complex Structural Directives with Inputs and templates
Providing a host Component for testing Attribute and Structural Directives

Angular beginners quickly encounter four core concepts:

Modules, Components, Services and Pipes. A lesser known core
concept are Directives. Without knowing, even beginners are
using Directives, because Directives are everywhere.

In Angular, there are three types of Directives:

1. A Component is a Directive with a template. A Component

typically uses an element type selector, like app-counter.
Angular then looks for app-counter elements and renders
the Component template into these host elements.

2. An Attribute Directive adds logic to an existing host element

in the DOM. Examples for built-in Attribute Directives are
NgClass and NgStyle.

3. A Structural Directive alters the structure of the DOM,

meaning it adds and removes elements programmatically.
Examples for built-in Structural Directives are NgIf, NgFor
and NgSwitch.
We have already tested Components. We have yet to test the two
other types of Directives.

Testing Attribute Directives

The name Attribute Directive comes from the attribute selector,
for example [ngModel]. An Attribute Directive does not have a
template and cannot alter the DOM structure.

We have already mentioned the built-in Attribute Directives

NgClass and NgStyle. In addition, both Template-driven and
Reactive Forms rely heavily on Attribute Directives: NgForm,
NgModel, FormGroupDirective, FormControlName, etc.

STYLING LOGIC

Attributes Directives are often used for changing the style of an

element, either directly with inline styles or indirectly with
classes.

Most styling logic can be implemented using CSS alone, no

JavaScript code is necessary. But sometimes JavaScript is
required to set inline styles or add classes programmatically.

ThresholdWarningDirective
None of our example applications contain an Attribute Directive,
so we are introducing and testing the
ThresholdWarningDirective.

This Directive applies to <input type="number"> elements. It

toggles a class if the picked number exceeds a given threshold. If
the number is higher than the threshold, the field should be
marked visually.

Note that numbers above the threshold are valid input. The
ThresholdWarningDirective does not add a form control
validator. We merely want to warn the user so they check the
input twice.

🔗 ThresholdWarningDirective: Source code

🔗 ThresholdWarningDirective: Run the app
Enter a number greater than 10 to see the effect.

This is the Directive’s code:

import {

Directive, ElementRef, HostBinding, HostListener, Input

} from '@angular/core';

@Directive({

selector: '[appThresholdWarning]',

})

export class ThresholdWarningDirective {

@Input()

public appThresholdWarning: number | null = null;

@HostBinding('class.overThreshold')

public overThreshold = false;

@HostListener('input')

public inputHandler(): void {

this.overThreshold =

this.appThresholdWarning !== null &&

this.elementRef.nativeElement.valueAsNumber >
this.appThresholdWarning;

constructor(private elementRef: ElementRef<HTMLInputElement>) {}

This is how we apply the Directive to an element:

<input type="number" [appThresholdWarning]="10" />

This means: If the user enters a number that is greater than 10,
mark the field with a visual warning.

One bit is missing: the styles for the visual warning.

input[type='number'].overThreshold {

background-color: #fe9;

Before we write the test for the Directive, let us walk through the
implementation parts.

INPUT OF THE SAME NAME

The ThresholdWarningDirective is applied with an attribute
binding [appThresholdWarning]="…". It receives the attribute
value as an Input of the same name. This is how the threshold is
configured.

@Input()

public appThresholdWarning: number | null = null;

INPUT EVENT

Using HostListener, the Directive listens for input event on

the host element. When the user changes the field value, the
inputHandler method is called.

The inputHandler gets the field value and checks whether it is

over the threshold. The result is stored in the overThreshold
boolean property.

@HostListener('input')

public inputHandler(): void {

this.overThreshold =

this.appThresholdWarning !== null &&

this.elementRef.nativeElement.valueAsNumber >
this.appThresholdWarning;

READ VALUE

To access the host element, we use the ElementRef

dependency. ElementRef is a wrapper around the host
element’s DOM node. this.elementRef.nativeElement
yields the input element’s DOM node. valueAsNumber contains
the input value as a number.

TOGGLE CLASS

Last but not least, the overThreshold property is bound to a

class of the same name using HostBinding. This is how the
class is toggled.

@HostBinding('class.overThreshold')

public overThreshold = false;

ThresholdWarningDirective test
Now that we understand what is going on, we need to replicate
the workflow in our test.

HOST COMPONENT

First of all, Attribute and Structural Directives need an existing

host element they are applied to. When testing these Directives,
we use a host Component that renders the host element. For
example, the ThresholdWarningDirective needs an <input
type="number"> host element.

@Component({

template: `

<input type="number"

[appThresholdWarning]="10" />

})

class HostComponent {}

We are going to render this Component. We need a standard

Component test setup using the TestBed.

describe('ThresholdWarningDirective', () => {

let fixture: ComponentFixture<HostComponent>;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [ThresholdWarningDirective, HostComponent],

}).compileComponents();

fixture = TestBed.createComponent(HostComponent);

fixture.detectChanges();

});

/* … */

});

When configuring the testing Module, we declare both the

Directive under test and the host Component. Just like in a
Component test, we render the Component and obtain a
ComponentFixture.

FIND INPUT ELEMENT

In the following specs, we need to access the input element. We

use the standard approach: a data-testid attribute and the
findEl testing helper.
For convenience, we pick the input element in the beforeEach
block. We save it in a shared variable named input.

@Component({

template: `

<input type="number"

[appThresholdWarning]="10"

data-testid="input" />

})

class HostComponent {}

describe('ThresholdWarningDirective', () => {

let fixture: ComponentFixture<HostComponent>;

let input: HTMLInputElement;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [ThresholdWarningDirective, HostComponent],

}).compileComponents();

fixture = TestBed.createComponent(HostComponent);

fixture.detectChanges();

input = findEl(fixture, 'input').nativeElement;

});

/* … */

});

CHECK CLASS
The first spec ensures that the Directive does nothing when the
user has not touched the input. Using the element’s classList, we
expect the class overThreshold to be absent.

it('does not set the class initially', () => {

expect(input.classList.contains('overThreshold')).toBe(false);

});

The next spec enters a number over the threshold. To simulate

the user input, we use our handy testing helper
setFieldValue. Then, the spec expects the class to be present.

it('adds the class if the number is over the threshold', () => {

setFieldValue(fixture, 'input', '11');

fixture.detectChanges();

expect(input.classList.contains('overThreshold')).toBe(true);

});

setFieldValue triggers a fake input event. This triggers the

Directive’s event handler. 11 is greater than the threshold 10, so
the class is added. We still need to call detectChanges so the
DOM is updated.

The last spec makes sure that the threshold is still considered as
a safe value. No warning should be shown.

it('removes the class if the number is at the threshold', () => {

setFieldValue(fixture, 'input', '10');

fixture.detectChanges();

expect(input.classList.contains('overThreshold')).toBe(false);

});

This is it! Testing the ThresholdWarningDirective is like

testing a Component. The difference is that the Component
serves as a host for the Directive.

The full spec for the ThresholdWarningDirective looks like

this:

import { Component } from '@angular/core';

import { async, ComponentFixture, TestBed } from

'@angular/core/testing';

import { findEl, setFieldValue } from './spec-helpers/element.spec-

helper';

import { ThresholdWarningDirective } from './threshold-

warning.directive';

@Component({

template: `

<input type="number"

[appThresholdWarning]="10"

data-testid="input" />

})

class HostComponent {}

describe('ThresholdWarningDirective', () => {

let fixture: ComponentFixture<HostComponent>;

let input: HTMLInputElement;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [ThresholdWarningDirective, HostComponent],

}).compileComponents();

fixture = TestBed.createComponent(HostComponent);

fixture.detectChanges();

input = findEl(fixture, 'input').nativeElement;

});

it('does not set the class initially', () => {

expect(input.classList.contains('overThreshold')).toBe(false);

});

it('adds the class if the number is over the threshold', () => {

setFieldValue(fixture, 'input', '11');

fixture.detectChanges();

expect(input.classList.contains('overThreshold')).toBe(true);

});

it('removes the class if the number is at the threshold', () => {

setFieldValue(fixture, 'input', '10');

fixture.detectChanges();

expect(input.classList.contains('overThreshold')).toBe(false);

});

});

🔗 ThresholdWarningDirective: implementation code

🔗 ThresholdWarningDirective: test code

Testing Structural Directives

A Structural Directive does not have a template like a
Component, but operates on an internal ng-template. The
Directive renders the template into the DOM programmatically,
passing context data to the template.

RENDER TEMPLATE PROGRAMMATICALLY

The prime examples emonstrate what Structural Directives are

capable of:

The NgIf Directive decides whether the template is rendered

or not.

The NgFor Directive walks over a list of items and renders the
template repeatedly for each item.

A Structural Directive uses an attribute selector, like [ngIf]. The

attribute is applied to a host element with the special asterisk
syntax, for example *ngIf. Internally, this is translated to <ng-
template [ngIf]="…"> … </ng-template>.

This guide assumes that you roughly understand how Structural

Directives work and how the microsyntax translates to Directive
Inputs. Please refer to the comprehensive official guide on
Structural Directives.

PaginateDirective
We are introducing and testing the PaginateDirective, a
complex Structural Directive.

NGFOR WITH PAGINATION

PaginateDirective works similar to NgFor, but does not

render all list items at once. It spreads the items over pages,
usually called pagination.

Per default, only ten items are rendered. The user can turn the
pages by clicking on “next” or “previous” buttons.

🔗 PaginateDirective: Source code

🔗 PaginateDirective: Run the app
Before writing the test, we need to understand the outer
structure of PaginateDirective first.

The simplest use of the Directive looks like this:

<ul>

<li *appPaginate="let item of items">

{{ item }}

</li>

</ul>

This is similar to the NgFor directive. Assuming that items is an

array of numbers ([1, 2, 3, …]), the example above renders
the first 10 numbers in the array.
The asterisk syntax *appPaginate and the so-called microsyntax
let item of items is syntactic sugar. This is a shorter and
nicer way to write something complex. Internally, Angular
translates the code to the following:

<ng-template appPaginate let-item [appPaginateOf]="items">

<li>

{{ item }}

</li>

</ng-template>

There is an ng-template with an attribute appPaginate and an

attribute binding appPaginateOf. Also there is a template input
variable called item.

RENDER TEMPLATE FOR EACH ITEM

As mentioned, a Structural Directive does not have its own

template, but operates on an ng-template and renders it
programmatically. Our PaginateDirective works with the ng-
template shown above. The Directive renders the template for
each item on the current page.

Now that we have seen Angular’s internal representation, we can

understand the structure of the PaginateDirective class:

@Directive({

selector: '[appPaginate]',

})

export class PaginateDirective<T> implements OnChanges {

@Input()

public appPaginateOf: T[] = [];

/* … */

The Directive uses the [appPaginate] attribute selector and

has an Input called appPaginateOf. By writing the microsyntax
*appPaginate="let item of items", we actually set the
appPaginateOf Input to the value items.

DIRECTIVE INPUTS

The PaginateDirective has a configuration option named

perPage. It specifies how many items are visible per page.

Per default, there are ten items on a page. To change it, we set
perPage: … in the microsyntax:

<ul>

<li *appPaginate="let item of items; perPage: 5">

{{ item }}

</li>

</ul>

This translates to:

<ng-template

appPaginate

let-item

[appPaginateOf]="items"

[appPaginatePerPage]="5">

<li>

{{ item }}

</li>

</ng-template>

perPage translates to an Input named appPaginatePerPage in

the Directive’s code:

@Directive({

selector: '[appPaginate]',

})

export class PaginateDirective<T> implements OnChanges {

@Input()

public appPaginateOf: T[] = [];

@Input()

public appPaginatePerPage = 10;

/* … */

This is how built-in Structural Directives like NgIf and NgFor

work as well.

Now it gets more complicated. Since we want to paginate the

items, we need user controls to turn the pages – in addition to
rendering the items.

Again, a Structural Directive lacks a template.

PaginateDirective cannot render the “next” and “previous”
buttons itself. And to remain flexible, it should not render
specific markup. The Component that uses the Directive should
decide how the controls look.

PASS ANOTHER TEMPLATE

We solve this by passing the controls as a template to the

Directive. In particular, we pass a reference to a separate ng-
template. This will be the second template the Directive
operates on.

This is how the controls template could look like:

<ng-template

#controls

let-previousPage="previousPage"

let-page="page"

let-pages="pages"

let-nextPage="nextPage"

>

<button (click)="previousPage()">

Previous page

</button>

{{ page }} / {{ pages }}

<button (click)="nextPage()">

Next page

</button>

</ng-template>

#controls sets a template reference variable. This means we

can further reference the template by the name controls.

CONTEXT OBJECT
The Directive renders the controls template with a context object
that implements the following TypeScript interface:

interface ControlsContext {

page: number;

pages: number;

previousPage(): void;

nextPage(): void;

page is the current page number. pages is the total number of

pages. previousPage and nextPage are functions for turning
the pages.

USE PROPERTIES FROM CONTEXT

The ng-template takes these properties from the context and

saves them in local variables of the same name:

let-previousPage="previousPage"

let-page="page"

let-pages="pages"

let-nextPage="nextPage"

This means: Take the context property previousPage and make

it available in the template under the name previousPage. And
so on.

The content of the template is rather simple. It renders two

buttons for the page turning, using the functions as click
handlers. It outputs the current page number and the number of
total pages.

<button (click)="previousPage()">

Previous page

</button>

{{ page }} / {{ pages }}

<button (click)="nextPage()">

Next page

</button>

Last but not least, we pass the template to the

PaginateDirective using the microsyntax:

<ul>

<li *appPaginate="let item of items; perPage: 5; controls:

controls">

{{ item }}

</li>

</ul>

This translates to:

<ng-template

appPaginate

let-item

[appPaginateOf]="items"

[appPaginatePerPage]="5"

[appPaginateControls]="controls">

<li>

{{ item }}

</li>

</ng-template>

controls: … in the microsyntax translates to an Input named

appPaginateControls. This concludes the Directive‘s outer
structure:

@Directive({

selector: '[appPaginate]',

})

export class PaginateDirective<T> implements OnChanges {

@Input()

public appPaginateOf: T[] = [];

@Input()

public appPaginatePerPage = 10;

@Input()

public appPaginateControls?: TemplateRef<ControlsContext>;

/* … */

The inner workings of the PaginateDirective are not relevant

for testing, so we will not discuss them in detail here. Please
refer to the Angular guide Write a structural directive for a
general explanation.

🔗 PaginateDirective: implementation code

PaginateDirective test
We have explored all features of PaginateDirective and are
now ready to test them!

HOST COMPONENT

First, we need a host Component that applies the Structural

Directive under test. We let it render a list of ten numbers, three
numbers on each page.

const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

@Component({

template: `

<ul>

<li

*appPaginate="let item of items; perPage: 3"

data-testid="item"

>

{{ item }}

</li>

</ul>

`,

})

class HostComponent {

public items = items;

CONTROLS TEMPLATE

Since we also want to test the custom controls feature, we need

to pass a controls template. We will use the simple controls
discussed above.
const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

@Component({

template: `

<ul>

<li

*appPaginate="let item of items; perPage: 3; controls:

controls"

data-testid="item"

>

{{ item }}

</li>

</ul>

<ng-template

#controls

let-previousPage="previousPage"

let-page="page"

let-pages="pages"

let-nextPage="nextPage"

>

<button

(click)="previousPage()"

data-testid="previousPage">

Previous page

</button>

<span data-testid="page">{{ page }}</span>

<span data-testid="pages">{{ pages }}</span>

<button

(click)="nextPage()"

data-testid="nextPage">

Next page

</button>

</ng-template>

`,

})

class HostComponent {

public items = items;

The template code already contains data-testid attributes.

This is how we find and examine the elements in the test (see
Querying the DOM with test ids).

This is quite a setup, but after all, we want to test the

PaginateDirective under realistic conditions.

The test suite configures a testing Module, declares both the

HostComponent and the PaginateDirective and renders the
HostComponent:

describe('PaginateDirective', () => {

let fixture: ComponentFixture<HostComponent>;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [PaginateDirective, HostComponent],

}).compileComponents();

fixture = TestBed.createComponent(HostComponent);

fixture.detectChanges();

});

/* … */

});

This is a standard Component test setup – nothing special yet.

The first spec verifies that the Directive renders the items on the
first page, in our case the numbers 1, 2 and 3.

We have marked the item element with data-testid="item".

We use the findEls test helper to find all elements with said
test id.

EXPECT RENDERED ITEMS

We expect to find three items. Then we examine the text content

of each item and expect that it matches the item in the number
list, respectively.

it('renders the items of the first page', () => {

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expect(els[0].nativeElement.textContent.trim()).toBe('1');

expect(els[1].nativeElement.textContent.trim()).toBe('2');

expect(els[2].nativeElement.textContent.trim()).toBe('3');

});

Already, the expectations are repetitive and hard to read. So we

introduce a little helper function.

function expectItems(

elements: DebugElement[],

expectedItems: number[],

): void {

elements.forEach((element, index) => {

const actualText = element.nativeElement.textContent.trim();

expect(actualText).toBe(String(expectedItems[index]));

});

This lets us rewrite the spec so it is easier to grasp:

it('renders the items of the first page', () => {

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expectItems(els, [1, 2, 3]);

});

CHECK CONTROLS

The next spec proves that the controls template is rendered

passing the current page and the total number of pages.

The elements have have a data-testid="page" and data-

testid="pages", respectively. We use the expectText testing
helper to check their text content.

it('renders the current page and total pages', () => {

expectText(fixture, 'page', '1');

expectText(fixture, 'pages', '4');

});

Three more specs deal with the controls for turning pages. Let
us start with the “next” button.

it('shows the next page', () => {

click(fixture, 'nextPage');

fixture.detectChanges();

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expectItems(els, [4, 5, 6]);

});

TURN PAGES

We simulate a click on the “next” button using the click testing

helper. Then we start Angular’s change detection so the
Component together with the Directive are re-rendered.

Finally, we verify that the Directive has rendered the next three
items, the numbers 4, 5 and 6.

The spec for the “previous” button looks similar. First, we jump to
the second page, then back to the first page.

it('shows the previous page', () => {

click(fixture, 'nextPage');

click(fixture, 'previousPage');

fixture.detectChanges();

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expectItems(els, [1, 2, 3]);

});

STRESS TEST

We have now covered the Directive’s important behavior. Time

for testing edge cases! Does the Directive behave correctly if we
click on the “previous” button on the first page and the “next”
button on the last page?

it('checks the pages bounds', () => {

click(fixture, 'nextPage'); // -> 2

click(fixture, 'nextPage'); // -> 3

click(fixture, 'nextPage'); // -> 4

click(fixture, 'nextPage'); // -> 4

click(fixture, 'previousPage'); // -> 3

click(fixture, 'previousPage'); // -> 2

click(fixture, 'previousPage'); // -> 1

click(fixture, 'previousPage'); // -> 1

fixture.detectChanges();

// Expect that the first page is visible again

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expectItems(els, [1, 2, 3]);

});

By clicking on the buttons, we jump forward to the last page and

backward to the first page again.

This is it! Here is the full test code:

import { Component, DebugElement } from '@angular/core';

import { async, ComponentFixture, TestBed } from

'@angular/core/testing';

import {

findEls,

expectText,

click,

} from './spec-helpers/element.spec-helper';

import { PaginateDirective } from './paginate.directive';

const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

@Component({

template: `

<ul>

<li

*appPaginate="let item of items; perPage: 3; controls:

controls"

data-testid="item"

>

{{ item }}

</li>

</ul>

<ng-template

#controls

let-previousPage="previousPage"

let-page="page"

let-pages="pages"

let-nextPage="nextPage"

>

<button (click)="previousPage()" data-testid="previousPage">

Previous page

</button>

<span data-testid="page">{{ page }}</span>

<span data-testid="pages">{{ pages }}</span>

<button (click)="nextPage()" data-testid="nextPage">

Next page

</button>

</ng-template>

`,

})

class HostComponent {

public items = items;

function expectItems(

elements: DebugElement[],

expectedItems: number[],

): void {

elements.forEach((element, index) => {

const actualText = element.nativeElement.textContent.trim();

expect(actualText).toBe(String(expectedItems[index]));

});

describe('PaginateDirective', () => {

let fixture: ComponentFixture<HostComponent>;

beforeEach(async () => {

await TestBed.configureTestingModule({

declarations: [PaginateDirective, HostComponent],

}).compileComponents();

fixture = TestBed.createComponent(HostComponent);

fixture.detectChanges();

});

it('renders the items of the first page', () => {

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expectItems(els, [1, 2, 3]);

});

it('renders the current page and total pages', () => {

expectText(fixture, 'page', '1');

expectText(fixture, 'pages', '4');

});

it('shows the next page', () => {

click(fixture, 'nextPage');

fixture.detectChanges();

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expectItems(els, [4, 5, 6]);

});

it('shows the previous page', () => {

click(fixture, 'nextPage');

click(fixture, 'previousPage');

fixture.detectChanges();

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expectItems(els, [1, 2, 3]);

});

it('checks the pages bounds', () => {

click(fixture, 'nextPage'); // -> 2

click(fixture, 'nextPage'); // -> 3

click(fixture, 'nextPage'); // -> 4

click(fixture, 'previousPage'); // -> 3

click(fixture, 'previousPage'); // -> 2

click(fixture, 'previousPage'); // -> 1

fixture.detectChanges();

// Expect that the first page is visible again

const els = findEls(fixture, 'item');

expect(els.length).toBe(3);

expectItems(els, [1, 2, 3]);

});

});

PaginateDirective is a complex Structural Directive that

requires a complex test setup. Once we have created a suitable
host Component, we can test it using our familiar testing
helpers. The fact that the logic resides in the Directive is not
relevant for the specs.

🔗 PaginateDirective: implementation code

🔗 PaginateDirective: test code
Testing Modules
LEARNING OBJECTIVES

Deciding whether and how to test Angular Modules

Writing smoke tests to catch Module errors early

Modules are central parts of Angular applications. Often they

contain important setup code. Yet they are hard to test since
there is no typical logic, only sophisticated configuration.

ONLY METADATA

Angular Modules are classes, but most of the time, the class
itself is empty. The essence lies in the metadata set with
@NgModule({ … }).

We could sneak into the metadata and check whether certain

Services are provided, whether third-party Modules are imported
and whether Components are exported.

But such a test would simply mirror the implementation. Code

duplication does not give you more confidence, it only increases
the cost of change.

Should we write tests for Modules at all? If there is a reference

error in the Module, the compilation step (ng build) fails before
the automated tests scrutinize the build. “Failing fast” is good
from a software quality perspective.
SMOKE TEST

There are certain Module errors that only surface during

runtime. These can be caught with a smoke test. Given this
Module:

import { NgModule } from '@angular/core';

import { CommonModule } from '@angular/common';

import { ExampleComponent } from './example.component';

@NgModule({

declarations: [ExampleComponent],

imports: [CommonModule],

})

export class FeatureModule {}

We write this smoke test:

import { TestBed } from '@angular/core/testing';

import { FeatureModule } from './example.module';

describe('FeatureModule', () => {

beforeEach(() => {

TestBed.configureTestingModule({

imports: [FeatureModule],

});

});

it('initializes', () => {

const module = TestBed.inject(FeatureModule);

expect(module).toBeTruthy();

});

});

The integration test uses the TestBed to import the Module

under test. It verifies that no error occurs when importing the
Module.
Measuring code coverage
LEARNING OBJECTIVES

Understanding the code coverage metric

Generating and inspecting a code coverage report
Finding code that is not yet covered by automated tests
Enforcing code coverage thresholds and improving code coverage

Code coverage, also called test coverage, tells you which parts of
your code are executed by running the unit and integration
tests. Code coverage is typically expressed as percent values, for
example, 79% statements, 53% branches, 74% functions, 78%
lines.

Statements are, broadly speaking, control structures like if and

for as well as expressions separated by semicolon. Branches
refers to the two branches of if (…) {…} else {…} and … ?
… : … conditions. Functions and lines are self-explanatory.

Coverage report
In Angular’s Karma and Jasmine setup, Istanbul is used for
measuring test coverage. Istanbul rewrites the code under test
to record whether a statement, branch, function and line was
called. Then it produces a comprehensive test report.
To activate Istanbul when running the tests, add the --code-
coverage parameter:

ng test --code-coverage

After the tests have completed, Istanbul saves the report in the
coverage directory located in the Angular project directory.

The report is a bunch of HTML files you can open with a browser.
Start by opening coverage/index.html in the browser of your
choice.

The report for the Flickr search example looks like this:
Istanbul creates an HTML page for every directory and every file.
By following the links, you can descend to reports for the
individual files.

For example, the coverage report for photo-item.component.ts

of the Flickr search:

The report renders the source code annotated with the

information how many times a line was called. In the example
above, the code is fully covered except for an irrelevant else
branch, marked with an “E”.

The spec it('focusses a photo on click', () => {…})

clicks on the photo item to test whether the focusPhoto Output
emits. Let us disable the spec on purpose to see the impact.

You can tell from the coverage report above that the
handleClick method is never called. A key Component
behavior is untested.
How to use the coverage report
Now that we know how to generate the report, what should we
do with it?

In the chapter The right amount of testing, we have identified

code coverage as a useful, but flawed metric. As a quantitative
measure, code coverage cannot assess the quality of your tests.

Software testing is not a competition. We should not try to reach

a particular score just for the sake of it. For what purpose are we
measuring code coverage then?

FIND UNCOVERED CODE

The coverage report is a valuable tool you should use while

writing tests. It reveals code behavior that is not yet tested. The
report not only guides your testing, it also deepens your
understanding of how your tests work.

Whatever your current coverage score is, use the reporting to

monitor and improve your testing practice. As described in
Tailoring your testing approach, testing should be part of the
development routine. New features should include tests, bug
fixes should include a test as proof and to prevent regressions.

IMPROVE COVERAGE
Writing new code and changing existing code should not lower
the coverage score, but gradually increase it. This means if your
existing tests cover 75% lines of code, new code needs to be at
least 75% covered. Otherwise the score slowly deteriorates.

It is common practice to run the unit and integration tests in a

continuous integration environment and measure the code
coverage. To enforce a certain coverage score and to prevent
decline, you can configure thresholds in the Karma
configuration.

In karma.conf.js, you can add global thresholds for

statements, branches, functions and lines.

coverageReporter: {

/* … */

check: {

global: {

statements: 75,

branches: 75,

functions: 75,

lines: 75,

},

},

},

In the configuration above, all values are set to 75%. If the

coverage drops below that number, the test execution fails even
if all specs succeeded.
RAISE THE BAR

When new code is added to the project with a test coverage

better than average, you can raise the thresholds slowly but
steadily – for example, from 75 to 75.1, 75.2, 75.3 and so on.
Soon these small improvements add up.

Test coverage should not be a pointless competition that puts

developers under pressure and shames those that do not meet
an arbitrary mark. Measuring coverage is a tool you should use
for your benefit. Keep in mind that writing meaningful, spot-on
tests does not necessarily increase the coverage score.

For beginners and experts alike, the coverage report helps to set
up, debug and improve their tests. For experienced developers,
the score helps to keep up a steady testing practice.

🔗 karma-coverage Configuration
End-to-end testing
LEARNING OBJECTIVES

Writing valueable tests that cover all parts of your application

Understanding different approaches to end-to-end testing
Setting up Cypress for testing your Angular project
Orchestrating a web browser to load and inspect your application
Intercepting API calls to return fixed data

We have successfully written unit and integration tests using

Karma, Jasmine and Angular’s own testing tools. These precise
tests give confidence that a single application part – like a
Component or Service - or a group of connected parts work as
intended.

USER PERSPECTIVE

Karma and Jasmine tests take a technical perspective. They focus

on the front-end JavaScript code alone and run it in a controlled
and isolated test environment. What is really important though
is whether the whole application works for the user.

The most effective and reliable way to ensure a working

application is manual testing: A dedicated software tester walks
through the application feature by feature, case by case
according to a test plan.
Manual tests are slow, labor-intensive and cannot be repeated
often. They are unspecific from a developer perspective: If the
test fails, we cannot easily pin down which part of the application
is responsible or which code change causes the regression.

We need automated tests that take the user’s perspective. This is

what end-to-end (E2E) tests do.

Strengths of end-to-end tests

As discussed in distribution of testing efforts, all types of
automated tests have pros and cons. Unit and integration tests
are fast and reliable, but do not guarantee a working application.
End-to-end test are slow and often fail incorrectly, but they
assess the fitness of the application as a whole.

REAL CONDITIONS

When all parts of the application come together, a new type of

bug appears. Often these bugs have to do with timing and order
of events, like network latency and race conditions.

The unit and integration tests we wrote worked with a fake back-
end. We send fake HTTP requests and respond with fake data.
We made an effort to keep the originals and fakes on par.

FRONT-END AND BACK-END

It is much harder to keep the front-end code in sync with the
actual API endpoints and responses from the back-end. Even if
the front-end and the back-end share type information about the
transferred data, there will be mismatches.

It is the goal of end-to-end tests to catch these bugs that cannot

be caught by other automated tests.

Deployment for end-to-end tests

End-to-end tests require a testing environment that closely
resembles the production environment. You need to deploy the
full application, including the front-end and the relevant back-
end parts. For that purpose, back-end frameworks typically
support configurations for different environments, like
development, testing and production.

DETERMINISTIC ENVIRONMENT

The database needs to be filled with pre-fabricated fake data.

With each run of the end-to-end tests, you need to reset the
database to a defined initial state.

The back-end services need to answer requests with

deterministic responses. Third-party dependencies need to be
set up so they return realistic data but do not compromise
production data.

Since this guide is not about DevOps, we will not go into details
here and focus on writing end-to-end tests.

How end-to-end tests work

An end-to-end test mimics how a user interacts with the
application. Typically, the test engine launches an ordinary
browser and controls it remotely.

SIMULATE USER ACTIONS

Once the browser is started, the end-to-end test navigates to the

application’s URL, reads the page content and makes keyboard
and pointer input. For example, the test fills out a form and clicks
on the submit button.

Just like unit and integration tests, the end-to-end test then
makes expectations: Does the page include the right content?
Did the URL change? This way, whole features and user
interfaces are examined.

End-to-end testing frameworks

Frameworks for end-to-end tests allow navigating to URLs,
simulating user input and inspecting the page content. Apart
from that, they have little in common. The test syntax and the
way the tests are run differ widely.

There are two categories of end-to-end testing frameworks:

Those that use WebDriver and those that do not.

BROWSER AUTOMATION

The WebDriver protocol defines a way to control a browser

remotely with a set of commands. It originates from the
Selenium browser automation project and is now developed at
the World Wide Web Consortium (W3C).

All common browsers support the WebDriver protocol and can

be controlled remotely. The most important WebDriver
commands are:

Navigate to a given URL

Find one or more elements in the DOM

Get information about a found element:

Get an element attribute or property

Get the element’s text content

Click on an element

Send keyboard input to a form field

Execute arbitrary JavaScript code

WebDriver is a key technology most end-to-end testing

frameworks depend on. The main benefit of WebDriver is that
tests can be run in different browsers, even simultaneously.

WebDriver is a high-level, generic, HTTP-based protocol. It

connects the test running on one machine with a browser
possibly running on another machine. The level of control over
the browser is limited.

FLEXIBILITY VS. RELIABILITY

Not all frameworks build on WebDriver. Some frameworks

integrate more directly into the browser. This makes them more
reliable, less complex, but also less flexible since they only
support few browsers.

In this guide, we will learn about two frameworks, one of each

category:

Protractor, which is based on WebDriver,

Cypress, which does not use WebDriver.

🔗 WebDriver protocol
🔗 Protractor: Official web site
🔗 Cypress: Official web site

Introducing Protractor
Protractor is an end-to-end testing framework based on
WebDriver, made for Angular applications. Like the Angular
framework itself, Protractor originates from Google.

DEPRECATED

Up until Angular version 12, Protractor was the default end-to-

end testing framework in projects created with Angular CLI.
Since Angular 12, Protractor is deprecated. In new CLI projects,
there is no default end-to-end testing solution configured.

The main reason for Protractor’s deprecation is that it was not

maintained for years. During that time, new browser automation
standards and better end-to-end testing frameworks emerged.

Protractor has two outstanding features designed for testing

Angular applications. But as we will learn, you cannot benefit
from these optimizations any longer.

ANGULAR-SPECIFIC FEATURES

First, Protractor hooks into the Angular app under tests. After
sending a WebDriver command, Protractor waits for Angular to
update the page. Then it continues with the next command. By
synchronizing the test and the application, the test gets faster
and more reliable.

Second, Protractor has a feature called control flow. While

WebDriver commands are asynchronous by nature, the control
flow allows you to write tests as if they ran synchronously.

Protractor’s control flow implementation led to inconsistencies

and bugs. The underlying WebDriverJS library removed the
feature, so Protractor had to deprecate it as well. This means you
need to use async / await to explicitly wait for a command to
finish.

As a result, Protractor lost a useful feature. Protractor’s

contenders, namely Cypress and WebDriver.io, still allow to write
asynchronous test code in a synchronous manner.

Without the control flow, you practically need to disable the “wait
for Angular” feature as well. This means both key Protractor
features have lapsed.

NOT RECOMMENDED

In view of these events, this guide recommends against using

Protractor for new projects. Protractor is a solid project, but
today there is no compelling reason to choose Protractor over its
competitors.
TESTED WITH PROTRACTOR

If you are looking for Protractor examples, have a look at the

Protractor end-to-end tests for the Counter and Flickr search.
They are not explained in this guide though.

🔗 Counter: End-to-end tests with Protractor

🔗 Flickr search: End-to-end tests with Protractor

Introducing Cypress
Cypress is an end-to-end testing framework that is not based on
WebDriver. There are no Angular-specific features. Any web site
can be tested with Cypress.

REPRODUCIBLE TESTS

WebDriver-based testing solutions are flexible and powerful but

turned out to be slow and unreliable. Cypress aims to improve
both the developing experience and the reliability of end-to-end
tests.

Cypress employs a fundamentally different architecture. A

Node.js application starts the browser. The browser is not
controlled remotely, but the tests run directly in the browser,
supported by a browser plugin.
The test runner provides a powerful user interface for inspecting
and debugging tests right in the browser.

TEST RUNNER

Cypress is the product of one company, Cypress.io, Inc. The test

runner we are going to use is open source and free of charge.

The company generates revenue with an additional paid service:

The Cypress dashboard manages test runs recorded in a
continuous integration environment. You do not have to
subscribe to this service to write and run Cypress tests.

TRADE-OFFS

From our perspective, Cypress has a few drawbacks.

In place of Jasmine, Cypress uses the Mocha and Chai

libraries for writing tests. While both serve the same purpose,
you have to learn the subtle differences. If you use Jasmine
for unit and integration tests, there will be an inconsistency in
your tests.

Cypress only supports Firefox as well as Chromium-based

browsers like Google Chrome and Microsoft Edge. It does not
support Safari, legacy Edge or even Internet Explorer.

Cypress is not simply better than WebDriver-based frameworks.

It tries to solve their problems by narrowing the scope and by
making trade-offs.

RECOMMENDED

That being said, this guide recommends to use Cypress for

testing Angular applications. Cypress is well-maintained and
well-documented. With Cypress, you can write valuable end-to-
end tests with little effort.

In case you do need a WebDriver-based framework, have a look

at Webdriver.io instead.

🔗 Cypress: Trade-offs
🔗 Cypress: Key differences
🔗 Webdriver.io

Installing Cypress
An easy way to add Cypress to an existing Angular CLI project is
the Cypress Angular Schematic.

In your Angular project directory, run this shell command:

ng add @cypress/schematic

This command does four important things:

1. Add Cypress and auxiliary npm packages to package.json.

2. Add the Cypress configuration file cypress.config.ts.

3. Change the angular.json configuration file in order to add

ng run commands.

4. Create a sub-directory named cypress with a scaffold for

your tests.

The output looks like this:

ℹ Using package manager: npm

✔ Found compatible package version: @cypress/[email protected].

✔ Package information loaded.

The package @cypress/[email protected] will be installed and

executed.

Would you like to proceed? Yes

✔ Packages successfully installed.

? Would you like the default `ng e2e` command to use Cypress? [
Protractor to Cypress Migration Guide:

https://on.cypress.io/protractor-to-cypress?cli=true ] Yes

CREATE cypress.config.ts (127 bytes)

CREATE cypress/tsconfig.json (139 bytes)

CREATE cypress/e2e/spec.cy.ts (143 bytes)

CREATE cypress/fixtures/example.json (85 bytes)

CREATE cypress/support/commands.ts (1377 bytes)

CREATE cypress/support/e2e.ts (655 bytes)

UPDATE package.json (1187 bytes)

UPDATE angular.json (3757 bytes)

✔ Packages installed successfully.

The installer asks if you would like the ng e2e command to start
Cypress. If you are setting up a new project without end-to-end
tests yet, it is safe to answer “Yes”.

In Angular CLI prior to version 12, ng e2e used to start

Protractor. If you have any legacy Protractor tests in the project
and want to continue to run them using ng e2e, answer “No” to
the question.

Writing an end-to-end test with

Cypress
In the project directory, you will find a sub-directory called
cypress. It contains:

A tsconfig.json configuration for all TypeScript files

specifically in this directory,

an e2e directory for the end-to-end tests,

a support directory for custom commands and other testing

helpers,

a fixtures directory for test data.

The test files reside in the e2e directory. Each test is TypeScript
file with the extension .cy.ts.

The tests itself are structured with the test framework Mocha.
The assertions (also called expectations) are written using Chai.

Mocha and Chai is a popular combination. They roughly do the

same as Jasmine, but are much more flexible and rich in
features.

TEST SUITES

If you have written unit tests with Jasmine before, the Mocha
structure will be familiar to you. A test file contains one or more
suites declared with describe('…', () => { /* … */}).
Typically, one file contains one describe block, possible with
nested describe blocks.

Inside describe, the blocks beforeEach, afterEach,

beforeAll, afterAll and it can be used similar to Jasmine
tests.

This brings us to the following end-to-end test structure:

describe('… Feature description …', () => {

beforeEach(() => {

// Navigate to the page

});

it('… User interaction description …', () => {

// Interact with the page

// Assert something about the page content

});

});

Testing the counter Component

Step by step, we are going to write end-to-end tests for the
counter example application.

🔗 Counter Component: Source code

🔗 Counter Component: Run the app
As a start, let us write a minimal test that checks the document
title. In the project directory, we create a file called
cypress/e2e/counter.cy.ts. It looks like this:

describe('Counter', () => {

beforeEach(() => {

cy.visit('/');

});

it('has the correct title', () => {

cy.title().should('equal', 'Angular Workshop: Counters');

});

});

COMMANDS
Cypress commands are methods of the cy namespace object.
Here, we are using two commands, visit and title.

cy.visit orders the browser to visit the given URL. Above, we

use the path /. Cypress appends the path to the baseUrl. Per
default, the baseUrl is set to http://localhost:4200 in
Cypress’ configuration file, cypress.config.ts.

CHAINERS

cy.title returns the page title. To be specific, it returns a

Cypress Chainer. This is an asynchronous wrapper around an
arbitrary value. Most of the time, a Chainer wraps DOM
elements. In the case, cy.title wraps a string.

ASSERTIONS

The Chainer has a should method for creating an assertion.

Cypress relays the call to the Chai library to verify the assertion.

cy.title().should('equal', 'Angular Workshop: Counters');

We pass two parameters, 'equal' and the expected title string.

equal creates an assertion that the subject value (the page title)
equals to the given value ('Angular Workshop: Counters').
equal uses the familiar === comparison.

This should style of assertions differs from Jasmine

expectations, which use the expect(…).toBe(…) style. In fact,
Chai supports three different assertion styles: should, assert,
but also expect. In Cypress you will typically use should on
Chainers and expect on unwrapped values.

🔗 Cypress API reference: cy.visit

🔗 Cypress API reference: cy.title
🔗 Cypress documentation: Assertions
🔗 Chai API reference: should style assertions
🔗 Chai API reference: equal

Running the Cypress tests

Save the minimal test from the last chapter as
cypress/e2e/counter.cy.ts.

Cypress has two shell commands to run the end-to-end tests:

TEST RUNNER

npx cypress run – Non-interactive test runner. Runs the

tests in a “headless” browser. This means the browser window
is not visible.

The tests are run once, then the browser is closed and the
shell command finishes. You can see the test results in the
shell output.
This command is typically used in a continuous integration
environment.

npx cypress open – Interactive test runner. Opens a

window where you can select which browser to use and
which tests to run. The browser window is visible and it
remains visible after completion.

You can see the test results the browser window. If you make
changes on the test files, Cypress automatically re-runs the
tests.

This command is typically used in the development

environment.

SERVE AND RUN TESTS

The Cypress schematic that we have installed wraps these

commands so they integrate well with Angular.

ng run $project-name$:cypress-run – Starts the non-

interactive test runner.

ng run $project-name$:cypress-open – Starts the

interactive test runner.

$project-name$ is a placeholder. Insert the name of the

respective Angular project. This is typically the same as the
directory name. If not, it can be found in angular.json in the
projects object.

For example, the Counter example has the project name

angular-workshop. Hence, the commands read:

ng run angular-workshop:cypress-run

ng run angular-workshop:cypress-open

Whatever method of starting Cypress you use, you need to start

Angular’s development server with ng serve in a separate shell
first. Cypress tries to connect to the baseUrl
(http://localhost:4200) and will let you know if the server is
not reachable.

LAUNCH WINDOW

The cypress open command will open the test runner. First,
you need to choose the type of testing, which is “E2E testing” in
our case.
On the next screen, you need to choose the browser for running
the tests.
Cypress automatically lists all browsers it finds on your system.
In addition, you can run your tests in Electron. Cypress’ user
interface is an Electron application. Electron is based on
Chromium, the open source foundation of the Chrome browser.

Select a browser and click on the “Start E2E Testing” button. This
launches the browser and opens the test runner, Cypress’
primary user interface. (The screenshot shows Chrome.)
In the main window pane, all tests are listed. To run a single test,
click on it.

TEST RUNNER

Suppose you run the tests in Chrome and run the test
counter.cy.ts, the in-browser test runner looks like this:
In the “Specs” column, the tests of this test run are listed. For
each test, you can see the specs.

On the right side, the web page under test is seen. The web page
is scaled to fit into the window, but uses a default viewport width
of 1000 pixels.

SPEC LOG

By clicking on a spec name, you can see all commands and

assertions in the spec.
You can watch Cypress running the specs command by
command. This is especially useful when a spec fails. Let us
break the spec on purpose to see Cypress’ output.

cy.title().should('equal', 'Fluffy Golden Retrievers');

This change leads to a failing spec:

Cypress provides a helpful error message, pointing to the
assertion that failed. You can click on the file name with line and
column, cypress/e2e/counter.cy.ts:7:16 in the example,
to jump right to the assertion in your code editor.

TIME TRAVEL

A unique feature of the in-browser test runner is the ability to

see the state of the page at a certain point in time. Cypress
creates DOM snapshot whenever a command is run or an
assertion verified.

By hovering over a command or assertion, you can travel back in

time. The page on the right side then reflects the page when the
command or assertion was processed.

The time travel feature is invaluable when writing and

debugging end-to-end tests. Use it to understand how your test
interacts with the application and how the application reacts.
When a test fails, use it to reconstruct what circumstances lead
to the failure.

🔗 Cypress documentation: The Test Runner

Asynchronous tests
Every Cypress command takes some time to execute. But from
the spec point of view, the execution happens instantly.

COMMAND QUEUE

In fact, Cypress commands are merely declarative. The execution

happens asynchronously. By calling cy.visit and cy.title,
we add commands to a queue. The queue is processed later.

As a consequence, we do not need to wait for the result of

cy.visit. Cypress automatically waits for the page to load
before proceeding with the next command.

For the same reason, cy.title does not immediately return a

string, but a Chainer that allows more declarations.
In the Jasmine unit and integration tests we wrote before, we
had to manage time ourselves. When dealing with asynchronous
commands and values, we had to use async / await,
fakeAsync and other means explicitly.

This is not necessary when writing Cypress tests. The Cypress

API is designed for expressiveness and readability. Cypress hides
the fact that all commands take time.

SYNCHRONOUS ASSERTIONS

Sometimes it is necessary to access and inspect a value

synchronously. Cypress allows this in form of callback functions
that are executed after a certain command was processed. You
can pass a callback function to the should command or the
more general then command.

Inside these callbacks, assertions on plain, unwrapped values

are written using Chai’s expect function. We will get to know
this practise later.

🔗 Cypress API reference: should with callback function

🔗 Cypress API reference: then command

Automatic retries and waiting

A key feature of Cypress is that it retries certain commands and
assertions.

For example, Cypress queries the document title and compares it

with the expected title. If the title does not match instantly,
Cypress will retry the cy.title command and the should
assertion for four seconds. When the timeout is reached, the
spec fails.

WAIT AUTOMATICALLY

Other commands are not retried, but have a built-in waiting

logic. For example, we are going to use Cypress’ click method
to click on an element.

Cypress automatically waits for four seconds for the element to

be clickable. Cypress scrolls the element into view and checks if it
is visible and not disabled. After several other checks, the
Cypress performs the click.

The retry and waiting timeout can be configured for all tests or
individual commands.

RETRY SPECS

If a spec fails despite these retries and waiting, Cypress can be

configured to retry the whole spec. This is the last resort if a
particular spec produces inconsistent results.
These features makes end-to-end tests more reliable, but also
easier to write. In other frameworks, you have to wait manually
and there is no automatic retry of commands, assertions or
specs.

🔗 Cypress introduction: Commands are asynchronous

🔗 Cypress documentation: Interacting with Elements
🔗 Cypress documentation: Retry-ability
🔗 Cypress documentation: Test Retries

Testing the counter increment

In our first Cypress test, we have checked the page title
successfully. Let us test the counter’s increment feature.

The test needs to perform the following steps:

1. Navigate to “/”.

2. Find the element with the current count and read its text
content.

3. Expect that the text is “5”, since this is the start count for the
first counter.

4. Find the increment button and click it.

5. Find the element with the current count and read its text
content (again).

6. Expect that the text now reads “6”.

We have used cy.visit('/') to navigate to an address. The

path “/” translates to http://localhost:4200/ since this is the
configured baseUrl.

Finding elements
The next step is to find an element in the current page. Cypress
provides several ways to find elements. We are going to use the
cy.get method to find an element by CSS selector.

cy.get('.example')

cy.get returns a Chainer, an asynchronous wrapper around the

found elements, enriched with useful methods.

Just like with unit and integration test, the immediate question
is: How should we find an element – by id, name, class or by
other means?

FIND BY TEST ID

As discussed in querying the DOM with test ids, this guide

recommends to mark elements with test ids.
These are data attributes like data-testid="example". In the
test, we use a corresponding attribute selector to find the
elements, for example:

cy.get('[data-testid="example"]')

FIND BY TYPE

Test ids are recommended, but other ways to find elements are
still useful in some cases. For example, you might want to check
the presence and the content of an h1 element. This element has
a special meaning and you should not find it with an arbitrary
test id.

The benefit of a test id is that it can be used on any element.

Using a test id means ignoring the element type (like h1) and
other attributes. The test does not fail if those change.

But if there is a reason for this particular element type or

attribute, your test should verify the usage.

🔗 Cypress API reference: cy.get

🔗 Cypress Best Practices: Selecting Elements

Interacting with elements

To test the counter Component, we want to verify that the start
count for the first counter is “5”. The current count lives in an
element with the test id count. So the element finder is:

cy.get('[data-testid="count"]')

PRESENCE AND CONTENT

The cy.get command already has an assertion built-in: It

expects to find at least one element matching the selector.
Otherwise, the spec fails.

Next, we check the element’s text content to verify the start

count. Again, we use the should method to create an assertion.

cy.get('[data-testid="count"]').should('have.text', '5');

The have.text assertion compares the text content with the

given string.

We did it! We have found an element and checked its content.

CLICK

Now let us increment the count. We find and click on the

increment button (test id increment-button). Cypress offers
the cy.click method for this purpose.

cy.get('[data-testid="increment-button"]').click();

The Angular code under test handles the click event. Finally, we
verify that the visible count has increased by one. We repeat the
should('have.text', …) command, but expect a higher
number.

The test suite now looks like this:

describe('Counter', () => {

beforeEach(() => {

cy.visit('/');

});

it.only('has the correct title', () => {

cy.title().should('equal', 'Angular Workshop: Counters');

});

it('increments the count', () => {

cy.get('[data-testid="count"]').should('have.text', '5');

cy.get('[data-testid="increment-button"]').click();

cy.get('[data-testid="count"]').should('have.text', '6');

});

});

The next feature we need to test is the decrement button. The

spec works similar to the increment spec. It clicks on the
decrement button (test id decrement-button) and checks that
the count has decreased.

it('decrements the count', () => {

cy.get('[data-testid="decrement-button"]').click();

cy.get('[data-testid="count"]').should('have.text', '4');

});

Last but not least, we test the reset feature. The user can enter a
new count into a form field (test id reset-input) and click on
the reset button (test id reset-button) to set the new count.

FILL OUT FORM

The Cypress Chainer has a generic method for sending keys to

an element that the keyboard can interact with: type.

To enter text into the form field, we pass a string to the type
method.

cy.get('[data-testid="reset-input"]').type('123');

Next, we click on the reset button and finally expect the change.

it('resets the count', () => {

cy.get('[data-testid="reset-input"]').type('123');

cy.get('[data-testid="reset-button"]').click();

cy.get('[data-testid="count"]').should('have.text', '123');

});

This is the full test suite:

describe('Counter', () => {

beforeEach(() => {

cy.visit('/');

});

it('has the correct title', () => {

cy.title().should('equal', 'Angular Workshop: Counters');

});

it('increments the count', () => {

cy.get('[data-testid="count"]').should('have.text', '5');

cy.get('[data-testid="increment-button"]').click();

cy.get('[data-testid="count"]').should('have.text', '6');

});

it('decrements the count', () => {

cy.get('[data-testid="decrement-button"]').click();

cy.get('[data-testid="count"]').should('have.text', '4');

});

it('resets the count', () => {

cy.get('[data-testid="reset-input"]').type('123');

cy.get('[data-testid="reset-button"]').click();

cy.get('[data-testid="count"]').should('have.text', '123');

});

});

On the start page of the counter project, there are in fact nine
counter instances. The cy.get command therefore returns nine
elements instead of one.

FIRST MATCH

Commands like type and click can only operate on one

element, so we need to reduce the element list to the first result.
This is achieved by Cypress’ first command inserted in the
chain.

it('increments the count', () => {

cy.get('[data-testid="count"]').first().should('have.text', '5');

cy.get('[data-testid="increment-button"]').first().click();

cy.get('[data-testid="count"]').first().should('have.text', '6');

});

This also applies to the other specs. If the element under test
only appears once, the first command is not necessary, of
course.

All counter features are now tested. In the next chapters, we will
refactor the code to improve its readability and maintainability.

🔗 Counter E2E test code

🔗 Cypress API reference: click
🔗 Cypress API reference: type
🔗 Cypress API reference: first
🔗 Cypress FAQ: How do I get an element’s text contents?

Custom Cypress commands

The test we wrote is quite repetitive. The pattern
cy.get('[data-testid="…"]') is repeated over and over.

The first improvement is to write a helper that hides this detail.

We have already written two similar functions as unit testing
helpers, findEl and findEls.

FIND BY TEST ID

The easiest way to create a Cypress helper for finding elements

is a function.
function findEl(testId: string):
Cypress.Chainable<JQuery<HTMLElement>> {

return cy.get(`[data-testid="${testId}"]`);

This would allow us to write findEl('count') instead of

cy.get('[data-testid="count"]').

CUSTOM COMMANDS

This works fine, but we opt for a another way. Cypress supports
adding custom commands to the cy namespace. We are going
to add the command byTestId so we can write
cy.byTestId('count').

Custom commands are placed in

cypress/support/commands.ts. This file is automatically
created by the Angular schematic. Using
Cypress.Commands.add, we add our own command as a
method of cy. The first parameter is the command name, the
second is the implementation as a function.

CY.BYTESTID

The simplest version looks like this:

Cypress.Commands.add(

'byTestId',

(id: string) =>

cy.get(`[data-testid="${id}"]`)

);

Now we can write cy.byTestId('count'). We can still fall back

to cy.get if we want to find an element by other means.

cy.byTestId should have the same flexibility as the generic

cy.get. So we add the second options parameter as well. We
borrow the function signature from the official cy.get typings.

Cypress.Commands.add(

'byTestId',

// Borrow the signature from cy.get

<E extends Node = HTMLElement>(

id: string,

options?: Partial<

Cypress.Loggable & Cypress.Timeoutable & Cypress.Withinable &

Cypress.Shadow

>,

): Cypress.Chainable<JQuery<E>> =

cy.get(`[data-testid="${id}"]`, options),

);

For proper type checking, we need to tell the TypeScript compiler

that we have extended the cy namespace. In commands.ts, we
extend the Chainable interface with a method declaration for
byTestId.

declare namespace Cypress {

interface Chainable {

/**

* Get one or more DOM elements by test id.

* @param id The test id

* @param options The same options as cy.get

*/

byTestId<E extends Node = HTMLElement>(

id: string,

options?: Partial<

Cypress.Loggable & Cypress.Timeoutable & Cypress.Withinable

& Cypress.Shadow

>,

): Cypress.Chainable<JQuery<E>>;

You do not have to understand these type definitions in detail.

They simply make sure that you can pass the same options to
cy.byTestId that you can pass to cy.get.

Save commands.ts, then open cypress/support/e2e.ts and

activate the line that imports command.ts.

import './commands';

This is it! We now have a strictly typed command cy.byTestId.

Using the command, we can declutter the test.

describe('Counter (with helpers)', () => {

beforeEach(() => {

cy.visit('/');

});

it('has the correct title', () => {

cy.title().should('equal', 'Angular Workshop: Counters');

});

it('increments the count', () => {

cy.byTestId('count').first().should('have.text', '5');

cy.byTestId('increment-button').first().click();

cy.byTestId('count').first().should('have.text', '6');

});

it('decrements the count', () => {

cy.byTestId('decrement-button').first().click();

cy.byTestId('count').first().should('have.text', '4');

});

it('resets the count', () => {

cy.byTestId('reset-input').first().type('123');

cy.byTestId('reset-button').first().click();

cy.byTestId('count').first().should('have.text', '123');

});

});

Keep in mind that all these first calls are only necessary since
there are multiple counters on the example page under test. If
there is only one element with the given test id on the page, you
do not need them.

🔗 Counter E2E test with helpers

🔗 Full code: commands.ts
🔗 Cypress documentation: Custom commands
🔗 Cypress documentation: Types for custom commands

Testing the Flickr search

We have learned the basics of Cypress by testing the counter
app. Let us delve into end-to-end testing with Cypress by testing
a more complex app, the Flickr search.

🔗 Flickr photo search: Source code

🔗 Flickr photo search: Run the app
Before writing any code, let us plan what the end-to-end test
needs to do:

1. Navigate to “/”.

2. Find the search input field and enter a search term, e.g.
“flower”.

3. Find the submit button and click on it.

4. Expect photo item links to flickr.com to appear.

5. Click on a photo item.

6. Expect the full photo details to appear.

NONDETERMINISTIC API

The application under test queries a third-party API with

production data. The test searches for “flower” and with each
test run, Flickr returns potentially different results.

There are two ways to deal with this dependency during testing:
1. Test against the real Flickr API.

2. Fake the Flickr API and return a fixed response.

If we test against the real Flickr API, we cannot be specific in our

expectations due to changing search results. We can superficially
test the search results and the full photo. We merely know that
the clicked photo has “flower” in its title or tags.

REAL VS. FAKE API

This has pros and cons. Testing against the real Flickr API makes
the test realistic, but less reliable. If the Flickr API has a short
hiccup, the test fails although there is no bug in our code.

Running the test against a fake API allows us to inspect the

application deeply. Did the application render the photos the API
returned? Are the photo details shown correctly?

Keep in mind that unit, integration and end-to-end tests

complement each other. The Flickr search is also tested
extensively using unit and integration tests.

Each type of test should do what it does best. The unit tests
already put the different photo Components through their
paces. The end-to-end test does not need to achieve that level of
detail.
With Cypress, both type of tests are possible. For a start, we will
test against the real Flickr API. Then, we will fake the API.

Testing the search form

We create a file called cypress/e2e/flickr-search.cy.ts.
We start with a test suite.

describe('Flickr search', () => {

const searchTerm = 'flower';

beforeEach(() => {

cy.visit('/');

});

it('searches for a term', () => {

/* … */

});

});

We instruct the browser to enter “flower” into the search field

(test id search-term-input). Then we click on the submit
button (test id submit-search).

it('searches for a term', () => {

cy.byTestId('search-term-input')

.first()

.clear()

.type(searchTerm);

cy.byTestId('submit-search').first().click();

/* … */

});

CLEAR, THEN TYPE

The type command does not overwrite the form value with a
new value, but sends keyboard input, key by key.

Before entering “flower”, we need to clear the field since it

already has a pre-filled value. Otherwise we would append
“flower” to the existing value. We use Cypress’ clear method for
that purpose.

Clicking on the submit button starts the search. When the Flickr
API has responded, we expect the search results to be appear.

EXPECT SEARCH RESULTS

A search result consists of a link (a element, test id photo-item-

link) and an image (img element, test id photo-item-image).

We expect 15 links to appear since this is amount of results

requested from Flickr.

cy.byTestId('photo-item-link')

.should('have.length', 15)

By writing should('have.length', 15), we assert that there

are 15 elements.
Each link needs to have an href containing
https://www.flickr.com/photos/. We cannot check for an
exact URL since results are the dynamic. But we know that all
Flickr photo URLs have the same structure.

There is no direct Chai assertion for checking that each link in

the list has an href attribute containing
https://www.flickr.com/photos/. We need to check each
link in the list individually.

The Chainer has an each method to call a function for each

element. This works similar to JavaScript’s forEach array
method.

cy.byTestId('photo-item-link')

.should('have.length', 15)

.each((link) => {

/* Check the link */

});

Cypress has three surprises for us.

SYNCHRONOUS JQUERY OBJECT

1. link is a synchronous value. Inside the each callback, we are

in synchronous JavaScript land. (We could do asynchronous
operations here, but there is no need.)
2. link has the type JQuery<HTMLElement>. This is an
element wrapped with the popular jQuery library. Cypress
chose jQuery because many JavaScript developers are already
familiar with it. To read the href attribute, we use
link.attr('href').

3. We cannot use Cypress’ should method since it only exists on

Cypress Chainers. But we are dealing with a jQuery object
here. We have to use a standard Chai assertion. We use
expect together with to.contain.

This brings us to:

cy.byTestId('photo-item-link')

.should('have.length', 15)

.each((link) => {

expect(link.attr('href')).to.contain(

'https://www.flickr.com/photos/'

);

});

The test now looks like this:

describe('Flickr search', () => {

const searchTerm = 'flower';

beforeEach(() => {

cy.visit('/');

});

it('searches for a term', () => {

cy.byTestId('search-term-input')

.first()

.clear()

.type(searchTerm);

cy.byTestId('submit-search').first().click();

cy.byTestId('photo-item-link')

.should('have.length', 15)

.each((link) => {

expect(link.attr('href')).to.contain(

'https://www.flickr.com/photos/'

);

});

cy.byTestId('photo-item-image').should('have.length', 15);

});

});

To start the tests, we first start the development server with ng

serve and then start Cypress:

ng run flickr-search:cypress-open

This opens the test runner where we click on flickr-

search.cy.ts.

🔗 Flickr search E2E test code

🔗 Cypress API reference: clear
🔗 Cypress API reference: each
🔗 jQuery API reference: attr
🔗 Chai API reference: include (contain)
Testing the full photo
When the user clicks on a link in the result list, the click event is
caught and the full photo details are shown next to the list. (If
the user clicks with the control/command key pressed or right-
clicks, they can follow the link to flickr.com.)

In the end-to-end test, we add a spec to verify this behavior.

it('shows the full photo', () => {

/* … */

});

First, it searches for “flower”, just like the spec before.

cy.byTestId('search-term-input').first().clear().type(searchTerm);

cy.byTestId('submit-search').first().click();

Then we find all photo item links, but not to inspect them, but to
click on the first on:

cy.byTestId('photo-item-link').first().click();

The click lets the photo details appear. As mentioned above, we

cannot check for a specific title, a specific photo URL or specific
tags. The clicked photo might be a different one with each test
run.

Since we have searched for “flower”, the term is either in the

photo title or tags. We check the text content of the wrapper
element with the test id full-photo.

cy.byTestId('full-photo').should('contain', searchTerm);

CONTAIN VS. HAVE  TEXT

The contain assertion checks whether the given string is

somewhere in the element’s text content. (In contrast, the
have.text assertion checks whether the content equals the
given string. It does not allow additional content.)

Next, we check that a title and some tags are present and not
empty.

cy.byTestId('full-photo-title').should('not.have.text', '');

cy.byTestId('full-photo-tags').should('not.have.text', '');

The image itself needs to be present. We cannot check the src

attribute in detail.

cy.byTestId('full-photo-image').should('exist');

The spec now looks like this:

it('shows the full photo', () => {

cy.byTestId('search-term-
input').first().clear().type(searchTerm);

cy.byTestId('submit-search').first().click();

cy.byTestId('photo-item-link').first().click();

cy.byTestId('full-photo').should('contain', searchTerm);

cy.byTestId('full-photo-title').should('not.have.text', '');

cy.byTestId('full-photo-tags').should('not.have.text', '');

cy.byTestId('full-photo-image').should('exist');

});

The assertions contain, text and exist are defined by Chai-

jQuery, an assertion library for checking jQuery element lists.

Congratulations, we have successfully tested the Flickr search!

This example demonstrates several Cypress commands and
assertions. We also caught a glimpse of Cypress internals.

🔗 Flickr search E2E test code

🔗 Cypress documentation: Chai-jQuery assertions

Page objects
The Flickr search end-to-end test we have written is fully
functional. We can improve the code further to increase clarity
and maintainability.

We introduce a design pattern called page object. A design

pattern is a proven code structure, a best practice to solve a
common problem.

HIGH-LEVEL INTERACTIONS

A page object represents the web page that is scrutinized by an

end-to-end test. The page object provides a high-level interface
for interacting with the page.

So far, we have written low-level end-to-end tests. They find

individual elements by hard-coded test id, check their content
and click on them. This is fine for small tests.

But if the page logic is complex and there are diverse cases to
test, the test becomes an unmanageable pile of low-level
instructions. It is hard to find the gist of these tests and they are
hard to change.

A page object organizes numerous low-level instructions into a

few high-level interactions. What are the high-level interactions
in the Flickr search app?

1. Search photos using a search term

2. Read the photo list and interact with the items

3. Read the photo details

Where possible, we group these interactions into methods of the

page object.

PLAIN CLASS

A page object is merely an abstract pattern – the exact

implementation is up to you. Typically, the page object is
declared as a class that is instantiated when the test starts.
Let us call the class FlickrSearch and save it in a separate file,
cypress/pages/flickr-search.page.ts. The directory
pages is reserved for page objects, and the .page.ts suffix
marks the page object.

export class FlickrSearch {

public visit(): void {

cy.visit('/');

The class has a visit method that opens the page that the page
object represents.

In the test, we import the class and create an instance in a

beforeEach block.

import { FlickrSearch } from '../pages/flickr-search.page';

describe('Flickr search (with page object)', () => {

const searchTerm = 'flower';

let page: FlickrSearch;

beforeEach(() => {

page = new FlickrSearch();

page.visit();

});

/* … */

});

The FlickrSearch instance is stored in a variable declared in

the describe scope. This way, all specs can access the page
object.

SEARCH

Let us implement the first high-level interaction on the page

object: searching for photos. We move the relevant code from
the test into a method of the page object.

public searchFor(term: string): void {

cy.byTestId('search-term-input').first().clear().type(term);

cy.byTestId('submit-search').first().click();

The searchFor method expects a search term and performs all

necessary steps.

ELEMENT QUERIES

Other high-level interactions, like reading the photo list and the
photo details, cannot be translated into page object methods.
But we can move the test ids and element queries to the page
object.

public photoItemLinks(): Cypress.Chainable<JQuery<HTMLElement>> {

return cy.byTestId('photo-item-link');

public photoItemImages(): Cypress.Chainable<JQuery<HTMLElement>> {

return cy.byTestId('photo-item-image');

public fullPhoto(): Cypress.Chainable<JQuery<HTMLElement>> {

return cy.byTestId('full-photo');

public fullPhotoTitle(): Cypress.Chainable<JQuery<HTMLElement>> {

return cy.byTestId('full-photo-title');

public fullPhotoTags(): Cypress.Chainable<JQuery<HTMLElement>> {

return cy.byTestId('full-photo-tags');

public fullPhotoImage(): Cypress.Chainable<JQuery<HTMLElement>> {

return cy.byTestId('full-photo-image');

These methods return element Chainers.

Next, we rewrite the end-to-end test to use the page object

methods.

import { FlickrSearch } from '../pages/flickr-search.page';

describe('Flickr search (with page object)', () => {

const searchTerm = 'flower';

let page: FlickrSearch;

beforeEach(() => {

page = new FlickrSearch();

page.visit();

});

it('searches for a term', () => {

page.searchFor(searchTerm);

page

.photoItemLinks()

.should('have.length', 15)

.each((link) => {

expect(link.attr('href')).to.contain(

'https://www.flickr.com/photos/'

);

});

page.photoItemImages().should('have.length', 15);

});

it('shows the full photo', () => {

page.searchFor(searchTerm);

page.photoItemLinks().first().click();

page.fullPhoto().should('contain', searchTerm);

page.fullPhotoTitle().should('not.have.text', '');

page.fullPhotoTags().should('not.have.text', '');

page.fullPhotoImage().should('exist');

});

});

For the Flickr search above, a page object is probably too much
of a good thing. Still, the example demonstrates the key ideas of
page objects:

Identify repetitive high-level interactions and map them to

methods of the page object.

Move the finding of elements into the page object. The test
ids, tag names, etc. used for finding should live in a central
place.

When the markup of a page under test changes, the page

object needs an update, but the test should remain
unchanged.

Leave all assertions (should and expect) in the specs. Do not

move them to the page object.

HIGH-LEVEL TESTS

When writing end-to-end tests, you get lost in technical details

quickly: finding elements, clicking them, filling out form fields,
checking fields values and text content. But end-to-end tests
should not revolve around these low-level details. They should
describe the user journey on a high level.

The goal of this refactoring is not brevity. Using page objects

does not necessarily lead to less code. The purpose of page
objects is to separate low-level details – like finding elements by
test ids – from the high-level user journey through the
application. This makes the specs easier to read and the easier
to maintain.

You can use the page object pattern when you feel the need to
tidy up complex, repetitive tests. Once you are familiar with the
pattern, it also helps you to avoid writing such tests in the first
place.
🔗 Flickr search E2E test with page object
🔗 Flickr search page object

Faking the Flickr API

The end-to-end test we wrote for the Flickr search uses the real
Flickr API. As discussed, this makes the test realistic.

The test provides confidence that the application works hand in

hand with the third-party API. But it makes the test slower and
only allows unspecific assertions.

INTERCEPT HTTP REQUESTS

With Cypress, we can uncouple the dependency. Cypress allows

us to intercept HTTP requests and respond with fake data.

First of all, we need to set up the fake data. We have already

created fake photo objects for the FlickrService unit test. For
simplicity, we just import them:

import {

photo1,

photo1Link,

photos,

searchTerm,

} from '../../src/app/spec-helpers/photo.spec-helper';

Using the fake photos, we create a fake response object that

mimics the relevant part of the Flickr response.

const flickrResponse = {

photos: {

photo: photos,

},

};

FAKE SERVER WITH ROUTE

Now we instruct Cypress to intercept the Flickr API request and

answer it with fake data. This setup happens in the test’s
beforeEach block. The corresponding Cypress command is
cy.intercept.

beforeEach(() => {

cy.intercept(

method: 'GET',

url: 'https://www.flickr.com/services/rest/*',

query: {

tags: searchTerm,

method: 'flickr.photos.search',

format: 'json',

nojsoncallback: '1',

tag_mode: 'all',

media: 'photos',

per_page: '15',

extras: 'tags,date_taken,owner_name,url_q,url_m',

api_key: '*',

},

},

body: flickrResponse,

headers: {

'Access-Control-Allow-Origin': '*',

},

},

).as('flickrSearchRequest');

cy.visit('/');

});

cy.intercept can be called in different ways. Here, we pass

two objects:

1. A route matcher describing the requests to intercept. It

contains the HTTP GET method, the base URL and a whole
bunch of query string parameters. In the URL and the
api_key query parameter, the * character is a wildcard that
matches any string.

2. A route handler describing the response Cypress should send.

As JSON response body, we pass the flickrResponse fake
object.

Since the request to Flickr is cross-origin, we need to set the

Access-Control-Allow-Origin: * header. This allows
our Angular application at the origin
http://localhost:4200 to read the response from the
origin https://www.flickr.com/.
ALIAS

Finally, we give the request an alias by calling

.as('flickrSearchRequest'). This makes it possible to refer
to the request later using the @flickrSearchRequest alias.

After this setup, Cypress intercepts the request to Flickr and

handles it by itself. The original Flickr API is not reached.

The existing, rather generic specs still pass. Before we make

them more specific, we need to verify that Cypress found a
match and intercepted the HTTP request. Because if it did not,
the test would still pass.

WAIT FOR REQUEST

We can achieve this by explicitly waiting for the request after

starting the search.

it('searches for a term', () => {

cy.byTestId('search-term-
input').first().clear().type(searchTerm);

cy.byTestId('submit-search').first().click();

cy.wait('@flickrSearchRequest');

/* … */

});

cy.wait('@flickrSearchRequest') tells Cypress to wait for

a request that matches the specified criteria.
@flickrSearchRequest refers to the alias we have defined
above.

If Cypress does not find a matching request until a timeout, the

test fails. If Cypress caught the request,
we know that the
Angular application received the photos specified in the photos
array.

SPECIFIC ASSERTIONS

By faking the Flickr API, we gain complete control over the

response. We chose to return fixed data. The application under
test processes the data deterministically. As discussed, this
allows us to verify that the application correctly renders the
photos the API returned.

Let us write specific assertions that compare the photos in the

result list with those in the photos array.

it('searches for a term', () => {

cy.byTestId('search-term-
input').first().clear().type(searchTerm);

cy.byTestId('submit-search').first().click();

cy.wait('@flickrSearchRequest');

cy.byTestId('photo-item-link')

.should('have.length', 2)

.each((link, index) => {

expect(link.attr('href')).to.equal(

`https://www.flickr.com/photos/${photos[index].owner}/${photos[inde
x].id}`,

);

});

cy.byTestId('photo-item-image')

.should('have.length', 2)

.each((image, index) => {

expect(image.attr('src')).to.equal(photos[index].url_q);

});

});

Here, we walk through the links and images to ensure that the
URLs originate from the fake data. Previously, when testing
against the real API, we tested the links only superficially. We
could not test the image URLs at all.

Likewise, for the full photo spec, we make the assertions more
specific.

it('shows the full photo', () => {

cy.byTestId('search-term-
input').first().clear().type(searchTerm);

cy.byTestId('submit-search').first().click();

cy.wait('@flickrSearchRequest');

cy.byTestId('photo-item-link').first().click();

cy.byTestId('full-photo').should('contain', searchTerm);

cy.byTestId('full-photo-title').should('have.text',
photo1.title);

cy.byTestId('full-photo-tags').should('have.text', photo1.tags);

cy.byTestId('full-photo-image').should('have.attr', 'src',
photo1.url_m);

cy.byTestId('full-photo-link').should('have.attr', 'href',
photo1Link);

});

The specs now ensure that the application under test outputs
the data from the Flickr API. have.text checks an element’s text
content, whereas have.attr checks the src and href
attributes.

We are done! Our end-to-end test intercepts an API request and

responds with fake data in order to inspect the application
deeply.

INTERCEPT ALL REQUESTS

In the case of the Flickr search, we have intercepted an HTTP

request to a third-party API. Cypress allows to fake any request,
including those to your own HTTP APIs.

This is useful for returning deterministic responses crucial for

the feature under test. But it is also useful for suppressing
requests that are irrelevant for your test, like marginal images
and web analytics.

🔗 Flickr search E2E test with cy.intercept

🔗 Photo spec helper
🔗 Cypress documentation: Network Requests
🔗 Cypress API reference: intercept
🔗 Cypress API reference: wait
End-to-end testing: Summary
End-to-end tests used to be expensive while the outcome was
poor. It was hard to write tests that pass reliably when the
application is working correctly. This time could not be invested
in writing useful tests that uncover bugs and regressions.

For years, Protractor was the end-to-end testing framework most

Angular developers relied on. With Cypress, a framework arose
that sets new standards. Compared to Protractor, Cypress excels
in developer experience and cost-effectiveness.

PROTRACTOR AND CYPRESS EXAMPLES

While this guide recommends to start with Cypress, WebDriver-

based frameworks are still useful if you need to test a broad
range of browsers. For all Cypress tests in this guide, you will
find equivalent Protractor tests in the example repositories.

Even with Cypress, end-to-end tests are much more complex and
error-prone than unit and integration tests with Jasmine and
Karma. Then again, end-to-end tests are highly effective to test a
feature under realistic circumstances.

🔗 Counter: Cypress tests

🔗 Counter: Protractor tests
🔗 Flickr search: Cypress tests
🔗 Flickr search: Protractor tests
Summary
LEARNING OBJECTIVES

Reducing the frustration from implementing and testing an application

Taking small steps when learning testing techniques and expanding test coverage
Growing as a developer and as a team by practicing automated testing

Writing tests is often a frustrating experience that comes on top

of implementation troubles. The logical and technical complexity
is overwhelming and intimidating. All this drains motivation.

The goal of this guide is to dispel the fear of testing. While

testing Angular applications is a complex matter, this guide
breaks it down into small, approachable steps and aims to give a
well-balanced overview.

Find a testing strategy that reduces the frustration and benefits

the quality of your software. Once you have written tests for a
couple of features, you will learn which tests are worthwhile –
tests that uncover bugs and prevent regressions. Continue with
these successes, then slowly explore other kind of tests.

Luckily, the Angular community works steadily to make testing

accessible. Angular’s architecture facilitates the testing of all
relevant parts. The framework ships with robust testing tools. If
they do not fit your needs, there are mature community projects
with alternative workflows.
Testing does not only make your software more reliable, but also
evolves your coding practice in the long run. It requires to write
testable code, and testable code is usually simpler.

Automated software testing is challenging and rewarding for

various reasons. Despite all troubles, that makes it fascinating.
Index of example applications
All example applications are repositories on GitHub:

🔗 Counter Component
🔗 Flickr photo search
🔗 Sign-up form
🔗 TranslatePipe
🔗 ThresholdWarningDirective
🔗 PaginateDirective
References
Angular: Grundlagen, fortgeschrittene Themen und Best
Practices, Second Edition, Ferdinand Malcher, Johannes
Hoppe, Danny Koppenhagen. dpunkt.verlag, 2019. ISBN 978-
3-86490-646-6

Testing Angular Applications, Jesse Palmer, Corinna Cohn, Mike

Giambalvo, Craig Nishina. Manning Publications, 2018. ISBN
978-1-61729-364-1

Testing JavaScript Applications, Lucas da Costa. Manning

Publications, 2021. ISBN 978-1-61729-791-5

JavaScript Testing Recipes, James Coglan, 2016.

Acknowledgements
This book would not be possible without the support and input
from many individuals. I would like to thank everyone in the
Angular, JavaScript and web development communities who not
only shares their knowledge and works on open source tools,
but also advocates for inclusive communities and software.

Thanks to the teams at 9elements, Diebold Nixdorf and Keysight

Technologies for the opportunity to work on first-class Angular
applications. Thanks for the challenges, resources and patience
that allowed me to research automated testing in detail.

Thanks to Netanel Basal for valuable feedback on the book, for

creating Spectator and for many helpful articles on Angular and
testing.

Thanks to Nils Binder for helping with the design, including the
dark color scheme. Thanks to Melina Jacob for designing the e-
book cover.

Thanks to Tim Deschryver, Kent C. Dodds, Kara Erickson, Asim

Hussain, Tracy Lee, Brandon Roberts, Jesse Palmer, Corinna
Cohn, Mike Giambalvo, Craig Nishina and Lucas F. Costa for
insights on Angular, RxJS and automated testing.
About
Author: Mathias Schäfer (molily)

Mathias is a software developer with a focus on web

development and JavaScript web applications.

Mathias is working for 9elements, a software and design agency.

Twitter: @molily

Please send feedback and corrections to [email protected]

or file an issue on GitHub.

Published on February 17th, 2021.

License
License: Creative Commons Attribution-ShareAlike (CC BY-SA 4.0)

The example code is released into the public domain. See

Unlicense.

The Flickr search example application uses the Flickr API but is
not endorsed or certified by Flickr, Inc. or SmugMug, Inc. Flickr is
a trademark of Flickr, Inc. The displayed photos are property of
their respective owners.

Online book cover photo: Flying probes testing a printed circuit

board by genkur, licensed from iStock.

E-book cover and favicon: Official Angular logo by Google,

licensed under Creative Commons Attribution (CC BY 4.0).

Legal notice: Impressum und Datenschutz