Forem: Rainer Hahnekamp

Angular's Testing Revolution: Vitest, Fake Timers & Testronaut

Rainer Hahnekamp — Mon, 27 Oct 2025 19:55:08 +0000

As we wrap up the year, the Angular world has been abuzz with big topics like Signal Forms. But quietly, and quite unexpectedly, a testing revolution is arriving with Angular version 21 - just two weeks away (at the time of this writing).

In this article, we’ll explore how Vitest is stepping in as the new default testing framework, how async testing will change for new zoneless Angular applications, and how Testronaut will make its debut as the community version of Playwright Component Testing for Angular.

Table of Contents

Vitest
Fake Timers
Testronaut

🧪 Vitest

The most important thing about Vitest is not Vitest itself 🙃.

For nearly two years, Angular developers have been in a kind of testing limbo.

With Karma’s deprecation in 2023, teams were left wondering which direction to go. Should they hold on to the old tools - sticking with Jasmine and hoping for a replacement in the form of the Modern Web Test Runner? Others had already switched to Jest - especially in Nx monorepos - but weren’t sure whether to stay or move on to Vitest (which was also available in Nx).

This lack of a clear choice made it very tough to plan for the future, especially for new projects 🤷.

Now, with the announcement that Vitest will be available as a testing framework starting with Angular 21, there's relief.

Developers finally have a decision and know what to pick.

The uncertainty is gone, and that's the most important aspect!

Vitest was the right decision.

Compared to Jasmine - and even Jest - Vitest brings a powerful API, a rich, forward-looking ecosystem that’s TypeScript-first and fully supports ESM. It also includes a browser mode, which means tests can run in a real browser environment.

That was one key point for the Angular team. They want to move forward - but not force everyone to rewrite. So it was crucial to choose a testing framework that, like Jasmine/Karma, runs tests in the browser.

Even though the APIs differ - especially around async testing and mocking - the environment stays the same.

Vitest is powered by Vite. And while Angular’s implementation doesn’t go all-in on Vitest (Angular builds the tests instead of Vite), it still closes the gap to the Vite ecosystem.

In the end, Angular doesn’t want to be an outsider anymore. It wants to become part of the broader JavaScript ecosystem - and Vite is the key for that.

The image shows that Jest is still dominating but Vitest has the momentum

Here's just a selection of Vitest's powerful API:

Polling Feature

expect.poll accepts a function which will return a value. Vitest will continue executing the assertion until it runs into a timeout or the matches is successful.

import { expect, test } from 'vitest';

test('wait for the asynchronous tasks to end', async () => {
  let a = 1;

  setTimeout(() => a++);
  Promise.resolve().then(() => a++);

  await expect.poll(() => a).toBe(3);
});

Soft Assertions

Soft Assertions execute all expects within a test, even if one fails. In case, one expect fails, the whole test is marked failed.

test('resource', () => {
  const todoResource = getSomeResource();

  expect.soft(resource.status()).toBe('resolved');
  expect.soft(resource.error()).toBeUndefined();
  expect.soft(resource.hasValue()).toBe(true);
})

Test Context

Test context allows us to add different functionality to a test. See it as some kind of "dependency injection" for tests.

In the example below, we add a wait function, which is then available as a parameter within the test.

context.ts

import { test as base } from 'vitest';

interface Fixtures {
  wait: (timeout?: number) => Promise<void>;
}

export const test = base.extend<Fixtures>({
  wait: async ({}, use) => {
    await use(
      (timeout = 0) =>
        new Promise<void>((resolve) => setTimeout(resolve, timeout)),
    );
  },
});

async.spec.ts

import { test } from './context';
import { expect } from 'vitest';

test('wait for the asynchronous task', async ({ wait }) => {
  let a = 1;

  setTimeout(() => a++);
  Promise.resolve().then(() => a++);

  expect(a).toBe(1);
  await wait();
  expect(a).toBe(3);
});

You can already use Vitest in Angular 20. For example, this repository already uses it. Just run ng test - just like you would with Jasmine/Karma - and it will execute the tests.

Starting with Angular 21, when you run ng new, you’ll be prompted to choose between Vitest and Jasmine, with Vitest being the default.

Migration schematics will also be available to help you migrate from Jasmine.

Vitest running behind ng test in Angular 20

For more information, check out Matthieu Riegler’s LinkedIn post - and I’m pretty sure more resources will follow.

And of course, check out the official Vitest website: https://vitest.dev

👋 Farewell `waitForAsync()` & `fakeAsync()`

Until now, Zone.js has played a central role in how Angular handles asynchronous behavior.

How Zone.js-testing "worked"

Zone.js patches timing functions like setTimeout and setInterval. This allows it to observe and track async tasks across the framework. However, one thing Zone.js could never patch was the native JavaScript Promise - since it's a language-level construct, not just a method.

In Angular testing, two functions built on Zone.js helped manage async behavior: fakeAsync() and waitForAsync().

waitForAsync() waits for all scheduled asynchronous tasks to finish before continuing with the test.

it('should wait for async tasks to end', waitForAsync(() => {
  let a = 1;
  setTimeout(() => {
    a++;
    expect(a).toBe(2);
  });
}));

This worked in most cases, but had limitations - especially when assertions were made after async tasks, or if a setTimeout was scheduled far into the future (e.g. 1 second or more). In such cases, the test would simply wait.

it('should wait for too long', waitForAsync(() => {
  let a = 1;
  setTimeout(() => {
    a++;
    expect(a).toBe(2);
  }, 10_000);
}));

it('should fail to assert an asynchronous task', waitForAsync(() => {
  let a = 1;
  setTimeout(() => {
    a++;
  });

  expect(a).toBe(2);
}));

fakeAsync() became the preferred solution. It gives developers full control over the async queue via tick() and flush(). tick() simulates the passage of time, while flush() executes all pending timers except for periodic ones like setInterval.

it('runs all asynchronous tasks immediately (synchronously) after flush', fakeAsync(() => {
  let a = 1;
  setTimeout(() => {
    a++;
  }, 5_000);

  setTimeout(() => {
    a++;
  }, 5_000);

  flush();

  expect(a).toBe(3);
}));

it('runs asynchronous tasks tick by tick 😉', fakeAsync(() => {
  let a = 1;
  setTimeout(() => {
    a++;
  }, 5_000);

  setTimeout(() => {
    a++;
  }, 5_000);

  tick(5_000);
  expect(a).toBe(2);

  tick(5_000);
  expect(a).toBe(3);
}));

Zoneless testing

Starting with Angular 20.2, the zoneless mode became stable. In Angular 21, it's the new default.

That also means fakeAsync() and waitForAsync() will stop working unless you explicitly enable Zone.js.

As unfortunate as it is, this means tests relying on these two utilities will have to be rewritten — not entirely, but at least the parts that manage asynchronous tasks.

⏱ Alternatives in Vitest (and Jest)

Luckily, the testing frameworks offer their own mechanisms for async control.

In Vitest and Jest, this feature is called fake timers.

Fake timers mock async APIs like setTimeout, setInterval, and more. They work very similar to waitForAsync and fakeAsync but are not exactly the same.

runAllTimers(): Runs all asynchronous tasks, even periodic ones. Also asynchronous tasks triggered by other asynchronous tasks are covered. This is what we know from flush() with the addition, that runAllTimers also covers setInterval.
advanceTimersByTime(ms): Runs all asynchronous tasks within a period of time. Close to tick() in fakeAsync().
runOnlyPendingTimers() - runs only currently scheduled timers

We have to enable fake timers explicitly, so that the testing framework can create the mocks first.

Since this is done in a beforeEach, we also need to disable them in afterEach.


describe('async tasks', () => {
  beforeEach(() => {
    vitest.useFakeTimers();
  });

  afterEach(() => {
    vitest.resetAllMocks();
  });

  it('runs all asynchronous tasks immediately (synchronously)', () => {
    let a = 1;
    setTimeout(() => {
      a++;
    }, 5_000);

    setTimeout(() => {
      a++;
    }, 10_000);

    vitest.runAllTimers();
    expect(a).toBe(3);
  });

  it('runs asynchronous tasks tick by tick 😉', () => {
    let a = 1;
    setTimeout(() => {
      a++;
    }, 5_000);

    setTimeout(() => {
      a++;
    }, 10_000);

    vitest.advanceTimersByTime(5_000);
    expect(a).toBe(2);

    vitest.advanceTimersByTime(5_000);
    expect(a).toBe(3);
  });
});

Not too bad, right?

Careful with Promises

There was one catch though. As mentioned above, Zone.js didn't compile down to native Promises, because they cannot be mocked. Fake Timers don't do any compilation. So if there is a native Promise, the fakes can't cover them.

it('fails on Promises', () => {
  let a = 1;
  Promise.resolve().then(() => a++);
  vitest.runAllTimers();
  expect(a).toBe(2); // this will fail
});

There's also another variation where both Promise and "mockable" timers come together.

it('fails on Promises 1', () => {
  let a = 1;
  setTimeout(() => Promise.resolve().then(() => a++));
  vitest.runAllTimers();
  expect(a).toBe(2);
});

it('fails on Promises 2', () => {
  let a = 1;
  Promise.resolve().then(() => setTimeout(() => a++));
  vitest.runAllTimers();
  expect(a).toBe(2);
});

What to do? We can fallback to the polling or use our wait function from the test fixtures example above. But there is also a solution for fake timers.

To handle this, fake timers can queue an additional Promise after the real one. Our test can then await that second Promise to ensure all async behavior completes.

Since this is quite common, Vitest provides us fakes for that. They are very easy to remember. In fact, they are the same fakes we had before, just with an Async suffix.

describe('async tasks', () => {
  beforeEach(() => {
    vitest.useFakeTimers();
  });

  afterEach(() => {
    vitest.resetAllMocks();
  });

  it('succeeds on Promises', async () => {
    let a = 1;
    Promise.resolve().then(() => a++);
    await vitest.runAllTimersAsync();
    expect(a).toBe(2);
  });

  it('succeeds on Promises 1', async () => {
    let a = 1;
    setTimeout(() => Promise.resolve().then(() => a++));
    await vitest.runAllTimersAsync();
    expect(a).toBe(2);
  });

  it('succeeds on Promises 2', async () => {
    let a = 1;
    Promise.resolve().then(() => setTimeout(() => a++));
    await vitest.runAllTimersAsync();
    expect(a).toBe(2);
  });
});

Even if you are using Zone.js, whenever you write a new test, use the fake timers.

🧑‍🚀 Testronaut

Let's face it: regardless of whether we use Vitest, Jest, or something else - nothing beats an E2E test. Why?

Developers can watch tests run live in the browser.
E2E frameworks handle asynchronous behavior automatically. Whether a component is still rendering or waiting on the browser - no problem, the framework’s got you covered.
Tools like testing-library rely on plugins to simulate real user events. With E2E frameworks, that's built-in.
E2E tests don’t just interact with elements because they exist in the DOM - they ensure the element is actually usable: visible, not overlapped, enabled, etc. for real users.

But there’s a downside: E2E frameworks require the whole application to be up and running. Reaching the feature under test often means navigating through the app, which can be cumbersome and slow.

A Better Way

Cypress Component Testing showed us a better approach. It could compile Angular components, mount them in the browser, and run a full E2E test - but focused on just the component.

That was in 2022. Today, the E2E framework of choice is Playwright. It supports component testing (CT) - but only for frameworks that fully support Vite.

There was a huge community effort to get Playwright CT working with Angular via Vite. It was fully implemented, working, and promising. But in November 2023, the PR was closed by the Playwright team. They had doubts about the long-term viability of CT in general - and a desire to reduce framework-specific maintenance.

👉 Playwright PR comment

Playwright CT Reloaded

Out of the ashes came Testronaut.

Testronaut is led by Younes Jaaidi (and the author of this article). Younes was part of the original effort to bring Angular CT to Playwright and previously contributed heavily to Cypress CT for Angular.

Testronaut is a community-driven Playwright Component Testing runner for Angular - but without forcing Angular to compile via Vite. Instead, it leverages the Angular CLI. That means the same build setup and speed you’re used to from ng serve, and no awkward workarounds.

Testronaut mounts a component and lets Playwright do what it does best: run a full, browser-based test with all the realism and async handling you'd expect from a real E2E framework.

And yes - the test code is straightforward. Here’s an example:

test('should emit an event on click', async ({ mount, page }) => {
  await mount(ClickMeComponent, { inputs: { clickMeLabel: 'Press me' } });
  await page.getByRole('button', { name: 'Press me' }).click();
  await expect(page.getByText('Lift Off!')).toBeVisible();
});

Testronaut is already available, though we recommend waiting until the schematics (ng add @testronaut/angular) are released for a smoother experience.

More info: https://testronaut.dev

My favorite Angular Setup in 2025

Rainer Hahnekamp — Thu, 16 Jan 2025 19:22:33 +0000

Angular continues to evolve rapidly. What should we use in 2025? Especially if we start with a new project.

Inspired by a Reddit discussion, this guide shares my personal take (=opinionated) on the most effective tools, libraries, and practices for Angular development in 2025.

The video version of this article is available on YouTube.

Reactivity: Go for Signals

Signals represent one of the most significant shifts in Angular's approach to reactivity. While some pieces like Signal Forms and httpResource are still in development, and effect remains in developer preview, my recommendation is clear: go all in with Signals.

Why shouldn’t you wait for Signal Forms and httpResource? The answer lies in the cost of rewrites. If you skip Signals now, you’ll likely default to RxJS for reactivity. But transitioning from RxJS to Signals later will require a much more extensive rewrite. Your have to realize that with RxJS, the paradigms are different, a lot of things are different.

On the other hand, by adopting Signals, you can ensure that your application is already aligned with Angular's future. For areas not yet "signalized" (e.g., Reactive Forms or HTTP communication), you can step out of the Signal reactivity and handle them the traditional way for now. For instance, you could use an effect to set the value of a FormGroup.

The key point is that starting with Signals means you only need to adjust the non-signalized parts of your code in the future. If you skip Signals now, you’ll face the daunting task of refactoring the entire application later.

That said, this doesn’t mean you should completely replace RxJS with Signals. My advice: Start with Signals, and if RxJS doesn’t offer any significant benefits, stick with Signals. Otherwise, go with RxJS.

For new applications, I’d also recommend adopting resource or rxResource from the start. While these APIs are currently experimental and might evolve, by the time your application goes live (which is often well beyond 2-3 months of initial development), they are likely to be stable.

Go learn more about Signals, you can check out my video

Angular CLI Over Nx

I prefer the Angular CLI because it provides everything I need to get started without adding unnecessary layers of complexity. While Nx offers pre-configured tooling, I find that manually setting up what I need with the Angular CLI is straightforward and works seamlessly with Schematics or pre-configured setup tools from that tool.

Starting with Nx introduces an additional layer of abstraction, which can feel overwhelming, especially in the early stages of a project. It also comes with its own learning curve and migration processes, which usually requires extra effort. In my experience, beginning with the Angular CLI and transitioning to Nx later, if needed, is the more practical approach.

That said, Nx offers value when your application grows. Its features, like advanced build tooling and mono repository management, become indispensable for large-scale projects. And if the time comes to adopt Nx, the process is straightforward — just run nx import.

For library development, however, I would choose Nx from the start.

Angular CLI • Overview • Angular

The web development framework for building modern apps.

angular.dev

Nx: Smart Monorepos · Fast Builds

Get to green PRs in half the time. Nx optimizes your builds, scales your CI, and fixes failed PRs. Built for developers and AI agents.

nx.dev

Angular Material + Tailwind

When it comes to UI development, I use Angular Material together with Tailwind.

Angular Material provides a robust library of components that integrate seamlessly with Angular. Since it is part of the Angular project (which consists of Material, the CLI, and the framework), it’s officially maintained and always kept in sync.

For me, Tailwind CSS is not a replacement for a UI library but the perfect complement to Angular Material. While Material handles most of my UI needs, Tailwind is used for fine-grained customizations, like positioning elements, tweaking margins, and adding utility classes.

I rarely encounter unique UI needs or work with an existing design system. Most of the time, I develop what I like to call "UI-boring" enterprise applications, where the combination of Angular Material and Tailwind is more than sufficient.

Angular Material UI Component Library

UI component infrastructure and Material Design components for Angular web applications.

material.angular.dev

tailwindcss.com

Testing: Jasmine/Karma and Playwright

To be fair, choosing the right testing tools is not easy at the moment. Since I go with the Angular CLI, I’ll stick to the only officially supported testing framework: the combination of Jasmine and Karma.

You might have heard that this pair has reached its end-of-life. That's not true. End-of-life applies only to Karma, which handles running the tests in the browser. Karma will be replaced by the Modern Web Test Runner in the future, but we don’t have to care about that. The commands we use in our tests are Jasmine, and that’s not going to be replaced. It will just stay.

What about Jest or Vitest? There are plans to support Jest officially. I hope it’s going to be Vitest, which is the modern tool, but I’m afraid the Angular team leans toward Jest.

Additionally, I use the Angular Testing Library, which runs on top of Jasmine. It enhances the testing experience by

providing utility functions to select elements via user-facing selectors, such as roles or labels, instead of relying on implementation details like class names or data-testid.
It simplifies the configuration of the TestingModule via a render function.
It handles asynchronous tasks and triggers the change detection automatically

Angular Testing Library | Testing Library

Angular Testing Library

testing-library.com

Since I don't write a test per file (aka. Unit Test), but for features a as a whole, I disable the automatic generation of a test in the CLI.

There is also a video about this "don't write tests for each file"

For end-to-end (E2E) testing, it’s going to be Playwright. If I don’t have existing code, I don’t see any reason to use something else. Playwright is fast, modern, and reliable.

Unfortunately, there’s no plan to support component testing in Angular with Playwright, but I can tell you that some work is going on in the background. It might come, maybe in the form of a community-driven effort.

And guess what, there I have also a video about Playwright 😅

Fast and reliable end-to-end testing for modern web apps | Playwright

Cross-browser end-to-end testing for modern web apps

playwright.dev

Code Guidelines: ESLint, Prettier, Husky, Lint-Staged & Sheriff

Sticking to clear code guidelines is essential for a clean and consistent codebase.

For linting, ESLint via angular-eslint remains the standard. It provides strong integration with Angular, meaning it also comes with the Angular Styles Guidelines. I also include the eslint-plugin-unused-imports library, which automatically removes unused imports — just as the name suggests.

While there’s an ESLint plugin for Prettier, I avoid using it. I don’t want formatting errors to show up as linting errors, turning everything red in the editor. Instead, I use lint-staged to run Prettier before every commit. To ensure the git hooks execute properly, I rely on Husky.

When it comes to enforcing architectural rules — particularly module boundaries and dependency rules between them — I use Sheriff. It also integrates with ESLint.

angular-eslint / angular-eslint

✨ Monorepo for all the tooling related to using ESLint with Angular

Angular ESLint

Monorepo for all the tooling which enables ESLint to lint Angular projects

This project is made possible thanks to the continued hard work going into https://github.com/typescript-eslint/typescript-eslint, and brilliant work on the original TSLint rule implementations in https://github.com/mgechev/codelyzer.

Quick Start

Follow the local environment and workspace setup guide in order to install the Angular CLI
Create…

View on GitHub

Prettier · Opinionated Code Formatter · Prettier

Opinionated Code Formatter

prettier.io

lint-staged / lint-staged

🚫💩 — Run tasks like formatters and linters against staged git files

🚫💩 lint-staged

Run tasks like formatters and linters against staged git files and don't let 💩 slip into your code base!

npm install --save-dev lint-staged # requires further setup

$ git commit

✔ Backed up original state in git stash (5bda95f)
❯ Running tasks for staged files...
  ❯ packages/frontend/.lintstagedrc.json — 1 file
    ↓ *.js — no files [SKIPPED]
    ❯ *.{json,md} — 1 file
      ⠹ prettier --write
  ↓ packages/backend/.lintstagedrc.json — 2 files
    ❯ *.js — 2 files
      ⠼ eslint --fix
    ↓ *.{json,md} — no files [SKIPPED]
◼ Applying modifications from tasks...
◼ Cleaning up temporary files...

See asciinema video

Why

Code quality tasks like formatters and linters make more sense when run before committing your code…

View on GitHub

typicode.github.io

Sheriff | Sheriff

Modularity for TypeScript Projects

sheriff.softarc.io

State Management: SignalStore

Angular’s introduction of Signals has greatly simplified state management, which is why I also choose a state management library that is built on top of Signals. For me, that’s the NgRx SignalStore.

I use SignalStore for both local and global state management. When do I decide to bring it in? The moment I find myself writing a service that holds a larger Signal and includes logic around it,

The SignalStore is not boilerplaty and it provides a clear standard.

As for the NgRx Global Store with Redux, I see it as a tool where an eventing-based system is necessary. To be honest, those scenarios are extremely rare for me. Even if such a need arises, I would wait for the upcoming eventing extension for the SignalStore.

If you haven't had the chance to try out the SignalStore, here's a jumpstart

ngrx.io

NgRx Toolkit | NgRx Toolkit

Extensions for the NgRx SignalStore

ngrx-toolkit.angulararchitects.io

`inject` over constructor

A heavily debated topic is inject vs constructor-based dependency injection. In my Java/Spring applications, I go with constructor-based DI, but in Angular, I choose inject.

inject also works within functions, which is a big advantage. My HTTP interceptors and router guards already depend on it, and who knows — there may be an alternative authoring format in the future that doesn’t require classes.

There are also other reasons for using inject, like type-safe injection tokens or the fact that it eliminates the need for property decorators, which aren’t standardized. But for me personally, the key argument is its support for use in functions.

Schematics

I try to keep my components small. As soon as a component grows larger, I split it into a container component and multiple presentational components. Logic goes into services.

Since my components therefore have around 100 lines of code, I don’t see the need for separate CSS and HTML files. Instead, I prefer inline styles and templates. To streamline this approach, I overwrite the schematics property in the angular.json file:

"schematics": {
  "@schematics/angular:component": {
    "inlineTemplate": true,
    "inlineStyle": true,
    "style": "scss",
    "skipTests": true,
    "flat": true,
    "changeDetection": "OnPush"
  },
  "@schematics/angular:class": {
    "skipTests": true
  },
  "@schematics/angular:directive": {
    "skipTests": true
  },
  "@schematics/angular:guard": {
    "skipTests": true
  },
  "@schematics/angular:interceptor": {
    "skipTests": true
  },
  "@schematics/angular:pipe": {
    "skipTests": true
  },
  "@schematics/angular:resolver": {
    "skipTests": true
  },
  "@schematics/angular:service": {
    "skipTests": true
  },
}

To be fully honest, I don’t use the Angular CLI anymore to create components or services. Since I prefer a single-file setup with inline templates and styles, I find it faster to simply create the file manually and use a live template/snippet that I’ve defined in my IDE.

For me, this approach is much quicker than running CLI commands and adjusting the generated files.

Zoneless & OnPush

As the name suggests, zone.js is no longer part of the game with zoneless mode. Instead, the function markForCheck— which has always been important for components using the OnPush strategy — now triggers change detection directly.

I go with zoneless mode. While it’s still experimental, some applications, like https://angular.dev, already use it in production. The argument here is the same as for rxResource: If you start a new application today, chances are high that you’ll go into production with either a developer preview or even a stable version of zoneless.

I also set my components to OnPush. OnPush shouldn’t cause any issues with zoneless mode. It’s necessary for an additional boost, called local change detection. You only get local change detection if the component is OnPush and a Signal in the template changes. With local change detection, only the component is checked, not its parents, which makes the process much faster.

For more information on change detection, I would recommend my video

SSR, Hydration, and Incremental Hydration

Server-Side Rendering (SSR), Hydration, and Incremental Hydration are essential for any internet-facing application with high demands on initial loading performance and good SEO.

Before I joined Angular Architects, I worked on an application where these features would have been a game-changer. If we had access to Incremental Hydration at the time, it would have been paradise for us.

That said, these capabilities come at a cost. They add additional complexity to the development and deployment processes.

Because of this, I recommend using SSR only if your application truly needs it, but then absolutely.

You might want to recheck this part. It could be that a video shows up here very soon...

Final Notes: Tools and Preferences

When it comes to package managers, I use pnpm over npm and yarn. For me it’s faster, and handles dependencies better. Yarn is also good, but I don't want to use version 1.

Fast, disk space efficient package manager | pnpm

Fast, disk space efficient package manager

pnpm.io

AI? Absolutely. It has become a necessity. I use CoPilot and ChatGPT as AI tools to boost productivity. As for my IDE, I stick with IntelliJ, a choice rooted in my Java background... and I still use the light theme 😅.

Microsoft Copilot: Your AI companion

Microsoft Copilot is your companion to inform, entertain and inspire. Get advice, feedback and straightforward answers. Try Copilot now.

copilot.microsoft.com

https://openai.com/

Outlook for 2025

Personally, I’m eager to try out Bun as an alternative to Node.js.

bun.sh

I also want to use Angular (TanStack) Query, which is gaining traction as a powerful tool for handling server state and caching. Also in combination with the SignalStore.

tanstack.com

And Analog, I need that for the ng-news website, which I wanted to do for some time now.

Analog | Analog

The fullstack Angular meta-framework

analogjs.org

I hear a lot of good things about Cursor, the AI IDE. Want to give that one a try as well.

And for Angular, I'm looking forward to the new features, such as httpResource and Signal Forms, which promise to bring reactivity even closer to core Angular patterns.

That's it. If you have an other selection or know about some tools which I don't, then please let me know.

I am also providing a GitHub repo which has all these tools installed and configured.

rainerhahnekamp / angular-starter

A starter project for a modern Angular application

Angular Project Setup

Installation

pnpm create @angular@latest -s -t -S --experimental-zoneless --ssr false --style scss [yourProjectName]

Manually add the following props to the angular.json The path is projects.[yourProjectName].schematics.@schematics/angular:component

"changeDetection": "OnPush"
"flat": true

UI

pnpm ng add @angular/material
pnpm install -D tailwindcss postcss autoprefixer
pnpm tailwindcss init

Open tailwind.config.js and add the following code to module.exports:

module.exports = {
  // ...
  content: ["./src/**/*.{html,ts}"],
};

At the beginning of styles.scss, add the following code:

@tailwind base;
@tailwind components;
@tailwind utilities;

Testing

Install the Angular Testing Library along the user-event library:

pnpm i -D @testing-library/angular @testing-library/dom @testing-library/user-event

Next, install Playwright and install the accompanying browsers:

pnpm i -D @playwright/test
pnpm playwright install

Code Quality

For code quality, we install angular-eslint, eslint-plugin-unused-imports, husky, prettier,lint-staged and Sheriff.

pnpm ng add @angular-eslint/schematics
pnpm i -D eslint-plugin-unused-imports husky prettier lint-staged @softarc/{sheriff-core,eslint-plugin-sheriff}

To integrate…

View on GitHub

And as always, feedback/comments are very welcomed.

Angular's effect(): Use Cases & Enforced Asynchrony

Rainer Hahnekamp — Wed, 02 Oct 2024 13:57:00 +0000

Angular's Signals are designed with simplicity in mind, providing three core functions: signal() to create Signals, computed() for derived Signals, and effect() to handle side effects.

The last one, effect(), stands out. While still in developer preview (unlike signal() and computed(), which became stable in v17), effect() has garnered a lot of attention in social media, blog posts, and community discussions. Many suggest avoiding it altogether, with some even saying it shouldn't exist.

This article presents three key arguments:

effect() has its righteous place and should be used where necessary.
The asynchronous nature of effect() means it should not be used to update Signals synchronously. For these cases, computed() is the better choice, even if some edge cases lead to less readable code.
The community discussion should move beyond stylistic debates (such as declarative vs. imperative programming) and blanket statements like "Don't use effect()." Instead, the focus should be on understanding the real consequences of its asynchronous behavior, which can have significant impacts on applications.

If you prefer watching a video over reading:

Signals Primer
computed() or effect(): A Matter of Style?
The Case for effect()
- Examples for side effects
- Examples with asynchronous Signal updates
effect()'s Achilles' Heel: Enforced Asynchrony
The Reset Pattern
Summary

Signals Primer

If you're already familiar with Signals, feel free to skip this section.

A Signal is a container for a value. To create one, we use the signal() function. To read the value, we call the Signal like a function. To update the value, we use the set() or update() methods.

const n = signal(2);
console.log(n()); // 2

n.set(3);
console.log(n()); // 3

n.update((value) => value + 1);
console.log(n()); // 4

Updates to a Signal must be immutable. If the Signal holds an object, the new value must have a different object address, e.g., by creating a shallow clone.

computed() creates a derived value, meaning it depends on other Signals and recalculates its value whenever those Signals change.

Signals created with signal() are of type WritableSignal, while those created with computed() are of type Signal.

A signal that notifies another is called a producer, while the one that depends on it is called a consumer.

const n = signal(2);
const double = computed(() => n() * 2);
console.log(double()); // 4

n.set(3);
console.log(double()); // 6

If we just want to execute code when one or more Signals change, we use the effect() function. Its usage is similar to computed() but doesn't return a new Signal.

An effect() runs asynchronously, at least once initially, and then whenever its producer notifies it.

const n = signal(2);
effect(() => console.log(n()));

window.setTimeout(() => {
  n.set(3);
  n.set(4);
}, 0);

// console output 2: (asynchronous execution of effect)
// console output 4: (asynchronous execution of effect)

Note that there's no output for the value 3. This happens because multiple synchronous changes happened, and the effect() only captures the final state after the synchronous execution completes.

Be aware of implicit tracking: if your effect() calls a method or function, all Signals used within it will be automatically tracked.

To avoid that, wrap that code with untracked.

effect(() => {
  const value = someSignalWeWantToTrack();

  untracked(() => {
    someService.doSomething(value);
  });
})

For more information, head to the official Angular documentation.

computed() or effect(): A Matter of Style?

There's a strong tendency to caution against using effect(). On social media, some even argue that you should never use it, though this doesn't hold up in real-world scenarios.

The official Angular documentation states: "Avoid using effects for the propagation of state changes."

The examples often presented are simple and are often cases where computed() could easily replace effect(). I'd argue that this is obvious.

Years of Angular + RxJS development have ingrained in us that this is an anti-pattern:

@Component({
  // ...
  template: `Double: {{ double }}`,
})
class DoubleComponent {
  n$ = new BehaviorSubject(2);
  double = 0;

  constructor() {
    this.n$.subscribe((value) => (this.double = value * 2));
  }
}

The computation of double here is a side effect. The best practice is to create derived Observable streams and avoid direct subscriptions.

@Component({
  // ...
  template: `Double: {{ double$ | async }}`,
})
class DoubleComponent {
  n$ = new BehaviorSubject(2);
  double$ = this.n$.pipe(map((value) => value * 2));
}

This code is more declarative. We don't need to explicitly subscribe, calculate, and assign the value. Instead, we define the calculation and connect it to the source. This approach makes the code easier to read and maintain.

The same principle applies to effect() and computed(). The effect() is imperative, while computed() is declarative.

@Component({
  // ...
  template: `Double: {{ double }}`,
})
class DoubleComponent {
  n = signal(2);
  double = 0;

  constructor() {
    effect(() => (this.double = this.n() * 2));
  }
}

Why would we use effect() here if computed() is available?

@Component({
  // ...
  template: `Double: {{ double() }}`,
})
class DoubleComponent {
  n = signal(2);
  double = computed(() => this.n() * 2);
}

Most of us wouldn't even consider using an effect() in this scenario.

Many discussions focus too much on the imperative vs. declarative. This is a stylistic debate, as using effect() in these cases doesn't harm your application.

Therefore, it can lead developers to think it's "safe" to use effect() to update other Signals. In some cases, effect() is even more readable.

The real issue is the asynchronous nature of the effect(), which can cause significant bugs. An example will follow later, but before diving into those examples, let's first take a look at the valid use cases for effect().

The Case for effect()

The "Don't use effect()" trend has led to some confusion. Whereas some developers might not see the risk of effect() others may avoid effect() even when it's the best and most appropriate choice.

Here are some noteworthy tweets from highly respected members of the Angular community:

// Detect dark theme var iframe = document.getElementById('tweet-1835596353143021850-863'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1835596353143021850&theme=dark" }

// Detect dark theme var iframe = document.getElementById('tweet-1836815585776160805-374'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1836815585776160805&theme=dark" }

// Detect dark theme var iframe = document.getElementById('tweet-1836066122904244443-469'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1836066122904244443&theme=dark" }

The most common uses cases for effect() are:

"Signal-exclusive" side effects: When reacting to a Signal's change where the immediate outcome is not a derived Signal.
asynchronous changes to Signals: When effect() updates another Signal, but first has to fetch data from a server.

Examples for side effects

A common example of using effect() is logging a Signal change or synchronizing data with local storage:

@Component({
  // ...
})
class DoubleComponent {
  n = signal(2);

  #logEffect = effect(() => console.log(n()));
  #storageSyncEffect = effect(() => localStorage.setItem("n", JSON.stringify({ value: n() })));
}

When interacting directly with the DOM, effect() is also the right tool. For example, connecting a Signal to chart data:

export class ChartComponent {
  chartData = input.required<number[]>();
  chart: Chart | undefined;

  updateEffect = effect(() => {
    const data = this.chartData();

    untracked(() => {
      if (this.chart) {
        this.chart.data.datasets[0].data = data;
        this.chart.update();
      }
    })
  });

  // code for creating the chart
}

Another common example is form synchronization:

export class CustomerComponent {
  customer = input.required<Customer>();

  formUpdater = effect(() => {
    this.formGroup.setValue(this.customer());
  });

  formGroup = inject(NonNullableFormBuilder).group({
    id: [0],
    firstname: ["", [Validators.required]],
    name: ["", [Validators.required]],
    country: ["", [Validators.required]],
    birthdate: ["", [Validators.required]],
  });
}

As you can see, the recurring pattern is that all these examples react to Signal changes but don't update other Signals.

This is similar to how we use Observable, where we had side effects in subscribe() or the tap() operator:

export class ChartComponent {
  chartData$ = inject(ChartDataService).getChartData();

  chart: Chart | undefined;

  constructor() {
    this.chartData$
      .pipe(
        tap((data) => {
          if (this.chart) {
            this.chart.data.datasets[0].data = data;
            this.chart.update();
          }
        }),
        takeUntilDestroyed(),
      )
      .subscribe();
  }

  // code for creating the chart
}

Examples with asynchronous Signal updates

Perhaps the most common use case for effect() is when a Signal changes and you need to fetch data asynchronously before updating another Signal.

For instance, take the following example where a Signal tracks a customer id from route parameters. Based on this id, you need to retrieve customer data from a server and update another Signal with the response:

@Component({
  // ..
  template: `
    @if (customer(); as value) {
      <app-customer [customer]="value" [showDeleteButton]="true" />
    }
  `
})
export class EditCustomerComponent {
  id = input.required({ transform: numberAttribute });
  customer = signal<Customer | undefined>(undefined);

  customerService = inject(CustomerService);

  loadEffect = effect(() => {
    const id = this.id();

    untracked(() => {
      this.customerService.byId(id).then(
        (customer) => this.customer.set(customer)
      );
    })
  });
}

In this example, loadEffect listens for changes to the id Signal, triggers an asynchronous fetch of customer data, and updates the customer Signal once the data is available.

It may seem like loadEffect is setting a derived value, but since there's an asynchronous task involved, computed() isn't an option. computed() requires the function to return a value immediately, which isn't possible here.

This loading mechanism could also be handled in a service, but that would just move the use of effect() to another place.

If you have a large application where much data fetching depends on route parameters and you're already using effect() for this purpose, it's perfectly fine.

Currently, your only options for reacting to Signal changes are computed() and effect(). If computed() doesn't work, effect() is
the right choice.

It's worth mentioning that when it comes to asynchronous tasks, there’s always the elephant in the room: RxJS.

While RxJS can be a powerful tool for managing async workflows, this article focuses on the role of effect(). I’ll touch on RxJS in more detail in another article.

If you want to go with an Observable, you must first convert
the Signal to an Observable. For that, you'd use toObservable(), but guess what? It uses an effect() internally.

Let's just keep in mind that when it comes to managing asynchronous race conditions, there is no way around RxJS.

Before we continue, let's consider forcing our way to a computed(). It's
possible, but the code would look like this:

@Component({
  selector: "app-edit-customer",
  template: `
    @if (customer(); as value) {
      <app-customer [customer]="value" [showDeleteButton]="true"></app-customer>
    }
    {{ loadComputed() }}
  `,
  standalone: true,
  imports: [CustomerComponent],
})
export class EditCustomerComponent {
  id = input.required({ transform: numberAttribute });
  customer = signal<Customer | undefined>(undefined);

  customerService = inject(CustomerService);

  loadComputed = computed(() => {
    const id = this.id();
    this.customerService.byId(id).then((customer) => this.customer.set(customer));
  });
}

What's the difference? First, we've generated a Signal of type void, which isn't particularly useful, and your fellow developers might not know what to do with a Signal of no value. Second, this only works because loadComputed is used in the template to keep the Signal alive.

Unlike effect(), a Signal needs to be called within a reactive context, such as a template, to become reactive.

We can all agree that using computed() in this case is not ideal.

effect()'s Achilles' Heel: Enforced Asynchrony

Here’s where real issue with effect() comes in. Unlike computed(), which runs synchronously, effect() enforces asynchronous execution. This can lead to serious bugs when immediate state updates are needed.

Let's look at the following example:

@Component({
  selector: "app-basket",
  template: `
    <h3>Click on a product to add it to the basket</h3>

    <div class="flex gap-4 my-8">
      @for (product of products; track product) {
        <button mat-raised-button (click)="selectProduct(product.id)">{{ product.name }}</button>
      }
    </div>

    @if (selectedProduct(); as product) {
      <p>Selected Product: {{ product.name }}</p>
      <p>Want more? Top up the amount</p>
      <div class="flex gap-x-4">
        <input [(ngModel)]="amount" name="amount" type="number" />
        <button mat-raised-button (click)="updateAmount()">Update Amount</button>
      </div>
    }
  `,
  standalone: true,
  imports: [FormsModule, MatButton, MatInput],
})
export default class BasketComponent {
  readonly #httpClient = inject(HttpClient);

  protected readonly products = products;
  protected readonly selectedProductId = signal(0);
  protected readonly selectedProduct = computed(() => products.find((p) => p.id === this.selectedProductId()));
  protected readonly amount = signal(0);

  #resetEffect = effect(() => {
    this.selectedProductId();
    untracked(() => this.amount.set(1));
  });

  selectProduct(id: number) {
    this.selectedProductId.set(id);
    console.log(this.selectedProduct()?.name + " added to basket");
  }

  updateAmount() {
    this.#httpClient.post("/basket", { id: this.selectedProductId(), amount: this.amount() }).subscribe();
  }
}

The BasketComponent lists some products and allows the user to select one.
After selecting a product, the user can update the amount for that product.

The #resetEffect resets the amount to 1 whenever a new product is selected. We could have placed this logic inside the selectProduct method, but linking it to the selectedProductId Signal ensures that any changes to selectedProductId — even from other event handlers — will always trigger the reset.

When the user switches to a different product, we want to send the selected product, along with the reset amount of 1, to the server. To achieve this, we add the following request inside selectProduct:

class BasketComponent {
  // ...
  selectProduct(id: number) {
    this.selectedProductId.set(id);
    console.log(this.selectedProduct()?.name + " added to basket");

    this.#httpClient.post("/basket", { id: this.selectedProductId(), amount: this.amount() }).subscribe();
  }
}

If we click on the first product, change the amount to something else, and then select a second product, we will see that the HTTP request still sends the amount from the first product. However, the input field correctly shows the reset value of 1.

It’s not that the #resetEffect didn’t run — otherwise, the input field wouldn't have updated. The issue is a timing problem.

An effect() runs asynchronously, whereas the event listener selectProduct runs synchronously. By the time the HTTP request is sent, the #resetEffect hasn’t even started executing, so the amount is still the old value.

This is a severe bug. The user sees the correct value, but the server receives the wrong one. Even worse, if the user submits their basket thinking the amount is correct, they could end up paying more and receiving a larger quantity than expected.

So far, we've seen that computed() behaves to effect(), like pipe() behaves to subscribe() in RxJS.

This is where the comparison with RxJS breaks down. In RxJS, a subscription would run synchronously, ensuring that everything stays in sync.

We’ve identified the problem — now, what’s the solution?

The Reset Pattern

The reset pattern, introduced at TechStackNation, solves tricky synchronous Signal updates using computed(). In these cases, while effect() may seem simpler, the reset pattern ensures updates happen synchronously.

The pattern places a nested Signal inside a computed(), initialized with a default value. These Signals act as triggers, and when they change, the
computed() recalculates and updates the Signal synchronously.

Here’s how the #resetEffect would be re-modeled using computed():

class BasketComponent {
  protected readonly state = computed(() => {
    return {
      selectedProduct: this.selectedProduct(),
      amount: signal(1),
    };
  });
}

As soon as the selectedProductId changes, the computed() is notified
synchronously and is internally marked as dirty. The selectProduct method then reads the value of amount and gets the correct value back.

For the sake of completeness, here is the final version of the BasketComponent:

@Component({
  selector: "app-basket",
  template: `
    <h3>Click on a product to add it to the basket</h3>

    <div class="flex gap-4 my-8">
      @for (product of products; track product) {
        <button mat-raised-button (click)="selectProduct(product.id)">
          {{ product.name }}
        </button>
      }
    </div>

    @if (state().selectedProduct; as product) {
      <p>Selected Product: {{ product.name }}</p>
      <p>Want more? Top up the amount</p>
      <div class="flex gap-x-4">
        <input [(ngModel)]="state().amount" name="amount" type="number" />
        <button mat-raised-button (click)="updateAmount()">Update Amount</button>
      </div>
    }
  `,
  standalone: true,
  imports: [FormsModule, MatButton, MatInput],
})
export default class BasketComponent {
  readonly #httpClient = inject(HttpClient);

  protected readonly products = products;
  protected readonly selectedProductId = signal(0);
  readonly #selectedProduct = computed(() => products.find((p) => p.id === this.selectedProductId()));

  state = computed(() => {
    return {
      selectedProduct: this.#selectedProduct(),
      amount: signal(1),
    };
  });

  selectProduct(id: number) {
    this.selectedProductId.set(id);
    console.log(this.#selectedProduct()?.name + " added to basket");

    this.#httpClient.post("/basket", { id: this.selectedProductId(), amount: this.state().amount() }).subscribe();
  }

  updateAmount() {
    this.#httpClient.post("/basket", { id: this.selectedProductId(), amount: this.state().amount() }).subscribe();
  }
}

At first glance, and even after, the reset pattern seems like a lot of
boilerplate. The effect() version is much more intuitive.

However, Alex Rickabaugh from the Angular team has presented this pattern, which is a good sign. This means that the team is aware of the problem, and we can expect utility functions to address it in future versions of Angular.

Summary

effect() has many valid use cases. Avoiding it in real-world applications will lead to poorer code quality.

We can compare the relationship between computed() and effect() to the declarative style of using pipe() in RxJs versus placing side-effects directly in tap() or subscribe(). effect() runs asynchronously, however.

For operations that synchronously modify other Signals, computed() is required — even if that means sacrificing some readability and maintainability. The risk of introducing bugs due to the asynchronous behavior of effect() is simply too high.

Fortunately, the Angular team has already recognized these issues, and we can expect new utility functions to provide solutions for these cases.

Some utility functions already exist that use effect() internally while protecting against misuse. Examples include toObservable(), rxMethod() from @ngrx/signals, and explicitEffect() from ngxtension.

These types of functions will likely become more common in the future, reducing the need for directly writing effect() in many
situations.

Common use cases for effect() include side-effects that don't result in changes to other Signals. It's also ideal for triggering asynchronous tasks, regardless of whether they eventually produce a new value for a Signal.

Use effect(). It is a critical part of Signals.

In case you are in doubt, let me give you a mnemonic:

Whenever you see have the for an effect, like this...

effect(() => {
  // side-effects, asynchronous or synchronous Signal updates
});

...and you can wrap it into an asynchronous task like this...

effect(() => {
  Promise.resolve().then(() => {
    // side effect, asynchronous or synchronous Signal updates
  })
});

...you are fine.

Special thanks to Manfred Steyer for reviewing this article, and to my GDE colleagues and Michael Egger-Zikes for the insightful discussions that led to this article.

Further Reading:

Alex Rickabaugh at TechStackNation - Don't Use Effects 🚫 and What To Do Instead

Angular Documentation - Signals

https://angular.dev/guide/signals

Rainer Hahnekamp - Signals Unleashed, The Full Guide

Manfred Steyer - Blog Series on Signals

Signals in Angular: Building Blocks - ANGULARarchitects

angulararchitects.io

Angular Community - Discussion on Explicit Effect

Explicit Tracking for `effect()`: Request for Reconsideration #56155

rainerhahnekamp posted on May 29, 2024

Which @angular/* package(s) are relevant/related to the feature request?

core

Changelog

June 2, 2024: Added section on relying on external libraryes

Description

We have been refactoring an application towards using Angular's Signals. During this process, we observed a recurring pattern where effects inevitably require the use of untracked. This pattern has revealed several issues:

Frequent Use of untracked: Developers frequently need to use untracked to prevent unintended side effects in signals, making it a standard practice in our codebase.
Error-Prone Nature: The necessity of untracked is not well-known among developers, leading to common errors when it is omitted.
Maintenance Overhead: Constantly ensuring that untracked is correctly applied adds to the maintenance burden and cognitive load on developers.

To address these issues, we propose that Angular effects should adopt an explicit tracking model.

Proposed solution

Explicit Declaration: Developers should explicitly declare dependencies within effects, rather than relying on automatic tracking.
Default Non-Tracking: By default, effects should not track dependencies unless explicitly specified, reducing the need for untracked.

Example Scenario: Currently, developers write:

id = input.required<number>();

effect(() => {
  // Part 1: Tracking
  const id = this.id();

  // Part 2: Execution
  untracked(() => {
    this.dataService.load(id);
  });
})

With explicit tracking, it would look like:

id = input.required<number>();

effect(this.id, (id) => {
  this.dataService.load(id);
});

Benefits:

Reduced Errors: Explicit tracking minimizes the risk of overlooking untracked, leading to more predictable and stable code.
Improved Developer Experience: Clearer dependency management simplifies understanding and maintaining the code.
Enhanced Performance: Explicit tracking can optimize performance by avoiding unnecessary re-computations and side effects.

Internal API and Library Ecosystem: It is noteworthy that some parts of the internal Angular API already utilize automatic untracked. While this is beneficial, other libraries face similar problems and would benefit if the untracking responsibility was handled by the caller. This approach can provide more consistent and error-free usage across different codebases and libraries.

** External Libraries:** It has been suggested that this change be implemented as an external library instead. Most application developers are not aware of explicit tracking, though, and would not expect implicit tracking, leading to bugs. Relying on an external library requires developers to be aware of the problem and actively seek out a solution.

Reference: https://github.com/angular/angular/issues/56155#issuecomment-2137760839

Prior Discussion: This issue was previously raised in

Thank you for considering this enhancement.

Alternatives considered

Introducing a fourth "effect-like" function with explicit tracking
Keep it as it is

View on GitHub

How do I test Signal & Model Inputs?

Rainer Hahnekamp — Fri, 08 Mar 2024 16:00:00 +0000

This article explains how to test Signal and Model Inputs, which are the input() and the model() functions.

Signal Inputs

Signal Inputs arrived in Angular 17.1. They fulfill the same tasks as the @Input decorator: Property Binding. A Signal Input is a simple function named input(). The new Property Binding syntax looks like this:

// @Input-Style (old)
class HolidayComponent {
  @Input() username = '';
  @Input({required: true}) holiday: Holiday | undefined;
}

// Signal Input (new)
class HolidayComponent {
  username = input(''); // Signal<string>
  holiday = input<Holiday>(); // Signal<Holiday | undefined>
}

The property is of type Signal, which makes it reactive by nature. Instead of ngOnChanges() and ngOnInit(), we can consume changes with effect() or computed().

The second addition is the additional required() function. It fixes the issue with @Input({required: true}), which always results in the union type including undefined and the actual type:

// required input
class HolidayComponent {
  username = input(''); // Signal<string>
  holiday = input.required<Holiday>(); // Signal<Holiday>
} 

@Component({
  tempate: `<app-holiday [username]="username" [holiday]="holiday" />`
})
class HolidayContainerComponent {
  username = 'Konrad Weber';
  holiday = createHoliday();
}

Testing Signal Inputs

How do we test that? We can set input properties via the componentInstance or the setInput() like this:

// Input Signal via componentInstance
it('should show username and holiday', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [HolidayComponent],
  }).createComponent(HolidayComponent);

  const holiday = signal(createHoliday({ title: "'London' }));"

  fixture.componentInstance.holiday =
    holiday as unknown as typeof fixture.componentInstance.holiday;

  fixture.detectChanges();

  const body: HTMLParagraphElement = fixture.debugElement.query(
    By.css('[data-testid=txt-body]'),
  ).nativeElement;

  expect(body.textContent).toContain('Are you interested in visiting London?');

  holiday.update((value) => ({ ...value, title: "'Vienna' }));"
  fixture.detectChanges();

  expect(body.textContent).toContain('Are you interested in visiting Vienna?');
});

// Input Signal via componentRef
it('should show username and holiday', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [HolidayComponent],
  }).createComponent(HolidayComponent);

  fixture.componentRef.setInput('holiday', createHoliday({ title: "'London' }));"
  fixture.detectChanges();

  const body: HTMLParagraphElement = fixture.debugElement.query(
    By.css('[data-testid=txt-body]'),
  ).nativeElement;
  expect(body.textContent).toContain('Are you interested in visiting London?');

  fixture.componentRef.setInput('holiday', createHoliday({ title: "'Vienna' }));"
  fixture.detectChanges();

  expect(body.textContent).toContain('Are you interested in visiting Vienna?');
});

Try to avoid that!

There is also another option that goes under different names. I tend to call it the "Wrapper Component" pattern. Another name is the Host Component. We create a Component for the test that uses the HolidayComponent and apply Property Binding.

The "Wrapper Component"/"Host Component" pattern

The test communicates with the "Wrapper Component" and passes over the task of Property Binding to Angular:

@Component({
  template: ` <app-holiday [holiday]="holiday" />`,
  standalone: true,
  imports: [HolidayComponent],
})
class HolidayWrapperComponent {
  holiday = createHoliday({ title: "'London' });"
}
it('should show username and holiday', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [HolidayWrapperComponent],
  }).createComponent(HolidayWrapperComponent);

  const { componentInstance } = fixture;
  fixture.detectChanges();

  const body: HTMLParagraphElement = fixture.debugElement.query(
    By.css('[data-testid=txt-body]'),
  ).nativeElement;

  expect(body.textContent).toContain('Are you interested in visiting London?');
  componentInstance.holiday = createHoliday({ title: "'Vienna' }); "
  fixture.detectChanges();

  expect(body.textContent).toContain('Are you interested in visiting Vienna?');
});

Why the "Wrapper Component"?

We don't know how Property Binding internally works. By directly setting a property via the componentInstance, we take a shortcut and remove Angular's part from the equation.

A common argument for that approach is that we don't want to involve Angular in our tests because we don't want to test Angular.

That's not true. Our code runs with Angular. By removing Angular, we are taking high risks that the test won't reflect the runtime behavior and thus will produce wrong results.

A simple example: You set the property before you run fixture.detectChanges(). Is this also the way how Angular does it? Does it set the property in the constructor, in ngOnInit(), between the instantiation and ngOnInit()? What about ngOnChanges() and the afterNextRender(), afterRender()?

We would have to call all these hooks manually and know when to do that. In that sense, we're re-implementing parts of the Angular framework.

Wouldn't it be better if we just let Angular do its things? We do ours, and the test runs both. Much better!

We should always try to run our tests in an environment as close to the applications as possible. If that doesn't come with additional costs, like slower tests or significantly more code, then do that.

Testing is not easy; don't make it harder for yourself as it already is ;).

ComponentRef::setInput() should work in most cases as long as you test via the DOM. setInput() is part of the Angular API, and the Angular Team designed it for that use case.

When you use Signal Inputs, directly setting properties on the component instance is not possible anymore.

The same also applies to testing the old @Input(). Testing tools, like the "Testing Library" or "Cypress Component Test Runner", support the "Wrapper Component" pattern out of the box.

Model Inputs

Where input() is one-way, model() is two-way binding. As a result, the Signal becomes writable, and we also have the required() function available.

The "Wrapper Component" pattern makes testing the model() a no-brainer.

Let's say HolidayComponent wants to introduce a rating feature for the holiday and emits an event whenever the rating changes. We must replace the input() with the model().

The parent component can still apply Property Binding but gets a new event named holidayChange. This allows the parent to use the classic two-binding via the "banana box" syntax:

@Component({
  selector: 'app-holiday',
  template: `<p data-testid="txt-greeting">Hello {{ username() }}</p>
    <p data-testid="txt-body">
      Are you interested in visiting {{ holiday().title }}?
    </p>
    <p> Rate your Holiday </p>
    <button mat-raised-button data-testid="btn-up" (click)="rating.set('👍')"
      >👍</button
    >
    <button mat-raised-button data-testid="btn-down" (click)="rating.set('👎')"
      >👎</button
    >`,
  standalone: true,
  imports: [MatButton],
})
export class HolidayComponent {
  username = input('');
  holiday = input.required<Holiday>();
  rating = model.required<'👍' | '👎'>();
}

Again, we use the "WrapperComponent", which does two-way binding on rating:

@Component({
  template: ` <app-holiday [holiday]="holiday" [(rating)]="rating" />
    <p data-testid="txt-rating">{{ rating }}</p>`,
  standalone: true,
  imports: [HolidayComponent],
})

class HolidayWrapperComponent {
  holiday = createHoliday({ title: "'London' });"
  rating = '👎';
}

describe('Holiday Component', () => {
  it('should apply two-way-binding on rating', () => {
    const fixture = TestBed.configureTestingModule({
      imports: [HolidayWrapperComponent],
    }).createComponent(HolidayWrapperComponent);
    fixture.detectChanges();
    const rating: HTMLParagraphElement = fixture.debugElement.query(
      By.css('[data-testid=txt-rating]'),
    ).nativeElement;
    expect(rating.textContent).toBe('👎');
    fixture.debugElement
      .query(By.css('[data-testid=btn-up]'))
      .nativeElement.click();
    fixture.detectChanges();
    expect(rating.textContent).toBe('👍');
  });
});

HolidaysWrapperComponent shows the current rating and passes it on to the HolidayComponent. Since we use the "banana box" syntax, any change to the HolidayComponent's rating would also happen to the wrapper's rating.

Summary

Testing Signal and Model Inputs is very easy as long as we communicate with the Component via the DOM and let Angular the Property Binding.

The "Wrapper Component" pattern or ComponentRef::setInput() are the right approaches to that common testing use case.

You can access the repository at https://github.com/rainerhahnekamp/how-do-i-test

If you encounter a testing challenge you'd like me to address here, please get in touch with me!

For additional updates, connect with me on LinkedIn, X, and explore our website for workshops and consulting services on testing.

Professional Angular Testing Workshop | ANGULARarchitects

angulararchitects.io

How do I test Signals (signal, computed, effect)?

Rainer Hahnekamp — Thu, 07 Mar 2024 16:00:00 +0000

Signals as lightweight "reactive primitive" will shape the future of Angular applications. At the time of this writing, signal() and computed() are stable, and effect() is in developer preview.

Developer preview doesn't mean we have an unstable feature but that the Angular team can introduce breaking changes within a major version. The feature is stable; otherwise, it would have the experimental label.

Especially with Signal Inputs, Signals find more and more usage in everyday tasks. It is time to consider integrating Signals into our codebases.

And that requires us to be able to write tests as well.

If you are more of a visual learner, here's a video for you:

Signals & Reactivity in a nutshell

With computed() and effect(), we create derived Signals or run side effects if a Signal's value changes. That is the reactive nature of Signals.

Compared to RxJs, reactivity does not require a manual subscription. Angular does that for you.

Signals, i.e., created by signal() or computed(), need to run inside a so-called Reactive Context. In Angular, there are two of them:

A Component's template
The effect() function

In other words, a Signal becomes reactive whenever we call a Signal inside a template or an effect().

When a "reactive Signal" changes, the Signal will notify consumers who are computed(), effect() or a template. computed() could have further consumers that could also have consumers on their end, and so on...

Depending on the Reactive Context, a DOM update (template) or a side effect (effect()) runs.

The Reactive Context runs during the Change Detection: Only the last value gets through. Even if a Signal changes multiple times between Change Detection runs. That means a computed(), an effect(), and the template processes the last value, not the intermediary ones.

This behavior makes total sense when looking at Signals from the perspective of a frontend framework. If we have three synchronous (intermediate) changes, why do we want to update the DOM three times? End users wouldn't see the new value if it were technically possible because it would change in the following rendering frame. It is much better to wait until the Signal reaches its "stable state" and then start updating the DOM.

This behavior is known under the term "Glitch-free effect" or "Push/Pull"

Maybe this animation might help you understand the "Glitch-free effect" as well.

Component under Test

Our Component is a basket in an online shop where users can increase or decrease the amount of products:

@Component({
  selector: 'app-basket',
  template: `<h2>Basket</h2>
    <div class="w-[640px]">
      <div class="grid grid-cols-4 gap-4 auto-cols-fr">
        <div class="font-bold">Name</div>
        <div class="font-bold">Price</div>
        <div class="font-bold">Amount</div>
        <div>&nbsp;</div>
        @for (product of products(); track product.id) {
          <div>{{ product.name }}</div>
          <div>{{ product.price }}</div>
          <div>{{ product.amount }}</div>
          <div>
            <button
              mat-raised-button
              (click)="decrease(product.id)"
              data-testid="btn-decrease"
            >
              <mat-icon>remove</mat-icon>
            </button>
            <button
              mat-raised-button
              (click)="increase(product.id)"
              data-testid="btn-increase"
            >
              <mat-icon>add</mat-icon>
            </button>
          </div>
        }

        <div class="font-bold">Total</div>
        <div class="font-bold" data-testid="total">{{ totalPrice() }}</div>
      </div>
    </div>`,
  standalone: true,
  imports: [MatButton, MatIcon],
})
export default class BasketComponent {
  products = signal([
    { id: 1, name: 'Coffee', price: 3, amount: 1 },
    { id: 2, name: 'Schnitzel', price: 15, amount: 1 },
  ]);

  syncService = inject(SyncService);

  constructor() {
    effect(() => this.syncService.sync(this.products()));
  }

  totalPrice = computed(() =>
    this.products().reduce(
      (total, product) => total + product.price * product.amount,
      0,
    ),
  );

  decrease(id: number) {
    this.#change(id, (product) =>
      product.amount > 0 ? { ...product, amount: product.amount - 1 } : product,
    );
  }

  increase(id: number) {
    this.#change(id, (product) => ({ ...product, amount: product.amount + 1 }));
  }

  #change(id: number, callback: (product: Product) => Product) {
    this.products.update((products) =>
      // some logic to update the products
    );
  }
}

The total price is a computed value. It updates on any change of the products Signal.

The same is true for SyncService. It has the following implementation:

@Injectable({ providedIn: 'root' })
export class SyncService {
  sync(products: Product[]) {
    console.log(products);
  }
}

Not that much 😀, but we'd like to keep the example as short as possible.

Testing with Change Detection

Given the central role of Change Detection for Signals, it should be evident that testing them becomes much easier if the Change Detection is part of the test.

That's always the case when our tests communicate with the Component via the DOM and create the Component via TestBed.createComponent.

Testing `computed()`

This is a test that verifies the total price via the DOM:

it('should increase the quantity of the product', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [BasketComponent],
  }).createComponent(BasketComponent);
  fixture.detectChanges();

  const total: HTMLDivElement = fixture.debugElement.query(
    By.css('[data-testid="total"]'),
  ).nativeElement;
  expect(total.textContent).toBe('18');

  fixture.debugElement
    .query(By.css('[data-testid="btn-increase"]'))
    .nativeElement.click();
  fixture.detectChanges();

  expect(total.textContent).toBe('21');
});

That test works as expected. No surprises!

Everything is alright if we run the Change Detection in the right places. That right place is after an event, like a click, and at the beginning to initialize the Component.

Testing `effect()`

It becomes slightly trickier if we include the effect() in our test.

Since effect() runs the SyncService, we want to count its calls.

During every Change Detection, the effect() checks if the value of products has changed. If yes, the effect() runs the SyncService.

We cannot assert the execution of the SyncService via the DOM. That's why we have to apply a spy on the SyncService instance. For that we require access to the componentInstance.

The updated test:

it('should run the SyncService', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [BasketComponent],
  }).createComponent(BasketComponent);
  const syncService = TestBed.inject(SyncService);
  const spy = spyOn(syncService, 'sync');
  fixture.detectChanges();

  expect(spy).toHaveBeenCalledTimes(1);
});

We can verify that the effect() only runs when products change and the Change Detection is executed.

The following two tests have to fail:

it('should run the SyncService', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [BasketComponent],
  }).createComponent(BasketComponent);
  const syncService = TestBed.inject(SyncService);
  const spy = spyOn(syncService, 'sync');

  // Change Detection did not run 
  expect(spy).toHaveBeenCalledTimes(1); 
})

it('should run the SyncService', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [BasketComponent],
  }).createComponent(BasketComponent);
  const syncService = TestBed.inject(SyncService);
  const spy = spyOn(syncService, 'sync');
  fixture.detectChanges();

  expect(spy).toHaveBeenCalledTimes(1);

  // no change to total, so no effect
  fixture.detectChanges();
  expect(spy).toHaveBeenCalledTimes(2); 
})

We can increase the amount in our basket, and we should see that after another run of the Change Detection, the SyncService should have run two times:

it('should run the SyncService', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [BasketComponent],
  }).createComponent(BasketComponent);
  const syncService = TestBed.inject(SyncService);
  const spy = spyOn(syncService, 'sync');
  fixture.detectChanges();

  expect(spy).toHaveBeenCalledTimes(1);

  const total: HTMLDivElement = fixture.debugElement.query(
    By.css('[data-testid="total"]'),
  ).nativeElement;
  expect(total.textContent).toBe('18');

  fixture.debugElement
    .query(By.css('[data-testid="btn-increase"]'))
    .nativeElement.click();

  fixture.detectChanges();
  expect(spy).toHaveBeenCalledTimes(2);
});

Let's move to another testing type where the Change Detection is unavailable.

Testing without Change Detection

We extract the logic of the BasketComponent into a new Service, BasketService:

@Injectable({ providedIn: 'root' })
export class BasketService {
  products = signal([
    {
      id: 1,
      name: 'Coffee',
      price: 3,
      amount: 1,
    },
    { id: 2, name: 'Schnitzel', price: 15, amount: 1 },
  ]);

  syncService = inject(SyncService);

  constructor() {
    effect(() => this.syncService.sync(this.products()));
  }

  totalPrice = computed(() =>
    this.products().reduce(
      (total, product) => total + product.price * product.amount,
      0,
    ),
  );

  decrease(id: number) {
    this.#change(id, (product) =>
      product.amount > 0 ? { ...product, amount: product.amount - 1 } : product,
    );
  }

  increase(id: number) {
    this.#change(id, (product) => ({ ...product, amount: product.amount + 1 }));
  }

  #change(id: number, callback: (product: Product) => Product) {
    this.products.update((products) =>
      products.map((product) => {
        if (product.id === id && product.amount > 0) {
          return callback(product);
        } else {
          return product;
        }
      }),
    );
  }
}

@Component({
  selector: 'app-basket',
  template: '<!-- template as before -->',
  standalone: true,
  imports: [MatButton, MatIcon],
})
export default class BasketComponent {
  basketService = inject(BasketService);

  products = this.basketService.products;
  totalPrice = this.basketService.totalPrice;

  decrease(id: number) {
    this.basketService.decrease(id);
  }

  increase(id: number) {
    this.basketService.increase(id);
  }
}

We keep the old tests. It now covers the Component and the two Services.

How would a test look like that only covers the BasketService?

We cannot run fixture.detectChanges() anymore because there is no Component and therefore no ComponentFixture.

Testing `computed()`

A test for SignalService that asserts the totalPrice Signal would look like this:

it('should test the BasketService', () => {
  const basketService = TestBed.inject(BasketService);
  expect(basketService.totalPrice()).toBe(18);

  basketService.increase(1);
  expect(basketService.totalPrice()).toBe(21);
});

The test above works. Why? Doesn't the totalPrice require a Change Detection run to become reactive?

Yes, that's true. In our case, though, we don't use totalPrice() in a reactive way. We call it directly.

At any given time, a Signal based on a computed() knows if its dependencies have changed (i.e., it is dirty) and would have to do a re-processing.

To start the re-processing, it waits for somebody to request its value.

In the Component test, the "caller" was the Change Detection. In our test, it was us.

Testing `effect()`

Whereas computed() Signals are simple to test without Change Detection, the real challenge is the effect().

As computed(), the effect() knows internally if it is dirty (one of its dependencies changed its value). Unfortunately, we can't access it like a computed() Signal.

In Angular 16, the only way to test an effect() was to wrap the Service into a "Helper Component". Since Angular 17, we have a new function, which "calls" an effect: TestBed.flushEffects().

Let's see that one in action:

it('should test the BasketService', () => {
  const syncService = TestBed.inject(SyncService);
  const spy = spyOn(syncService, 'sync');

  const basketService = TestBed.inject(BasketService);
  TestBed.flushEffects();

  basketService.increase(1);
  TestBed.flushEffects();
  expect(spy).toHaveBeenCalledTimes(2);
});

Again, we could observe the same behavior as with the Component test. For an effect() to run, two things are necessary:

The effect() needs to be dirty and
there has to be an "active access".

These tests will fail again:

it('should test the BasketService', () => {
  const syncService = TestBed.inject(SyncService);
  const spy = spyOn(syncService, 'sync');
  TestBed.inject(BasketService);

  // effect didn't run
  expect(spy).toHaveBeenCalledTimes(1);
});

it('should test the BasketService', () => {
  const syncService = TestBed.inject(SyncService);
  const spy = spyOn(syncService, 'sync');
  TestBed.inject(BasketService);

  TestBed.flushEffects();
  expect(spy).toHaveBeenCalledTimes(1);

  // effect not dirty
  TestBed.flushEffects();
  expect(spy).toHaveBeenCalledTimes(2);
});

Summary

We must know the "Glitch-free" effect if we test code that uses Signals.

Whenever Change Detection is part of the test, the test behaves in the same way as our application.

For those testing types where the Change Detection is not included, we have to call Signals directly and run TestBed.flushEffects() to execute "dirty side effects".

You can access the repository at https://github.com/rainerhahnekamp/how-do-i-test

If you encounter a testing challenge you'd like me to address here, please get in touch with me!

For additional updates, connect with me on LinkedIn, X, and explore our website for workshops and consulting services on testing.

Professional Angular Testing Workshop | ANGULARarchitects

angulararchitects.io

How do I test using the RouterTestingHarness?

Rainer Hahnekamp — Wed, 06 Mar 2024 16:00:00 +0000

Historically, creating a test involving the routing context without mocking it has been challenging. This is mainly due to less-than-optimal documentation on RouterTestingModule or provideLocationMock.

In the meantime, some community projects, especially Spectacular from @layzee, have helped us out.

Spectacular by ngworkers | Spectacular

Spectacular Angular integration testing. Flexible when you need it. Specialized test harnesses. Faster than end-to-end tests.

ngworker.github.io

This article explains how to use the RouterTestingHarness to write sound tests where we don't have to mock anything from the Router.

If you are more of a visual learner, here's a video for you:

In Angular 16.2, we could fetch router parameters via the @Input. With 17.1, we have Signal Inputs as an alternative in the form of the input function.

Still, the question persists: How do you test it without mocking too much?

The answer has already been available since Angular 15.2. It introduced the RouterTestingHarness. It makes testing with minimal mocking a breeze.

This is the component we want to test:

@Component({
  selector: 'app-detail',
  template: `<p>Current Id: {{ id() }}</p>`,
  standalone: true,
})
export class DetailComponent {
  id = signal(0);

  constructor() {
    inject(ActivatedRoute)
      .paramMap.pipe(takeUntilDestroyed())
      .subscribe((paramMap) => 
        this.id.set(Number(paramMap.get('id') || '0')));
  }
}

The RouterTestingHarness replaces the typical TestBed::createComponent pattern. It creates the component but wraps it inside a "testing routing context".

Harnesses are pretty popular in Angular Material. They are testing helper classes that make testing very convenient by managing parts of asynchronous execution and triggering the change detection.

There is one requirement, though. Harness commands are asynchronous. So we always end up with async/await tests.

For every routing, we require a configuration. It is the same here:

describe('Detail Component', () => {
  it('should test verify the id is 5', waitForAsync(async () => {
    TestBed.configureTestingModule({
      providers: [
        provideRouter([{ path: 'detail/:id', component: DetailComponent }]),
      ],
    });
 }));
});

Next, we instantiate the RouterTestingHarness and use it to navigate to "/detail/5".

const harness = await RouterTestingHarness.create('detail/5');

Internally, our component's subscription to the route runs, and we should already see that the id in the template shows the value 5:

const p: HTMLParagraphElement = harness.fixture.debugElement.query(
  By.css('p'),
).nativeElement;

expect(p.textContent).toBe('Current Id: 5');

We can now even extend our test. For example, we might want to stay at the same route but want to switch to a different id.

No problem with the RouterTestingHarness. For the sake of completeness, here's the full code of the test:

describe('Detail Component', () => {
  it('should test verify the id is 5', waitForAsync(async () => {
    TestBed.configureTestingModule({
      providers: [
        provideRouter([{ path: 'detail/:id', component: DetailComponent }]),
      ],
    });

    const harness = await RouterTestingHarness.create('detail/5');

    const p: HTMLParagraphElement = harness.fixture.debugElement.query(
      By.css('p'),
    ).nativeElement;

    expect(p.textContent).toBe('Current Id: 5');

    await harness.navigateByUrl('detail/6');
    expect(p.textContent).toBe('Current Id: 6');
  }));
});

Please note that we didn't have to trigger the change detection or do anything else when we switched to "/detail/6". The Harness did everything for us internally. The only thing which we must not forget is to use the await.

Testing with the RouterTestingHarness is much better than mocking the ActivatedRouter.

Whenever you mock functions outside your control, like ActivatedRouter, you can never be sure that your mocking behaves precisely as the original.

The original could run asynchronous tasks; it could trigger the change detection or something else internally, which you might not be aware of. There are quite a lot of traps you might fall into.

You better be safe and leave the internal functions to the internal functions 😀.

You can access the repository at https://github.com/rainerhahnekamp/how-do-i-test

If you encounter a testing challenge you'd like me to address here, please get in touch with me!

For additional updates, connect with me on LinkedIn, X, and explore our website for workshops and consulting services on testing.

Professional Angular Testing Workshop | ANGULARarchitects

angulararchitects.io

How do I test code using inject()

Rainer Hahnekamp — Tue, 05 Mar 2024 16:00:00 +0000

This article discusses testing Angular code, which uses the inject function for dependency injection.

If you are more of a visual learner, here's a video for you:

Why `inject`?

The inject function, introduced in Angular 14, is an alternative to the constructor-based dependency injection. inject has the following advantages:

1. Standardization of Decorators

Decorators have existed in an experimental setting within the TypeScript configuration.

While TC39 has completed the standardization of decorators, all decorator types must be finalized to disable the experimental mode of the TypeScript compiler.

Unlike the constructor, the inject function works without parameter decorators, eliminating potential risks for future breaking changes associated with dependency injection via the constructor.

class FlightSearchComponent {
  constructor(
    @SkipSelf() // not standardized
    @Optional() // not standardized
    private flightService1: FlightService
  ) {}

  private flightService2 = inject(FlightService, {
    skipSelf: true,
    optional: true,
  });
}

2. Erased Type in the constructor

The type of inject is also available during runtime. With the constructor, only the variable name survives the compilation. So, the TypeScript compiler has to add specific metadata where type information is part of the bundle. This setting is not the default behavior of the compiler.

// TypeScript
class FlightService {}

class FlightSearchComponent {
  constructor(private flightService: FlightService) {}

  flightService2 = inject(FlightService);
}

// Compiled JavaScript

class FlightService {
}

class FlightSearchComponent {
  // type is gone
  constructor(flightService) { 
    this.flightService = flightService;

    // type is still there
    this.flightService2 = inject(FlightService); 
  }
}

3. Class Inheritance

inject is more accessible for class inheritance. With the constructor, a subclass has to provide all dependencies for its parents. With inject, the parent get their dependencies on their own.

// Inheritance and constructor-based dependency injection

class Animal {
  constructor(private animalService: AnimalService) {}
}

class Mammal extends Animal {
  constructor(
    private mammalService: MammalService,
    animalService: AnimalService
  ) {
    super(animalService);
  }
}

class Cat extends Mammal {
  constructor(
    private catService: CatService,
    mammalService: MammalService,
    animalService: AnimalService
  ) {
    super(mammalService, animalService);
  }
}

// Inheritance via inject

class Animal {
  animalService = inject(AnimalService);
}

class Mammal extends Animal {
  mammalService = inject(MammalService);
}

class Cat extends Mammal {
  catService = inject(CatService);
}

4. Type-Safe Injection Tokens

Injection Tokens are type-safe.

const VERSION = new InjectionToken<number>('current version');

class AppComponent {
  //compiles, although VERSION is of type number
  constructor(@Inject('VERSION') unsafeVersion: string) {} 

  safeVersion: string = inject(VERSION); // fails 👍
}

5. Functional Approaches

Some functional-based approaches (like the NgRx Store) that don't have a constructor can only work with inject.

Because of these many advantages, inject was the rising star. It almost looked like the constructor-based approach might become deprecated.

At the time of this writing, things shifted a little bit. According to Alex Rickabaugh, property decorators are in Stage 1 regarding standardization. That's why he recommends using whatever fits best and waiting for the results of the TC39.

Time Position: 25:25

`TestBed.inject`

Many tests face issues when the application code switches to inject. One of the main issues is the instantiation. With a constructor-based class, a test could directly instantiate the class, but with inject, that is impossible, and we always have to go via the TestBed.

Whenever dealing with a Service/@Injectable, we can call TestBed.inject from everywhere in our test.

That could be at the beginning of the test, in the middle, or even at the end.

We have the following Service, which we want to test:

@Injectable({ providedIn: "root" })
export class AddressAsyncValidator {
  #httpClient = inject(HttpClient);

  validate(ac: AbstractControl<string>): Observable<ValidationErrors | null> {
    return this.#httpClient
      .get<unknown[]>("https://nominatim.openstreetmap.org/search.php", {
        params: new HttpParams()
          .set("format", "jsonv2").set("q", ac.value),
      })
      .pipe(
        map((addresses) =>
          addresses.length > 0 ? null : { address: "invalid" }
        )
      );
  }
}

AddressAsyncValidator injects the HttpClient. So we have to mock that one.

There is no need to import or create a component in our TestingModule.

It is pure "logic testing". The test doesn't require a UI, i.e., DOM rendering.

describe("AddressAsyncValidator", () => {
  it("should validate an invalid address", waitForAsync(async () => {
    TestBed.configureTestingModule({
      providers: [
        {
          provide: HttpClient,
          useValue: { get: () => of([]).pipe(delay(0)) },
        },
      ],
    });

    const validator = TestBed.inject(AddressAsyncValidator);
    const isValid = await lastValueFrom(
      validator.validate({ value: "Domgasse 5" } as AbstractControl)
    );
    expect(isValid).toEqual({ address: "invalid" });
  }));
});

That test will succeed. There are two remarks, though.

First, if AddressAsyncValidator has no {providedIn: 'root'} (only @Injectable is available), we have to provide the Service in the TestingModule:

@Injectable()
export class AddressAsyncValidator {
  // ...
}

describe("AddressAsyncValidator", () => {
  it("should validate an invalid address", waitForAsync(async () => {
    TestBed.configureTestingModule({
      providers: [
        AddressAsyncValidator,
        {
          provide: HttpClient,
          useValue: { get: () => of([]).pipe(delay(0)) },
        },
      ],
    });

    // rest of the test
  }));
});

Second, we cannot run inject inside the test. That will fail with the familiar error message.

NG0203: inject() must be called from an injection context such as a constructor, a factory function, a field initializer, or a function used with runInInjectionContext.

describe("AddressAsyncValidator", () => {
  it("should validate an invalid address", waitForAsync(async () => {
    TestBed.configureTestingModule({
      providers: [
        AddressAsyncValidator,
        {
          provide: HttpClient,
          useValue: { get: () => of([]).pipe(delay(0)) },
        },
      ],
    });

    const validator = inject(AddressAsyncValidator); // not good
  }));
});

`TestBed.runInInjectionContext`

Why would we ever want to run inject in a test? Answer: Whenever we have to test a function which uses inject.

In the Angular framework, that could be an HttpInterceptorFn or one of the router guards, like CanActivateFn.

In the Angular community, we currently see many experiments with functional-based patterns.

A good start might be

nxtensions / nxtensions

Extensions and plugins for Nx

Nxtensions

Nxtensions is a set of plugins and utilities for Nx.

Nx is a smart and extensible build framework. At its core, it offers many great features like:

Project and task graph creation and analysis.
Orchestration and execution of tasks.
Computation caching.
Code generation.

Its core functionality can be further extended with plugins to support frameworks and technologies not supported by the core plugins maintained by the Nx team.

List of packages

@nxtensions/astro: Astro plugin for Nx.
@nxtensions/tsconfig-paths-snowpack-plugin: Snowpack plugin adding support for using path mappings specified in tsconfig files.

Contributing

Interested in contributing? We welcome contributions, please check out our Contributors Guide.

View on GitHub

feat(vite-plugin-angular): enable `.analog` support #870

nartc posted on Jan 26, 2024

PR Checklist

Please check if your PR fulfills the following requirements:

[x] The commit message follows our guidelines: https://github.com/analogjs/analog/blob/main/CONTRIBUTING.md#-commit-message-guidelines
[x] Tests for the changes have been added (for bug fixes / features)
[ ] Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[ ] Documentation content changes
[ ] Other... Please describe:

Which package are you modifying?

[x] vite-plugin-angular
[ ] vite-plugin-nitro
[ ] astro-angular
[ ] create-analog
[ ] router
[ ] platform
[ ] content
[ ] nx-plugin
[ ] trpc

What is the new behavior?

This PR enables support for .analog file extension via the supportAnalogFormat flag under vite.experimental.

This replaces the .ng file extension support. With .analog, the separation is clearer (and intentional). Level of support is around the same as .ng with the following difference:

templateUrl is now supported for external HTML file
styleUrl and styleUrls are now supported for external style file(s)
<style> (for inline style) is now converted to styles property in the Component metadata instead of prepend in the <template> content
- Multiple <style> is not guaranteed. If folks need multiple stylesheet, use styleUrls instead

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

[optional] What gif best describes this PR or how it makes you feel?

View on GitHub

We will stick to native features, though, and test a CanActivateFn:

export const apiCheckGuard: CanActivateFn = (route, state) => {
  const httpClient = inject(HttpClient);

  return httpClient.get("/holiday").pipe(map(() => true));
};

apiCheckGuard is a simple function that verifies if a request to the URL "/holiday" succeeds. There is no constructor in a function. Therefore, apiCheckGuard must use inject.

A test could look like this:

it("should return true", waitForAsync(async () => {
  TestBed.configureTestingModule({
    providers: [
      { provide: HttpClient, useValue: { get: () => of(true).pipe(delay(1)) } },
    ],
  });

  expect(await lastValueFrom(apiCheckGuard())).toBe(true);
}));

That will also not work. We get the NG0203 error again.

The solution is TestBed.runInInjectionContext. As the name says, it allows us to run any function, which will run again in the injection context. That means the inject is active and will work as expected.

describe("Api Check Guard", () => {
  it("should return true", waitForAsync(async () => {
    TestBed.configureTestingModule({
      providers: [
        {
          provide: HttpClient,
          useValue: { get: () => of(true).pipe(delay(1)) },
        },
      ],
    });

    await TestBed.runInInjectionContext(async () => {
      const value$ = apiCheckGuard();
      expect(await lastValueFrom(value$)).toBe(true);
    });
  }));
});

Although it looks like TestBed.runInInjectionContext provides the injection context asynchronously, that is not true.

The guard calls inject synchronously. If it did it in the pipe operator, inject would run in the asynchronous task and again fail.

Summary

inject comes with many advantages over the constructor-based dependency injection, and you should consider using it.

HttpInterceptorFn and router guards are functions and can only use inject to get access to the dependency injection.

To have a working inject, we must wrap those function calls within TestBed.runInInjectionContext.

There is also TestBed.inject, which behaves differently. It is only available in tests and we should use it get instances of classes. Regardless, if those classes use inject or the constructor-based dependency injection.

You can access the repository at https://github.com/rainerhahnekamp/how-do-i-test

If you encounter a testing challenge you'd like me to address here, please get in touch with me!

For additional updates, connect with me on LinkedIn, X, and explore our website for workshops and consulting services on testing.

Professional Angular Testing Workshop | ANGULARarchitects

angulararchitects.io

How do I test and mock Standalone Components?

Rainer Hahnekamp — Mon, 04 Mar 2024 16:00:00 +0000

If you prefer the kind of tests that minimize mocking as much as possible, you will be pretty happy with Standalone Components. Gone are the struggles of meticulously picking dependencies from NgModules for your Component under test.

Standalone Components come self-contained. Add them to your TestingModule's imports property, and all their "visual elements" – Components, Directives, Pipes, and dependencies – become part of the test. As a nice side-effect, you reach a much higher code coverage.

If you are more of a visual learner, here's a video for you:

A Huge Dependency Graph

When we write a test, we check what Services our Component requires. Typical candidates are HttpClient, ActivatedRoute. We need to mock them. That's doable.

Unfortunately, the Components' dependencies also require Services, which - some of them - we also have to provide.

Consider the example of testing the RequestInfoComponent. It contains the following dependencies:

A considerable number of Services derive from RequestInfoHolidayCardComponent. That Subcomponent uses NgRx, which can be a heavy dependency on its own.

Looking at the necessary setup of the TestingModule, there is quite a lot to consider:

const fixture = TestBed.configureTestingModule({
  imports: [RequestInfoComponent],
  providers: [
    provideNoopAnimations(),
    {
      provide: HttpClient,
      useValue: {
        get: (url: string) => {
          if (url === '/holiday') {
            return of([createHoliday()]);
          }
          return of([true]).pipe(delay(125));
        },
      },
    },
    {
      provide: ActivatedRoute,
      useValue: {
        paramMap: of({ get: () => 1 }),
      },
    },
    provideStore({}),
    provideState(holidaysFeature),
    provideEffects([HolidaysEffects]),
    {
      provide: Configuration,
      useValue: { baseUrl: 'https://somewhere.com' },
    },
  ],
}).createComponent(RequestInfoComponent);

Mocking a Component

To improve the situation and still have an impactful test, we only want to mock the RequestInfoHolidayCard. That would free us from quite a lot of Service dependencies:

Third-party libraries, like ng-mocks, provide functions to automate that. We do it manually to understand what's going on under the hood.

We add the code of the mocked Component directly into the test file.

@Component({
  selector: 'app-request-info-holiday-card',
  template: ``,
  standalone: true,
})
class MockedRequestInfoHolidayCard {}

MockedRequestInfoHolidayCard is a simple Component without any dependencies. What it has in common with the original is the selector. So when Angular sees the tag <app-request-info-holiday-card>, it uses the mocked version.

The next step is to import the mock into the TestingModule. With all its dependencies gone, the TestingModule setup slims down quite a bit:


const fixture = TestBed.configureTestingModule({
  imports: [RequestInfoComponent, MockedRequestInfoHolidayCard],
  providers: [
    provideNoopAnimations(),
    {
      provide: HttpClient,
      useValue: {
        get: (url: string) => of([true]).pipe(delay(125))
      },
    }
  ],
}).createComponent(RequestInfoComponent);

Unfortunately, that does not work. The test fails because ActivatedRoute (dependency of RequestInfoHolidayCard) is unavailable.

The reason should be clear. RequestInfoHolidayCard is not part of the imports property of some NgModule but directly of the RequestInfoComponent. Although the mocked version is now part of the TestingModule, the imports from RequestInfoComponent internally override it.

We need to find an alternative solution.

`TestBed::overrideComponent`

Our only chance is to access the imports property of the Component itself. Luckily, there is TestBed::overrideComponent().

A method that perfectly fits our use case. After overriding the imports property of RequestInfoHolidayCard, we configure the TestingModule and proceed with the actual test.

TestBed.overrideComponent(RequestInfoComponent, {
  remove: { imports: [RequestInfoComponentHolidayCard] },
  add: { imports: [MockedRequestInfoHolidayCard] },
});

const fixture = TestBed.configureTestingModule({
  imports: [RequestInfoComponent],
  providers: [
    provideNoopAnimations(),
    {
      provide: HttpClient,
      useValue: {
        get: (url: string) => of([true]).pipe(delay(125)),
      },
    },
  ],
}).createComponent(RequestInfoComponent);

Et voilà, that's much better!

A set instead of add or remove method would override the complete imports, providers, etc.

Again: Please note that I highly recommend using ng-mocks. Mocking Components, Pipes, and Directives with it is way more comfortable.

Summary

Component tests, which include dependencies, give us higher code coverage, and we are also closer to the actual behavior. At the same time, the setup becomes harder.

Partial mocking is a good compromise. With Standalone Components, we must add the mock via TestBed::overrideComponent.

There is also a TestBed::overrideDirective and TestBed::overridePipe for Directives or Pipes.

You can access the repository at https://github.com/rainerhahnekamp/how-do-i-test

If you encounter a testing challenge you'd like me to address here, please get in touch with me!

For additional updates, connect with me on LinkedIn, X, and explore our website for workshops and consulting services on testing.

Professional Angular Testing Workshop | ANGULARarchitects

angulararchitects.io

NgRx Best Practices Series: 4. Facade Pattern

Rainer Hahnekamp — Tue, 08 Aug 2023 13:00:00 +0000

This article covers the Facade pattern in NgRx. The reader must have a basic understanding of NgRx or a similar state management library.

The Facade pattern mainly decouples NgRx from the rest of our application. We can also see it as an API. The Facade masks the dispatching of actions as method calls and the selectors as properties of type Observable.

Next to the decoupling, the facade pattern offers even further advantages.

If you prefer a video over an article, there you go ;)

1. Theory
2. Implementation
3. Advantages
- 3.1. Decoupling
- 3.1.1. Changed Requirements
- 3.1.2. Prepared for more
- 3.1.3. Reversing Overengineering
- 3.1.4. NgRx Component & Signal Store
- 3.2. Built-in Logic
- 3.3. Easier Component Tests
4. Summary

1. Theory

The Facade pattern, sometimes called Repository or API, is an architectural pattern.

We divide our application into different modules and organise them within two layers. The first divides our application into multiple scopes or domains (if you use DDD). Next to the domains, we have the application shell and shared modules.

Every domain holds multiple modules of different types. A typical structure for an NgRx-powered application is the division into feature, data, ui, and model type.

The feature module contains the container components, the ui contains the presentational components, and the data has the NgRx feature state.

Our modules need to support encapsulation and dependency rules. Encapsulation means that we can hide certain elements from the outside. With dependency rules, we can define which modules can access each other.

We must use additional tools since TypeScript does not support modularity out of the box. The author recommends Nx dependency rules or Sheriff. Both come as ESLint plugins.

We apply dependency rules on all two layers. In the first layer, we define that domains cannot talk to each other. If required otherwise, we will add exceptions on an individual basis.

Dependency rules on the second layer, i.e. the domain, follow the module type. Only elements of the feature module can access the data module. The presentational components, part of the ui module, get their data from the container components. The ui module does not have access to the data module.

The model type holds the TypeScript interfaces of the domain models. Since domain models are the ubiquitous language of the domain, every other module of the same domain has access to it.

For more information about architecture and NgRx, check out this article.

The Facade uses the encapsulation feature. We hide all NgRx elements within the data module. These are the reducer, the selectors and the actions. What stays exposed to the public is the actual Facade, and the provider function that creates the NgRx feature state.

In both Nx and Sheriff, modules define their exposed elements in the index.ts. In our case, it could have the following content:

import { provideState } from '@ngrx/store';
import { customersFeature } from '@app/customers/data/customers.reducer';
import { provideEffects } from '@ngrx/effects';
import { CustomersEffects } from '@app/customers/data/customers-effects.service';

export { CustomersFacade } from './customers-facade';

export const provideCustomers = [
  provideState(customersFeature),
  provideEffects(CustomersEffects),
];

2. Implementation

Let's say we have a simple CRUD feature state which manages customers. It has actions for adding, editing, listing, and removing customers. At the same time, it offers two selectors. One returns all customers, and the other finds a customer per id.

We have the following state:

export interface State {
  customers: Customer[];
}

The NgRx actions:

import { createActionGroup, emptyProps, props } from '@ngrx/store';
import { Customer } from '@app/customers/model';

export const customersActions = createActionGroup({
  source: 'Customers',
  events: {
    load: emptyProps(),
    loaded: props<{ customers: Customer[] }>(),
    add: props<{ customer: Customer }>(),
    added: props<{ customer: Customer }>(),
    update: props<{ customer: Customer }>(),
    updated: props<{ customer: Customer }>(),
    remove: props<{ id: number }>(),
    removed: emptyProps(),
  },
});

And finally, the two selectors, where NgRx provides the first one automatically via its createFeature function:

const selectAll = customersFeature.selectCustomers;


const selectById = (id: number) => createSelector(
  selectAll, 
  (state: Customer[]) =>
    state.find((p) => p.id === id)
);


export const fromCustomers = {selectAll, selectById};

Without the Facade, our container components would dispatch actions and select from the state via the Store service.

export class EditCustomerComponent implements OnInit {
  #store = inject(Store);
  protected customers$: Observable<Customer[]> | undefined;

  ngOnInit() {
    this.customers$ = this.#store
      .select(fromCustomers.selectAll());
  }

  submit(customer: Customer) {
    this.#store.dispatch(customersActions.update({ customer }));
  }
}

Now we implement the Facade. It provides methods for the actions we want to make publicly available.

@Injectable({ providedIn: 'root' })
export class CustomersFacade {
  #store = inject(Store);

  update(customer: Customer) {
    this.#store.dispatch(customersActions.update({ customer }));
  }
}

And for the selectors, we expose "read-only properties" in the form of a getter function.

@Injectable({ providedIn: 'root' })
export class CustomersFacade {
  #store = inject(Store);

  get customers$(): Observable<Customer[]> {
    return this.#store.select(fromCustomers.selectAll);
  }

  update(customer: Customer) {
    this.#store.dispatch(customersActions.update({ customer }));
  }
}

We should also limit the number of actions, we want to expose to our container components. An example is the updated action. That is an internal action because only our NgRx Effect dispatches it. CustomersFacade doesn't provide a method for it, so it is unavailable.

export class EditCustomerComponent implements OnInit {
  #facade = inject(CustomersFacade);

  protected customer$: Observable<Customer> | undefined;

  ngOnInit() {
    this.customer$ = this.#facade.customers$;
  }

  update(customer: Customer) {
    this.#facade.update(customer);
  }
}

We see that the component no longer knows that NgRx runs under the hood. From the component's perspective, the CustomersFacade provides an Observable of Customer[]. When it comes to the update, it is a simple method call.

The same is true for all other components or services that use NgRx. We have to refactor them, so that they only use the Facade.

Next, we'll cover why we want this decoupling and what further advantages we get.

3. Advantages

3.1. Decoupling

We don't want to have NgRx everywhere in our codebase. This allows us to switch to another state management library quite easily.

I know many Angular developers (whom I highly respect) who are unhappy with the Facade pattern.

A common argument says that replacing NgRx with another state management library is implausible if we already use it.

Another argument is that the Facade opens the door for anti-patterns. For example, we could have a method which dispatches the action and calls a selector at the same time.

I will discuss the reasons for replacing NgRx in the next chapter.

For the argument about misusing the Facade, it is really up to the discipline and internal code reviews of the development team.
We can overengineer every pattern, but that doesn't mean we shouldn't use it.

3.1.1. Changed Requirements

Requirements for our applications change. It is common that some of the frontend logic moves to the backend or diminishes. If everything we have to do is send a single HTTP request to the API, it is better to slim down our codebase and remove NgRx for that feature.

With a Facade, we could replace NgRx under the hood with a BehaviorSubject. Our components don't have to change at all. Everything is fine as long as the Facade returns the same Observables and the methods keep their signature.

The Facade also allows us to mix simple HTTP requests with NgRx. Let's say there is some data in our domain which doesn't need state management. The Facade could still provide it as a normal property of type Observable. Instead of calling a selector, it triggers an HTTP request.

Summarised, the Facade gives us the flexibility to change with dynamic requirements efficiently.

3.1.2. Prepared for more

Especially teams, who start to learn Angular and use NgRx immediately, can be overwhelmed or even intimated by NgRx.

If those teams decide to postpone the usage of NgRx, there is a high chance that they will miss the point where they have to integrate it. They'll end up with a self-written state management library. That's a liability. They must fix bugs, maintain and extend it. We don't want to be in this position.

The Facade helps here as well. It uses a BehaviorSubject internally first. When the time comes to change, just replace that BehaviorSubject with NgRx.

Again, this change only needs to happen inside the data module. The components and services are unaffected.

The Facade works here as some kind of insurance. It is definitely worth the investment.

3.1.3. Reversing Overengineering

The opposite can happen as well. Teams with little NgRx experience might overuse it. The Facade helps here in the same way as it did in the other extreme.

3.1.4. NgRx Component & Signal Store

In my opinion, we rarely switch to another library for state management once we go with NgRx.

Nevertheless, NgRx has meanwhile created its own competition.
According to the official download statistics, the NgRx Component Store is already in place 2. One can see the Component Store as a "lightweight Global Store".

Because of that, many developers are considering the switch to the Component Store. The third self-made contender is the Signal Store, built with Signals in mind.

Given the two alternatives in the NgRx ecosystem, moving away from the Global Store is no longer uncertain.

You know already what comes next ;).

The Facade is the universal remedy for those scenarios as well. When you switch to the Signal Store, your properties will return a Signal instead of an Observable. Given that the Global and Component already supports signal-based selectors, this change is relatively easy.

3.2. Built-in Logic

A Facade doesn't just have to hide NgRx. It could also add logic, which would be impossible with native NgRx.

In our current application, container components need to call the load method of the CustomersFacade. It dispatches an action to fetch the data from the backend.

If more components depend on loaded customers, every component would have to call load.

Therefore, implementing a "loading on-demand" feature in NgRx is impossible. A selector cannot dispatch an action. But our Facade can.

The Facade must track if it has already dispatched the load action once. Since the properties of our CustomersFacade are getters (function with get prefix), we could place that check directly into it:

export class CustomersFacade {
  #isLoaded = false;
  #store = inject(Store);

  get customers$(): Observable<Customer[]> {
    this.#assertLoaded();
    return this.#store.select(fromCustomers.selectAll);
  }

  byId(id: number): Observable<Customer | undefined> {
    this.#assertLoaded();

    return this.#store.select(fromCustomers.selectById(id));
  }

  #assertLoaded() {
    if (!this.#isLoaded) {
      this.#store.dispatch(customersActions.load());
      this.#isLoaded = true;
    }
  }
}

With that version, no component needs to call the load method anymore. Our Facade could even remove it.

We find another attractive option in extending the possibilities of selectors.

An NgRx's Store select method returns an Observable that synchronously emits the first value. It is not possible to add pipe operators to the selector (what createSelector returns) itself.

Still, we want to clone the state to have protection against mutable changes. Another requirement is that we want to filter out values of undefined.

Without the Facade, our components must deal with a potential undefined and ensure they don't apply mutable changes. The reason is obvious. They are the ones that run store.select() and therefore get the Observable.

Facade to help! It returns already an Observable and can therefore add pipe operators to it.

Let's say we want that byId doesn't return an Observable<Customer | undefined> but Observable<Customer>. We also want to clone the value because we use a template-driven form which does mutable changes.

Our improved version of the CustomersFacade would look like this:

@Injectable({ providedIn: 'root' })
export class CustomersFacade {
  #isLoaded = false;
  #store = inject(Store);

  byId(id: number): Observable<Customer> {
    this.#assertLoaded();

    return this.#store
      .select(fromCustomers.selectById(id))
      .pipe(filterDefined, deepClone);
  }
}

filterDefined and deepClone are custom operators.

3.3. Easier Component Tests

If we want to test a component that uses NgRx, we have quite handy testing utilities. For example, the provideMockStore provides a fully functional but stubbed NgRx feature state.

A test for a component which lists all customers might look like that:

it('should show customers', () => {
  const fixture = TestBed.configureTestingModule({
    imports: [CustomersContainerComponent],
    providers: [
      provideRouter([]),
      provideMockStore({
        initialState: {
          customers: {
            customers: [
              {
                firstname: 'Sabine',
                name: 'Miscovics',
                country: 'AT',
                birthday: '1993-05-09',
              },
            ],
          },
          currentPage: 1,
          pageCount: 1,
        },
      }),
    ],
  }).createComponent(CustomersContainerComponent);
  fixture.detectChanges();

  expect(
    document
      .querySelector('[data-testid=row-customer] p.name')
      ?.innerHTML.trim()
  ).toBe('Sabine Miscovics');
});

What's the issue with provideMockStore?

In our component test, we must know the feature state's structure. One of the ideas behind selectors is to hide that from our components. Now we have it right in our tests back again. We also need to know the feature's key. That's why we have two times the property customers.

In this type of test, we only want to test the component and don't deal with NgRx.

Again, the Facade can help. If we want to mock NgRx, we only need to mock a simple service. We can even make use of the common mocking libraries (testing-library, ng-mocks, [jest|jasmine]-auto-spies, ts-mockito) for further simplification:

it('should show customers', () => {
  const facadeMock: Partial<CustomersFacade> = {
    get customers$(): Observable<Customer[]> {
      return of([
        {
          id: 1,
          firstname: 'Sabine',
          name: 'Miscovics',
          country: 'AT',
          birthdate: '1993-05-09',
        },
      ]);
    },
  };
  const fixture = TestBed.configureTestingModule({
    imports: [CustomersContainerComponent],
    providers: [
      provideRouter([]),
      { provide: CustomersFacade, useValue: facadeMock },
    ],
  }).createComponent(CustomersContainerComponent);
  fixture.detectChanges();

  expect(
    document
      .querySelector('[data-testid=row-customer] p.name')
      ?.innerHTML.trim()
  ).toBe('Sabine Miscovic');
});

We use facadeMock as mock for the CustomersFacade. It only returns the Observable<Customer>, which is everything we need in this test.

We don't have to know about the feature state's structure, the feature key, or that we use NgRx.

4. Summary

The Facade is a pattern which is easy to implement but very powerful in its possibilities. We just have to replace a dispatched action with a method call, and the selectors become a property with an Observable to the outside.

Decoupling NgRx from the rest of our application is the main advantage. The Facade significantly reduces the amount of work when we want to replace NgRx.

We can also add logic or additional features to our Facade, which is not possible with plain NgRx.

Examples are adding pipe operators to our selectors or developing an on-demand loading mechanism for our entities.

Last, we also end up with easier tests. We don't need to learn and use the utility testing methods that NgRx offers to mock a feature state. We only have to mock the Facade, as with any other Service mock.

The Facade looks like an overengineered pattern at first sight. It is not. It is a pattern that offers a lot of advantages with minimal effort. You should give it a try!

You can find a Github repository containing all possible variations in Angular 16.

rainerhahnekamp / ngrx-facades

Repository demonstrating the advantages of the facade pattern in NgRx

This is the accompanying repository for the video on NgRx Facades on

View on GitHub

If you are interested in more content about NgRx, you might want to join one of our upcoming Professional NgRx workshops:

🇺🇸 English Workshops:

Professional NgRx: Angular State Management Workshop | ANGULARarchitects

angulararchitects.io

🇩🇪 German Workshops:

Professional NgRx: Angular State Management Schulung | ANGULARarchitects

angulararchitects.io

What is your opinion? Do you think the Facade can be a benefit to your application? Maybe you use the Facade already. Did you find you find further use cases for it?

Let me know in the comments!

Angular Testing in 2023 - Past, Present, and Future

Rainer Hahnekamp — Tue, 06 Jun 2023 06:00:32 +0000

Angular 16 has deprecated Karma and introduced Jest in experimental mode. Does that mean we currently have no stable testing framework? Should we switch to Jest? What's wrong with Karma in the first place?

If you prefer watching a video over reading, that's for you:

In this article, I want to answer these and more questions.

First, let's take a look at the pre-Angular 16 situation. I will cover the differences between Jest and Jasmine and explain the role of Karma. Then we'll dive into Jest and discuss why the current community-based solutions could be more optimal. Finally, we'll look into the future and see what Angular brings to the table.

Angular Testing Landscape

Roughly speaking, we use two different types of frameworks to test our Angular applications: one for unit/component tests and another for E2E testing. We use frameworks like Cypress, Playwright, or some Webdriver derivatives like Selenium or WebDriverIO for the latter.

When it comes to component testing, there are some overlaps because Cypress also supports it.

For the unit/component tests, we use Jasmine or Jest. The official support of the Angular CLI has always been Jasmine. If we wanted to switch to Jest, we usually went with Nx or used the builder from just-jeb/angular-builders.

Jest or Jasmine?

In Angular, Jasmine always comes together with Karma. Karma serves as a vehicle for Jasmine, which embeds the tests in the browser. The browser context has the advantage that the tests have access to the Web API and everything else a browser offers. On the other hand, the browser adds some overhead.

Jest offers an alternative. We can find the origins of Jest at Facebook. They forked Jasmine and improved it in terms of performance.

Instead of a browser, Jest uses jsdom, an emulator providing a DOM with parts of the Web API that allows us to select and interact with the DOM itself. Due to the emulator, the overhead is much smaller compared to a real browser. On the other side, we have limited functionality available. For example, we cannot play music via the audio tag or store something in local storage. In most cases, though, that's different from what we want to do in tests.

Additional "power features" are built-in parallelisation and an excellent watch mode. The watch mode only executes tests that are affected by the current changes. If we had 10,000 tests, but our recent changes affect only 10 of them, Jest runs only them.

These features made Jest the dominating testing framework, not just in Angular but more or less in the whole JavaScript land.

Jest's weakness: ES Modules

Unfortunately, in the last few years, we saw some strange error messages like "import is not defined" and experienced a considerable drop in performance.

It turned out that Jest's integration into Angular was not on the same level as Jasmine's. Jest needs to do the compilation on its own. So it gets the source code of our tests and compiles it down to JavaScript in the case of Angular.

The Angular compiler, which runs on top of the TypeScript compiler, is responsible for that. It knows about all the metadata and what that means for the final code.

How does it work in Jest? The secret sauce is the jest-angular-preset project. It holds all the logic, and the Nx and just-jeb/angular-builders depend on it.

Unfortunately, jest-angular-preset doesn't fix all issues regarding the Jest build process.

Entering ECMAScript Modules or ESM. It is the official standard for loading JavaScript files and, in a way, the successor to CommonJS (CJS). Many third-party libraries jumped onto the ESM train and exclusively published in that format. Angular especially pushed their libraries to produce ESM format only.

Jest was caught flat-footed. It only understood the old CJS. Compiling our test and application code down to CJS wasn't much of an issue for Jest. The problem lies within the node_modules directory, especially in Angular and its libraries, which are not in CJS anymore.

Jest had to transpile this massive amount of code from ESM to CJS. That significantly slowed down Jest. So it shouldn't be surprising that Jasmine - where Angular is responsible for the build - suddenly outperformed Jest.

Additionally, it also turned out that just one person is responsible for Jest's development. Facebook/Meta last contributed code a few years ago. So Simen Bekkhen had to keep Jest together all alone. And if things were not already bad enough, he got frustrated with the standardisation process of ESM and took some time off.

Let's move forward to today. Jest is now part of the OpenSource Foundation and has many contributors. Simen is working on an ESM support for Jest. It is still experimental, but the Angular community plugins use it already by default.

The situation is much better. Nevertheless, there are still some chances of falling into a performance trap. Tomas Trajan dedicated a whole article to that problem.

Experimental Jest Mode in the Angular CLI

Let's come to the present. We see that Jest is recovering, catching up to its old form…and suddenly, the Angular team steps in.

The Angular Developer survey showed that there is room for improvement in testing. So, looking at the testing landscape, the Angular team decided to support Jest officially.

At the moment, this is in experimental mode. We can try it out, but we shouldn't expect too much. The experimental mode is not on the same level as the developer preview we've seen in Angular 14 for Standalone Components. We should see it more as a proof of concept.

The official Jest integration will not go the path of Nx & Co. Jest will no longer be responsible for the build. Angular takes over.

That means Jest gets a bunch of *.mjs files. There is no need to traverse through node_modules, transpiling, etc. Instead, Jest can start with the execution right away.

And that's not all of it. For example, Angular uses the brand-new esbuild instead of webpack. Esbuild is said to outperform Webpack in some situations by 50-100x times. It has also proven itself multiple times. For example, Vitest and Vite use it internally. They are both known for their performance, which they get from esbuild.

So we can say that the current status of testing in Angular looks like this:

Switching over to Jest

Here is how you can try it out.

Open your angular.json and replace the builder in test, which should have the value @angular-devkit/build-angular:karma to @angular-devkit/build-angular:jest.
Install the necessary dependencies via npm install -D jest @types/jest jest-environment-jsdom.
Locate the tsconfig.spec.json and replace the value jasmine in the property types with jest.

Now just execute npx ng test. You should see that the Angular builder created a test-out folder in dist, which your test files with mjs as the file extension. This is the location where Jest runs.

You don't want to use it in production yet. Jest's watch mode is unavailable, your IDE will not run the tests, and you cannot customise Jest via a jest.config.ts.

Jasmine and ModernWeb

What about the deprecation of Karma? Karma's task is to start a browser and embed the Jasmine tests. So the deprecation of Karma doesn't mean that Jasmine is deprecated.

Furthermore, in Angular 16, Karma is still fully functional. So your existing tests will still work as they used to.

In a future release, Angular will replace Karma with the web-test-runner from ModernWeb. That future release might already be Angular 17. ModernWeb is a modern community project that embeds tests into a browser.

The switch from Karma to ModernWeb might even go unnoticed. There should be nothing left for us to do. But let's see if it really turns out that way ;)

The more interesting question is why?

Karma has been there since Angular 1 (AngularJs). Misko Hevery, also known as the "father of Angular", was the co-author, and Karma was more or less exclusively for Angular.

Quite some time has passed since AngularJs and the ecosystem evolved. With community projects like web-test-runner, there is no need for the Angular team anymore to stick to Karma.

The predictable future of testing Angular would therefore provide a combination of Jasmine/WebTestRunner (ModernWeb) and Jest.

Summary

In 2023, Angular made huge steps forwards with Signals and Hydration. In terms of testing, Angular is picking up speed as well. It will integrate Jest so that Angular provides the entire build, and Jest just needs to execute those tests. In the current community solutions, Jest also had to build it, which caused some problems in the past.

Jasmine will stay a support testing framework. However, it will get modernised in the way that the web-test-runner and not Karma provides the Browser context.

Good things are happening in Angular wherever we look!

You can find a Github repository containing all possible variations in Angular 16.

rainerhahnekamp / angular-testing-status

Monorepo showcasing the current status of testing in Angular (16)

Monorepo showcasing the current status of testing in Angular (16).

You can find the full article on Angular Testing in 2023 – Past, Present, and Future https://www.rainerhahnekamp.com/en/angular-testing-in-2023-past-present-and-future/

And if you prefer a video over an article, there you go:

View on GitHub

If you are interesting in more content about testing, you might want to join one of our upcoming testing workshops:

🇩🇪 German Workshops:

Professional Angular Testing Schulung | ANGULARarchitects

angulararchitects.io

🇺🇸 English Workshops:

Professional Angular Testing Workshop | ANGULARarchitects

angulararchitects.io

Type-Safe TypeScript with Type Narrowing

Rainer Hahnekamp — Fri, 28 Oct 2022 19:27:51 +0000

1. Introduction
2. Equality Narrowing
3. typeof
4. Truthiness Narrowing
5. instanceof
6. Discriminated Union
7. in Type Guard
8. Type Predicate
9. Type Narrowing against unknown
- 9.1. Manual Validation
- 9.2. Automatic Validation: zod
10. Assertion Functions
11. Summary

This article shows common patterns to maximize TypeScript's potential for type-safe code. These techniques are all part of the same group, which we call type narrowing.

The source code can be found on: https://github.com/rainerhahnekamp/type-safe-typescript-with-type-narrowing

If you prefer a video over an article, then this is for you:

1. Introduction

Whenever we deal with a variable that can be of multiple types, like an unknown or a union type, we can apply type narrowing, to "narrow" it down to one specific type. We work together with the TypeScript compiler because it understands the context of our code and guarantees that this narrowing happens in a fully type-safe way.

Let's say we have a function with a parameter of type Date | undefined. Every time the function executes, the variable's type can either be Date or undefined, but not both types at the same time.

function print(value: Date | undefined): void {}

If we apply an if condition, checking if that variable is not undefined, TypeScript understands its meaning and treats the value inside the condition only as a string. This is type narrowing.

function print(input: Date | undefined): void {
  if (input !== undefined) {
    input.getTime(); // 👍 value is only Date
  }

  input.getTime(); // 💣 fails because value can be Date or undefined
}

There is also a very similar technique which is called type assertion. It looks like the easier option at first sight. In terms of type-safety though, it is not. We manually set the type and therefore overwrite the compiler.

If the compiler could speak to us, it would say something like: "OK, you know what you are doing there, but don't blame me if something goes wrong."

Therefore we should avoid type assertion and always favour type narrowing. (And in general: trying to be smarter than the compiler is never a good idea.)

function print(input: Date | undefined): void {
  (input as Date).getTime(); // type assertion - don't!
}

After this short introduction, let's come up with an example where we see the major type narrowing techniques in action.

This will be our "workbench":

declare function diffInYears(input: Date): number;
declare function parse(input: string): Date;

function calcAge(input: Date | null | undefined): number {
  return diffInYears(input); // will not work
}

calcAge, should return - as the name says - the age.

Additionally, we use the two utility functions diffInYears and parse. For simplicity, the snippet doesn't show their implementation.

The type of input in calcAge can be of three different types. The return statement will therefore fail to compile.

2. Equality Narrowing

An obvious start would be to check if input doesn't have the value null and undefined. If that's the case, then it can only be a Date.

If we add this condition, TypeScript understands it and treats input inside the if-block as Date and we can safely call diffInYears.

This "implicit understanding" of TypeScript is already our first type guard and it is called "Equality Narrowing".

function calcAge(input: Date | null | undefined): number {
  if (input !== null && input !== undefined) {
    return diffInYears(input);
  }
}

Please be aware, that the if condition is not a direct check for the type undefined or null. It runs against the value. In the same way, we would not be able to write a type check against a Date: value === Date. Date is the type of input and not its value.

So why can we use undefined and null then? The answer is quite obvious. The type undefined has just one value, which is 'undefined'. And the same is true for null. The type null can only have one value, and that is 'null'.

So what our condition really does, is that it is excluding all possible values that can come for undefined or null. For obvious reasons, we don't want want to exclude all possible values for type Date :)

3. `typeof`

Let's try another type guard. JavaScript provides typeof which we can place in front of any variable. As the name says, it will return the name of the variable's type as string… well not really. Otherwise we would have already reached the end of this article :).

In JavaScript, we have seven primitive types and the rest is just of type object. The primitive types are boolean, string, number, undefined, null, bigint, and symbol.

typeof returns the name of every primitive type, except for null. For null it returns 'object'. So one could assume that for null and any non-primitive type, we would get 'object'. But there is a second exception. typeof also returns 'function', if the variable is actually a function or if you pass the name of a class. Strictly speaking function is not a real type, it is a callable object.

With that knowledge, would the following code work?

function calcAge(input: Date | null | undefined): number {
  if (typeof input === "object") {
    return diffInYears(input);
  }
}

No. Since typeof returns for null also 'object' the compilation will fail. So for now, we don't have any use for the typeof type guard, but let's keep it in mind. We might need it later.

4. Truthiness Narrowing

JavaScript invented two new English terms. Falsy and Truthy. If we put a falsy value into a condition, it will return false and true for a truthy value. There is an exhaustive list of falsy values in JavaScript. They are false, 0, 0n, '', null, NaN, and undefined.

We could use that to our advantage. If we put only the input into the if condition, it would be true if the value is not undefined or null. In our case, this is very similar to the equalness operator but just shorter.

function calcAge(input: Date | null | undefined): number {
  if (input) {
    return diffInYears(input);
  }
}

We missed one tiny bit here. If the value is an empty string, it would also be false and we would not end up inside the if-condition. But that's OK for our use case, as long as we are aware of it.

Let's make our example more interesting. We add a fourth possible type which is a string. This is now the time where the typeof enters the game.

First, we get rid of the possibility that the value is null or undefined via truthiness narrowing and return the value 0 (we'll improve that later).

Then it is only between Date and string. And here we can use typeof to check if input is a string. If not, it can only be Date. Perfect!

function calcAge(input: Date | null | undefined | string): number {
  if (!input) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else {
    return diffInYears(input);
  }
}

5. `instanceof`

There is also a possibility for type narrowing when we deal with classes. For that purpose, let's add a class Person, which has a property birthday of type Date.

class Person {
  birthday = new Date();
}

function calcAge(input: Date | null | undefined | string | Person): number {
  if (!input) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else {
    return diffInYears(input); // failure: can be Date or Person
  }
}

Obviously,the last return in the else clause will fail because input can be of type Date or Person. The good message is though, that both are actually class instances and we can use instanceof.

instanceof returns true if a value is an instance of a particular class. So if we add a condition with a check for class Date, we are on the type-safe side again:

function calcAge(input: Date | null | undefined | string | Person): number {
  if (!input) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else if (input instanceof Date) {
    return diffInYears(input);
  } else {
    return diffInYears(input.birthday);
  }
}

Be aware that instanceof returns true for the whole class inheritance chain. So if Person would extend from class Entity, instanceof Entity would also return true.

6. Discriminated Union

We use classes quite often, but more often we deal with object literals or - put in TypeScript jargon - interfaces or types.

Check out the slightly modified example:

type Person = {
  birthday: Date;
  category: "person";
};

type Car = {
  yearOfConstruction: Date;
  category: "car";
};

function calcAge(
  input: Date | null | undefined | string | Person | Car
): number {
  if (!input) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else if (input instanceof Date) {
    return diffInYears(input);
  } else {
    return diffInYears(input.birthday); // Person | Car
  }
}

Ouch, again a compilation error. Can't we just use instanceof here as well? No. Person and Car are both only a type which is an element that only exists in TypeScript. When it is transpiled to JavaScript the definition of Person and Car is not there anymore. Classes, on the other hand, do also exist in JavaScript. That's why instanceof works for them.

Okay, so what can we do?

We are in a kind of lucky position. Both Person and Car share the same property category and each has a distinct value. By verifying if category has the value "car", TypeScript is smart enough to understand that it can only be of type Car. For Person the value would be 'person' obviously. The name of this type guard is "discriminated union". Let's fix our code again:

function calcAge(
  input: Date | null | undefined | string | Person | Car
): number {
  if (!input) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else if (input instanceof Date) {
    return diffInYears(input);
  } else if (input.category === "Car") {
    return diffInYears(input.yearOfConstruction);
  } else {
    return diffInYears(input.birthday);
  }
}

We don't need to call the property for the discriminator category. We can pick whatever name we want.

7. `in` Type Guard

Consider the case where we are not so lucky to have a property that we can use as a discriminator value:

type Person = {
  birthday: Date;
};

type Car = {
  yearOfConstruction: Date;
};

function calcAge(
  input: Date | null | undefined | string | Person | Car
): number {
  if (!input) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else if (input instanceof Date) {
    return diffInYears(input);
  } else if (input.category === "Car") {
    return diffInYears(input.yearOfConstruction);
  } else {
    return diffInYears(input.birthday);
  }
}

In such a case, we can make use of the in type guard. With in we can request, if an object has a certain property or not. So if it is between Person and Car, and the property birthday is present, the type can only be Person.

type Person = {
  birthday: Date;
};

type Car = {
  yearOfConstruction: Date;
};

function calcAge(
  input: Date | null | undefined | string | Person | Car
): number {
  if (!value) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else if (input instanceof Date) {
    return diffInYears(input);
  } else if ("birthday" in input) {
    return diffInYears(input.birthday);
  } else {
    return diffInYears(input.yearOfConstruction);
  }
}

8. Type Predicate

Our next type guard is not a real type guard in that sense, it is some kind of a compromise.

First, let's replace the type Car with a type PersonJson. It has also a property birthday but it is of type string.

We could get away with it by typeof value.birthday === 'string'. This a combination of the typeof and the discriminated union type guard:

type Person = {
  birthday: Date;
};

type PersonJson = {
  birthday: string;
};

function calcAge(
  input: Date | null | undefined | string | Person | PersonJson
): number {
  if (!input) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else if (input instanceof Date) {
    return diffInYears(input);
  } else if (typeof input.birthday === "string") {
    return diffInYears(parse(input.birthday));
  } else {
    return diffInYears(input.birthday);
  }
}

This code compiles and everything looks alright, but it is not perfect. If we would assign input to a new variable inside the last else if statement, we would see that TypeScript identifies the type not as PersonJson but as Person | PersonJson.

This is the point in time, where we reached the limits of TypeScript. Fortunately, it doesn't mean game over.

Whenever TypeScript runs out of options, it gives us the possibility to come up with a function that contains validation code for a particular type.

In a way, this is a compromise. We can write whatever we want in that function, as long as we return true or false. TypeScript will trust us.

This special function is called "type predicate" and for Person it looks like that:

function isPerson(value: Person | PersonJson): value is Person {
  return value.birthday instanceof Date;
}

Please note the special notation where we normally have the return type.

We use the predicate as any other function and place it into the last else if condition:

type Person = {
  birthday: Date;
};

type PersonJson = {
  birthday: string;
};

function isPerson(value: Person | PersonJson): value is Person {
  return value.birthday instanceof Date;
}

function calcAge(
  input: Date | null | undefined | string | Person | PersonJson
): number {
  if (!input) {
    return 0;
  } else if (typeof input === "string") {
    return diffInYears(parse(input));
  } else if (input instanceof Date) {
    return diffInYears(input);
  } else if (isPerson(input)) {
    return diffInYears(input.birthday);
  } else {
    return diffInYears(parse(input.birthday));
  }
}

9. Type Narrowing against `unknown`

With type predicates, we could even deal with variables of type unknown. Everything it takes, is to apply an if condition with the type predicate and voilà, problem gone.

But we have to be careful and shouldn't trick ourselves. The type narrowing is only as good as our validation logic.

If we would have a value of type unknown and we would like to verify if that has the "shape" of Person we would have to come up with a better code than the one we used before. By "shape", we mean any object literal or instance which has a property of birthday: Date.

9.1. Manual Validation

A type-safe type predicate would look like this:

function isPerson(value: unknown): value is Person {
  return (
    typeof value === "object" &&
    value !== null &&
    "birthday" in value &&
    (value as { birthday: unknown }).birthday instanceof Date
  );
}

What a huge amount of code! Unfortunately, it is necessary if we want to be full type-safe.

The function shows another limitation of TypeScript's capabilities. Although we checked that birthday is a property of value, we still have to apply type assertion in the last condition to check if birthday is of type Date.

We can expect that over time TypeScript's limitations become less but at the moment it is what it is.

9.2. Automatic Validation: zod

We stay with type narrowing against the unknown type. Depending on the application type, we might quite often have to deal with the unknown type. Clearly, we don't want to write these huge type predicates all the time on our own. It takes quite a lot of precious time away.

Fortunately, it doesn't have to be like that. There are special libraries that do the validation automatically.

One of the most popular ones is "zod".

For every type, we have to come up with a schema first. This means we programmatically define the type and store it into a variable. So the schema information is also present during the runtime.

The generated schema is then used inside of a type predicate to validate if a value is of that type or not.

With zod, our isPerson would look like that:

const personSchema = z.object({
  birthday: z.date(),
});

type Person = z.infer<typeof personSchema>;

function isPerson(value: unknown): value is Person {
  return personSchema.safeParse(value).success;
}

First, we define the schema and store it under personSchema. With an existing schema, we can ask zod to generate the type automatically for us. This works with z.infer. This simplifies things and also makes sure that we don't have double work when we change the Person type.

Last, we use the method safeParse which doesn't throw an error, if the value is not of type Person. It returns the result via the success property.

This is way much better than writing validation code manually all the time.

10. Assertion Functions

The last feature which is not a type guard, but comes in very handy, is the assertion function.

We return the number 0 in the first condition, when the type is unknown, null, or an empty string.

Returning number 0 is one way how to do it. The alternative is to throw an error.

If we throw an error, TypeScript's type narrowing will exclude undefined or null from the rest of the function's code.

An assertion function is a special function which does exactly do that. If we call it, it will - similar to the type guard - narrow down the parameter but it doesn't return a boolean. It guarantees us that it throws an error, if the value is not of the specific type.

Dealing with types that should not be undefined or null is so common, that TypeScript even provides a special type utility. It goes under the name NonNullable<T>. This type utility means, whatever type T is, it is not undefined or null. Let's see how NonNullable<T> and the assertion function work in action:

function assertNonNullable<T>(value: T): asserts value is NonNullable<T> {
  if (value === undefined || value === null) {
    throw new Error("undefined or null are not allowed");
  }
}

function calcAge(
  input: Date | null | undefined | string | Person | PersonJson
): number {
  assertNonNullable(input);

  if (typeof input === "string") {
    return diffInYears(parse(input));
  } else if (input instanceof Date) {
    return diffInYears(input);
  } else if (isPerson(input)) {
    return diffInYears(input.birthday);
  } else {
    return diffInYears(parse(input.birthday));
  }
}

One final question must be allowed: When we throw an error, why don't we just remove them from the parameter's union type in the first place? Like function calcAge(value: Date | string | Person | PersonJson): number {}?

Well, because the caller might force us to include it. For example, in Angular, a form's input value is undefined when it is disabled. So we could of course say, that our program logic doesn't allow an undefined because we didn't provide a disable function. Nevertheless, the type of our form library has it and that's why it is among the parameter's types.

11. Summary

This article showed various techniques to deal with union types and how to narrow them down to one specific type. TypeScript is able to validate these patterns which means we are not trying to outsmart the compiler but produce code which is as much type-safe as possible.

We should always try to favour type narrowing over type assertion. It means more effort but we don't have to sacrifice type-safety.

Type-safety is actually the main reason, why we use TypeScript over JavaScript. We want to get as much type-safety as possible. From that perspective, the proper usage of type narrowing is the most important TypeScript skill for an application developer.

Ng-News: Episode 22/42

Rainer Hahnekamp — Tue, 25 Oct 2022 13:05:54 +0000

This and all future episodes of ng-news are available on

ng-newsFollow

The latest updates from the Angular community in 100 seconds every week.

I would be grateful, if you follow that channel as well.

Thanks,
Rainer

Forem: Rainer Hahnekamp

Angular's Testing Revolution: Vitest, Fake Timers & Testronaut

How Zone.js-testing "worked"

Zoneless testing

⏱ Alternatives in Vitest (and Jest)

Careful with Promises

A Better Way

Playwright CT Reloaded

My favorite Angular Setup in 2025

Reactivity: Go for Signals

Angular CLI Over Nx

Angular Material + Tailwind

Testing: Jasmine/Karma and Playwright

Code Guidelines: ESLint, Prettier, Husky, Lint-Staged & Sheriff

angular-eslint / angular-eslint

✨ Monorepo for all the tooling related to using ESLint with Angular

Angular ESLint

Contents

Quick Start

lint-staged / lint-staged

🚫💩 — Run tasks like formatters and linters against staged git files

🚫💩 lint-staged

Table of Contents

Why

State Management: SignalStore

inject over constructor

Schematics

Zoneless & OnPush

SSR, Hydration, and Incremental Hydration

Final Notes: Tools and Preferences

Outlook for 2025

rainerhahnekamp / angular-starter

A starter project for a modern Angular application

Angular Project Setup

Installation

UI

Testing

Code Quality

Angular's effect(): Use Cases & Enforced Asynchrony

Signals Primer

computed() or effect(): A Matter of Style?

The Case for effect()

Examples for side effects

Examples with asynchronous Signal updates

effect()'s Achilles' Heel: Enforced Asynchrony

The Reset Pattern

Summary

Which @angular/* package(s) are relevant/related to the feature request?

Changelog

Description

Proposed solution

Alternatives considered

How do I test Signal & Model Inputs?

Signal Inputs

Testing Signal Inputs

The "Wrapper Component"/"Host Component" pattern

Why the "Wrapper Component"?

Model Inputs

Summary

How do I test Signals (signal, computed, effect)?

Signals & Reactivity in a nutshell

Component under Test

Testing with Change Detection

Testing computed()

Testing effect()

Testing without Change Detection

Testing computed()

Testing effect()

Summary

How do I test using the RouterTestingHarness?

How do I test code using inject()

Why inject?

TestBed.inject

TestBed.runInInjectionContext

nxtensions / nxtensions

Extensions and plugins for Nx

Nxtensions

List of packages

Contributing

PR Checklist

`inject` over constructor

Testing `computed()`

Testing `effect()`

Testing `computed()`

Testing `effect()`

Why `inject`?

`TestBed.inject`

`TestBed.runInInjectionContext`

`TestBed::overrideComponent`

3. `typeof`

5. `instanceof`