DEV Community: Juliano

Building recursively nested @angular reactive forms: a clean approach

Juliano — Sat, 13 Jun 2020 20:50:59 +0000

The use case

Side Note: this post was inspired by this StackOverflow question

Let's talk about the below behavior:

If you look carefully at the above animated gif you'll notice 2 important things about the displayed form behavior:

It's dynamically created
It can be recursively nested indefinitely

A static image will help us to better understand the scenario:

I've highlighted some repeating parts on the form above. The red parts are very interesting, so take your time looking at them. Have you notice something with them? It's recursively nested. You can see that Group 2 has a Nested Group 1 inside it and both of them are structurally identical. In fact, Group 2 and the Nested Group 1 have the same elements: conditions and the same action buttons bar.

How would we build up a dynamically, recursively nested form like the one shown in the image above? What if we want to create and fill-up the form based on some data you load from a server? Keep reading and we'll get there in a minute.

The complete code discussed here is available at Stackblitz.com:

The pseudo component tree

We'll build the following structure (in this "pseudo component tree" each label started with app represents an angular component):



app-group-control
    |
   app-action-buttons-bar
    |
   conditions:
     app-condition-form
     app-condition-form
     app-condition-form
     ...
    |
   groups:
     app-group-control
     app-group-control
     app-group-control
     ...

In the above pseudo component tree, app-group-control is an angular reactive form that contains an action bar and 2 FormArray controls: conditions and groups.

Now I want you to be a curious developer and notice that groups is a collection of app-group-control components. Imagine this: you're gonna a build a component: app-group-control. In its template, among other things, it has a collection of... itself. It's a composite component.

Let's dive a little in each part of this component.

Action bar

Inside app-group-control the first thing we'll find is this action bar (ActionButtonsBarComponent in Stackblitz demo) that allows us to:

Add a app-group-control to groups FormArray (let's call it a "nested group")
Add a condition to the conditions FormArray
When the user clicks on the delete group button, it will ask the component that hosts this instance of app-group-control to be removed

This is a very simple component with 3 @Ouput()-decorated properties:



  @Output()
  remove = new EventEmitter<void>();
  @Output()
  addGroup = new EventEmitter<void>();
  @Output()
  addCondition = new EventEmitter<void>();

Condition

The condition component (ConditionFormComponent in Stackblitz demo) is also a very simple component. But, it has an important thing you should notice: it implements the ControlValueAccessor interface.

The ControlValueAccessor interface is what makes it possible for you to turn your components into angular FormControls. And like any FormControl, they can be part of forms (for example, they can receive the formControlName directive and be controlled by the available @angular/forms utilities and methods).

The ControlValueAccessor is also, what make it possible for us to nest forms in the most possible simple way. I've seen a lot of people doing crazy things to nest forms, like passing the parent FormGroup to a child component in order to reuse it in the child component's form. Maybe it's a matter of style, but I'd strongly recommend anyone to just turn that child component (that contains the nested form) into a FormControl. By doing that you'll be flattening the form's structure. I'd suggest two Kara Erickson videos if you want to learn more cool stuff about angular forms. Finish reading this post and, after that, scroll your page back to check out these amazing videos.

The wrapper form component

Finally we have this wrapper component, that contains the form that wraps everything (GroupControlComponent in Stackblitz demo).

Basically, its template is:



<form [formGroup]="_form">
  <app-action-buttons-bar (remove)="remove.emit()"
                          (addGroup)="_addGroup()"
                          (addCondition)="_addCondition()">
  </app-action-buttons-bar>
  <ng-container formArrayName="conditions">
    <app-condition-form *ngFor="let c of _conditionsFormArray?.controls; index as j" 
                        (remove)="_deleteCondition(j)"
                        [formControlName]="j" 
                        [formLabel]="'Condition ' + (j+1)">
    </app-condition-form>
  </ng-container>
  <ng-container formArrayName="groups">
    <app-group-control *ngFor="let s of _groupsFormArray?.controls; index as i"
                        (remove)="_deleteGroupFromArray(i)" 
                        [formControlName]="i"
                        [formLabel]="'Nested Group '+ (i + 1) + ':'">
    </app-group-control>
  </ng-container>
</form>

If you check the code in Stackblitz, you'll notice that <app-condition-form> has its own form inside. <app-group-control> also has its own form (we're actually looking at it in the code above). Thanks to ControlValueAccessor, nesting these two forms inside a parent form was a piece of cake. Take a look again... we're not only nesting two forms in a completely transparent way, which would be a huge achievement per se. Considering that conditions and groups are FormArrays, we're, in fact, nesting an indefinite number of forms inside the parent form, without the need of any hack, using a simple, clean and robust approach. Pretty cool, don't you think?

The recursion

Like if it wasn't awesome enough to nest an indefinite number of forms in the first nested level, we're nesting host component instances inside itself... for an indefinite number of nesting levels down. It deserves a huge OMG!!! I hope this can give you a measure of the power of angular component-based structure.

Create the form based on incoming data

As a part of the implementation of the ControlValueAccessor interface, we implemented the writeValue(...). It is called by angular whenever the FormControl.setValue() or FormControl.patchValue() is executed by the host form. And this is a perfect place to analyze the incoming data and create/remove/fill-up controls of our form according to the incoming data.

If you take a look at this modified stackblitz demo, you'll see how we can achieve this with two tiny snippets (both of them in the writeValue(...) functions of the GroupControlComponent):



writeValue(value: Record<string,any>) {
  ...
  // Here we create the `conditions` controls based on 
  //   existent `conditions` attribute in the value
  if (value && value.conditions && value.conditions.length) {
    this._conditionsFormArray.clear();
    value.conditions.forEach(c => this._addCondition());
  }
  ...
  // Here we create the `groups` controls based on 
  //   existent `groups` attribute in the value
  if (value && value.groups && value.groups.length) {
    this._groupsFormArray.clear();
    value.groups.forEach(g => this._addGroup());
  }
  ...
}

So, in the AppComponent (in the demo), when we call this._form.patchValue(data); in the buildFormFromData() method, our form is built automatically to accommodate data in the right fields. With ControlValueAccessor in place, this was pretty easy, wasn't it?

Final Considerations

If you try to build this same form without angular ControlValueAccessor, I can guarantee you painful headaches during all the process. For some reason, the ControlValueAcessor is one of the most underestimated angular features among developers. Not using it makes the overall process of building complex forms an overwhelming task.

Give my schematics library a try

BTW, I've built an schematics libray that generates the skeleton of a component with the ControlValueAccessor implementation for you. If you want to, fell free to try it in your projects (it's a devDependency, so it won't add any nano dependency to your project): https://www.npmjs.com/package/@julianobrasil/schematics-components

Credits: Cover image from https://undraw.co

It's something @angular injectors can solve

Juliano — Wed, 01 Apr 2020 14:05:49 +0000

The use case

Today I answered a question at StackOverflow and I'll describe it here just because the author is free to remove it from there breaking that link. The question was: How to Access Parent Component from Child Component in Angular 9.

The first point is that component interaction is very well documented on @angular official site. I'm not the hugest fan of what the author of the question wanted to do. I'm not gonna judge his reasons too because I really don't know his use case thoroughly though. And, most of all, angular provides the tools to do that, so why not learning how to use them? Someday they can be useful. Let's just, for a moment, forget that there are other ways of solving the problem we're taking as an excuse for our sleuthing and focus on this topic: how to use @angular injector directly.

So, in the description of the question, the author described this scenario:

@Component({
  template: '<child></child>'
}) export class Parent { pp: string; }

@Component({
  selector: 'child',
  template: '<grand-child></grand-child>'
}) export class Child { }

@Component({selector: 'grand-child', ...}) export class GrandChild { }

What he wanted to do was accessing, from the GrandChild, the Parent to change pp property. And he was asking why he wasn't able to do, in angular 9, what he was used to doing in angular 8. In his description, he describes what he was trying to do and I'll post it here as it was in the question text:

  this.viewContainerRef[ '_data' ].componentView.component.viewContainerRef[ '_view' ].component;

Don't mess with the library private properties

If you don't wanna be lectured because of one seriously bad coding practice, just jump to the next section

Don't be distracted by following the logic in the last snippet: it's not important if it works or not. The point is that in a serious typescript project like angular, you should believe when the developer uses the private modifier. What he is trying to say is: this property is part of the internal implementation of this class and I can change it without any warning.

Keep this abbreviation in mind: API. The API (Application Program Interface) is the thing you should rely on. As its name said, it is supposed to be the way of an application to use the features of a class/library. Changes in the API are usually avoided by the libraries' authors. And when they are inevitable, they first try to make it compatible with previous versions, and if not possible, publish a document listing that change as a breaking change (because some of the users of that library will have to change their codes in order to use that version).

The API is so important that some testers say that they are the only part of a library that must be tested. It cannot break.

So, if you find yourself in a situation where you need something that is not on the API, the best you can do is asking the authors to expose it. If the authors agree with that, let's consider as acceptable to temporarily use hacks while you wait for that implementation to be rolled out with the new API adding. If the authors aren't gonna change the API, find another way to do what you want. Keeping code that accesses private properties of 3rd party libraries, is having a bomb with a random timer in your project: sooner or later, without any warning, it'll give you headaches.

If my reasons didn't convince you to not use those private properties, do yourself a favor: backup the piece of code you're using it with good tests (and comments). Don't let your users find out for you that a part of your app isn't working anymore.

@angular Dependency Injection

There are great articles out there (and the official docs) diving into how @angular's dependency injection (DI) system works and describing how it uses a probabilistic search technique (Bloom Filters) to discover the injectable stuff in the angular component tree, like this one. It's not part of the scope of this article to go through all that information again.

You only have to know that the DI has multiple injectors, which are methods, associated with components, directives, pipes, and modules, that are responsible for look for objects based on tokens throughout the DI system. For example, if you ask a specific injector for a component and it cannot find it, it asks its parent injector for that component and so on. The injectors are distributed in a hierarchical tree.

How can the angular DI solve that stackoverflow problem

The most simple way

Angular allows for any parent component to be directly injected in any of its children. It's simple and effective. End of discussion.

@Component({
  template: '<child></child>'
}) export class Parent { pp: string; }

@Component({
  selector: 'child',
  template: '<grand-child></grand-child>'
}) export class Child {
  constructor(public parent: Parent) {}
}

@Component({selector: 'grand-child', ...})
export class GrandChild { 
  constructor(private _parent: Child) {
    this._parent.parent.pp = 'some value';
  }
}

Using ViewContainerRef service

All angular component can be used as a reference in the dom to create other components dynamically. The ViewContainerRef is a service associated a component that has methods to do that creation taking that component as a reference in the DOM (even though it may appear that these dynamic components are created inside the component that owns the ViewContainerRef, it is, in fact, created as a sibling - see this article for more info).

What we are really interested in here is the fact that the ViewConainerRef service has a public method to get the parent's injector of the component it is associated with. _And it can also be injected in the component:

@Component({
  template: '<child></child>'
}) export class Parent { pp: string; }

@Component({
  selector: 'child',
  template: '<grand-child></grand-child>'
}) export class Child {}

@Component({selector: 'grand-child', ...})
export class GrandChild { 
  constructor(private _viewContainerRef: ViewContainerRef) {
    const childInjector = this._viewContainerRef.parentInjector;
    const parent: Parent = childInjector.get<Parent>(Parent);
    parent.pp = 'some value';
  }
}

Notice that we don't need any property on Child component to get to the Parent.

Using Injector service

If you look carefully at the previous technique, you may connect some dots and think to your self that if there's a tree of injectors and if one injector doesn't know how to resolve a reference token, it asks for its parent injector... than why just ask the component's injector instead of asking the parent injector for that info? And it's a completely plausible question. Of course, you can do so:

@Component({
  template: '<child></child>'
}) export class Parent { pp: string; }

@Component({
  selector: 'child',
  template: '<grand-child></grand-child>'
}) export class Child {}

@Component({selector: 'grand-child', ...})
export class GrandChild { 
  constructor(private _injector: Injector) {
    const parent: Parent = this._injector.get<Parent>(Parent);
    parent.pp = 'some value';
  }
}

Notice that, once more, we don't need any property on Child component to get to the Parent.

Final Considerations

In the above cases, you can get a reference for the components, because they are hierarchically distributed. It wouldn't work, for example, if A and B components were siblings (you would not be able to inject a reference to A using A's injector => the search algorithm look for a token up in a tree from a given start point, it won't look for a token going up in the tree and, then, going down from upper nodes). You couldn't, also, inject B in A if B was a child of A (the injectors asks information up in the hierarchy, not down in it).

Knowing that you have an injector at your service sometimes solves some problems in a fast way (maybe not the best way, but in a fast way). Maybe you'll never use it, but it's there for you.

Prepare your @angular web app to grow: keep it performant and consistent from the beginning

Juliano — Wed, 25 Dec 2019 22:01:35 +0000

Summarizing...

If you're using angular, I assume that you like its CLI opinionated project structure. It's well designed to give you a good start point for a web application. At the same time, it's flexible enough to give you the freedom to do all sorts of crazy assemblies. If you, at the moment, don't care about how you're doing things just because you feel comfortable in a supposedly safe directory structure built by Angular CLI, chances are that, in the long term, you'll end up with an unmaintainable slow web application haunting your life.

What could go wrong?

It's not uncommon to underestimate the potential of a web app during the time it's being built. Once it is released and people start using it, features requests are almost unavoidable. Have you missed something during your app specs? Even though a poor analysis is usually the reason for an incomplete final product, this is not always the root cause of this kind of situation. The list of what could possibly take your original app to this undesirable stage is larger than just one single poor-analysis factor. Maybe the application was formerly designed to quickly fulfill a single tiny specific demand in the company where you work. Or maybe the client changed his/her mind after seeing the released product; or maybe it was just a pet project that started showing some real potential. It doesn't matter right now what is pushing you to change your original application. In this post, let's focus on the product developing practices, instead of concentrating on the reasons that led it to its current (messy?) state. Let's talk about how you can build or refactor your app, even if it is a small one today, to make it less painful to expand it in the future. We'll be focusing on an @angular web app. We'll see a few good practices that, if adopted from the beginning, can keep your application architecture healthy. Despite the fact that they are kind of overwhelming in small apps (IMO), they can be your life-guard in the future.

What we'll be talking about

There are some actions you can take to keep an @angular app healthy as time goes by. This article does not intend to be an exhaustive list of good practices, but a shortlist of those that I think are the most important of them. We'll be talking about lazy loading, state management, change detection, components architecture and schematics. And the kind of situations a wrong decision involving these topics can bring to the final product. I'll try to reference relevant articles and pages about each topic as we go through each one of them.

Lazy Loading Modules

This is a UX tool available for your app. As your app grows, you can just split it up in several modules.

Any component with some complexity above the minimum should be declared in its own module. I'm calling "complex" any component that you have to spend 200+ lines (not taking comment lines into account) of code to make it works. Maybe a form with only two fields doesn't need to reside in its own module, but a popup list with a searching feature certainly does. By declaring them in their own modules, you can import more selectively what you take into your app. Of course, there's no need for lazy loading complex components. The real advantage of lazy loading is on feature modules.

The problem: if you don't lazy load your feature modules (virtually all of them), you are forcing all of your users to download all the files of your application even if they won't ever use most of the features being downloaded to their browsers. We're talking about the application first rendering delay, that time spent from the moment the user sends a request to the server to the time he/she sees something in the browser. I'm not talking just about that splash screen, but about what comes after it. Instead of forcing the users to stare at a splash screen like forever waiting for the first useful module to be loaded, you want your app to be ready to use ASAP.

The solution: Letting the user initially download just what he needs at first is a bandwidth saver. This can be a very sensible aspect on devices with a poor internet connection. Maybe you want to initially send just that login-page component and nothing more. As soon as the user can see that component you can setup @angular to automatically download (in the background) the next modules that he/she will probably want to see after logging in. Of course, you can opt to wait for the user to finish the login process before start downloading anything else. Or you can take the lazy loading to another level by analyzing the user's average behavior using some statistical tool to try to predict what parts of the app your users will probably want to see after any visited page, by using Minko's Gess.js like he describes in this great article.

Caveats: We are talking exclusively about UX, not about security. Developers tend to believe they are increasing security by using lazy loading and angular routes guards. The ability to load a module just after you're sure the logged user has the right permissions to do it doesn't mean you're protecting anything. You shouldn't rely on the front-end features at all to secure your app. The back-end is the right place to take your security actions because it's much harder for an attacker to have access to it in order to mess up with your system. On the other hand, the front-end code is fully available to be explored. One more persistent user with some javascript knowledge will find out how to reveal hidden components or use your REST API from Postman or any equivalent tool to try to gain access to your database and other protected resources.

Recommended Reading: You can learn a lot about lazy loading from the links below.

Get used to loading all of your feature modules lazily. By doing that it'll be easier to control what your users need to download when they use your web app.

State Management

This is a consistency tool in some situations and a UX one in others. As your app grows, you'll need to show the same information in (potentially) various formats to the user. For example, you can let the user enter a new address in a profile form and want that address to be instantly available on a list shown in an area on the page just reserved to show existing addresses or to be available in a selection list immediately

The problem: if you have the same information spread all over the place in your app, sooner or later you'll forget to update it somewhere and you'll be face-to-face with a problem similar to the wrong-messages-count one that led facebook to adopt redux. You want the information presented to your user in various forms to be consistent. This is one problem. The other situation is about UX. Suppose you have this really long form. Suppose a user is in the middle of the task of filling up that form. Suppose that, for any reason, the user needs to navigate away from the form page (not just hiding it, but destroying it). Finally, suppose the user navigates back to the form: would it be a good UX if he/she find out that the already fulfilled information was all cleared up and it's necessary to start filling up the form all over again?

The solution: have a state object to store all your app components' currently used values. One single object containing all the information, without duplicates. If you google it you'll find out that this single object is called "single source of truth" and it's basically an object that can be globally accessed by any component. It's also important to notice that it's easier to add developers to a project if you follow (well-established) patterns. Of course, you could build this global state object by yourself, using reactive functions from the rx.js library, like BehaviorSubject's, ReplaySubject's, etc. Then you'd have to write functions to isolate the pieces of the state object you wanted in each part of your app. Soon you'd need functions specialized in updating the state object. And you'd have to decide whether mutate it was a better idea than just create a new object. Next, for the sake of organization, you'd decide to have functions to be run as a consequence of the state object updates. Then you'd finally realize you'd be reinventing the wheel and that you should have adopted, from the beginning, NGRX, NGXS, Akita or any other stable library that do all of what you'd have been coding for months just out-of-the-box.

Caveats: the amount of code you have to write to get a state object up and running can be intimidating. It's not avoidable and let's face it: it's really a lot of work to do in terms of coding, apparently repeated (although it's not really duplicated code despite the fact it appears to be so). But it has been a while since coding a lot became part of a developer's job. I have a clear impression that in the past IDEs did a lot of the front-end job. Today it seems that the heavy lifting has been transferred to the programmer, so... what are we complaining about? It's a lot of code that will save us from a lot of known issues that can be irrelevant and easy to deal with while the app is small, but will certainly bring up terrible headaches when it becomes a large web app.

Recommended Reading:

OnPush Change Detection Strategy

One of the reasons @angular has been originally designed to be a completely different project from angular.js, is that the latter's two-way data flow used frequently by the change detector. In @angular, you're not forced to use two-way data binding, so an update in a child doesn't necessarily cause an update on the data in a parent component (you can use @Input() and @Output() decorators instead of "banana-in-a-box" notation to exchange data). But the two-way data binding alone is not a big problem. Think of a page full of components, having a large table and lots of animating things triggered by user interactions. Now imagine @angular having to figure out which parts of that page (comprised of lots of components) must be updated so the view can reflect correctly the underlying data. You, as the developer, know exactly what should be refreshed on the page whenever the underlying data changes. @angular's change detector does it's best to repeat the same task as you'd do if you could take care of the change detection process.

The problem: In the process of figuring out which parts of the view should be updated, @angular updates almost everything related to data in almost every situation. In heavy pages, this can turn the UX into a hell. The page can potentially take seconds to update every part and, in the process, disallow any interaction of the user with any part of it. Of course, you don't want to take care of selecting which components should be updated in that same heavy page, because it surely has many components being presented. But certainly, you'd wish to control this updating process at a higher level, telling @angular which groups of components (in contrast to "which components") and when they should be updated to correctly reflect the underlying data.

The solution: to have more control over when the change detection should affect your component, you can tell angular to automatically runs the change detector in some special cases (@Input() change events, async pipes being updated and DOM originated events). This can be activated by setting the @Component's attribute changeDetection to ChangeDetectionStrategy.OnPush. It will probably have no noticeable performance improvement in simple components, but I assure you it's a lifesaver when you're dealing with complex components comprised of several subcomponents. This can be the difference between a good UX and a completely unusable page of your app. If you take a look at well-designed components libraries like Google's @angular/components you'll notice that all of the components have their change detection strategy set to OnPush. It's an important clue of what you should be doing. All of your components should follow the same strategy (IMO). Most of the times this strategy will be enough for any component. In some specific situations not covered by OnPush strategy, you can inject a reference to the change detector (ChangeDetectorRef) and express your will to force a component to take part in the next turn of change detection by calling its markForCheck method inside this component. To group your components... well, it's more simple than you imagine: you can build a component to group them, because, in @angular, everything is a component.

Caveats: most of the time, there aren't any points you should be aware of when using OnPush (just be careful to not invalidate the OnPush strategy by too many manual calls to the change detector). I'll update this article if I remember something.

Recommended Reading:

Components Architecture (Container-Presentational)

Right now you have two important pieces of the architecture I'm suggesting: state management and OnPush change detection strategy. You'll want to use them at their full potential and there's one thing you can do to assure it.

The problem: at this point, if you follow carefully the preceding sections, you're probably mentally set up your projects to use the above techniques. It is possible you'll not take full advantage of them and maybe the OnPush change detection strategy brings you some headaches in some situations, forcing you to manually call the change detector two many times. In addition to that, you have a component hard to test because of the reactive nature of the injected services that will make your project work.

The solution: there's a recommended way of organizing your project components in order to take maximum advantage of the configuration I've written bout until now. It's called Container-Presentational. It's important to say that this isn't general advice for every framework. We're speaking strictly of @angular here, in the specific situation where the components are set to use the OnPush strategy. Long story short, this is about grouping most of your components into two categories:

Presentational: the components in this category, as a rule, are not allowed to have any features but those related to rendering the information on the screen. The presentational components shouldn't have any injected services or access any rest API. All of the data the component needs in order to work correctly should be passed in by @Input() properties (which, in turn, activates the change detector, even in OnPush strategy, automatically). Similarly, all the data and requests the component needs to externalize should be done using @Output() properties. You are allowed to inject a component service, containing methods strictly related to the rendering process or the logic of showing/hiding the component's parts. Sometimes you'll find authors using the term dumb components to describe presentational components (the smart components would be the other category, described below).
Container: the components in this category, are responsible to grab the data from external sources (REST APIs/Global State Objects) and to pass the information down to presentational components. Here you are allowed to inject as many services you think are necessary, including the State Management service. They act as the "API" components for your project. If your project is split into several libraries, the Container components would be used directly on your feature modules, and they would wrap your presentational components, passing data down to them in order to make your project work.

Caveats: sometimes it's not so obvious if a component should be container or presentational. The most obvious situation is the dialogs. On some occasions, they can be considered presentational and, in others, container components. There's not any strong rule stating what they should act like. In fact, once you're using this container-presentational organization, nobody would be arrested for deciding to inject the store service in a formerly presentational component. There are legitimate use cases where it's much more simple to inject the store in a presentational component than pass in 15 input data, which would increase the complexity of the component API. So, don't worry if you exceptionally have to inject some services in your presentational components.

Recommended Reading:

`@angular/cli` schematics: thinking of DX

To take to your project all the things we've been talking about, you'll surely add a lot of code. If your project is already on production or in an advanced stage of development, we're also talking about refactoring (even more work to do). In any situation, when building a new project or refactoring an existing one, every developer should always think of how to reduce the amount of code needed to make things work.

The problem: adding a robust and flexible architecture to any software project usually takes many lines of code plus the creation of some files. We're talking about interfaces, abstract classes, services, DI, tests, etc. To keep your code healthy and consistent, you will add things to your code that once in a while will seem overwhelming ("OMG, this is just a hello-world component! Why do I have to create so many files/interfaces/services/modules?"). Believe-me: you should be faithful to the chosen design patterns even in these apparently overwhelming scenarios. At the same time, you should find a way to not kill the developers' experience and productivity and let them do what they are meant to do: coding. Most of the work should be around thinking of the business logic instead of writing code because there's a specific design pattern to be followed. Yes, we're talking about how to avoid the inevitable boilerplate. The design pattern should get into the project in the most possible transparent way.

The solution: there are some actions you could take to reduce the amount of boilerplate. Use good code editors configured correctly using the same setup shared among the team, for example. But I'd like to talk here about a powerful tool that comes with @angular/cli: schematics. Schematics is a template-based tool that comes with an API, that allows you to manipulate text files. Using schematics you are able to take one or more template files and generate custom commands that take those template files and generate other files based on them, replacing specific parts of their contents by whatever you want. Schematics turn the boring task of creating complex directory structures in a very quick and productive task. And the best part is that building your custom schematics is not that hard, even if you have never done anything like that before. @angular/cli itself uses schematics to generate components, modules, pipes, etc. What Google did here is to turn all the heavy work that @angular/cli did internally into a powerful API. How about creating a template to, in 2 or 3 seconds, generate a feature module, with a component inside, ready to be lazy-loaded, with all the routing already configured to use @angular/material imported as a separated module and a component service injected on your component? Try to build it and you'll see that to an experient developer who's also a fast typer, knowing absolutely what to do, it will take like 5 to 10 minutes. To a beginner developer, it would easily take 40 to 60 minutes. Building some custom schematics to help your day-by-day coding can be a good idea.

Caveats: be careful to not catch your self reinventing the wheel. The schematics won't ever be a peer dependency on your project (they're always a dev-dependency). So do not be afraid of npm install --save-dev 3rd parties schematics libraries. If their projects become abandoned, you can stop using them whenever you want without refactoring any code.

Recommended Reading:

Conclusion

You should get to know all the pros and cons of the approaches you choose for your components. You'll find out that simple strategies, like the ones shown here, can help to keep your application healthy during its active life span.

Accessing angular components methods from within Cypress

Juliano — Mon, 23 Dec 2019 18:13:46 +0000

Some Initial thoughts

One important (let's avoid the word "essential" here) element to keep a long-living application maintainable is the presence of tests. It's a common-sense that they are a must-have piece of any healthy codebase and come in some flavors: Unit, Integration, and Functional (end-to-end or e2e) tests. You can read more about each one on this great article. There are two kinds of elements to be tested: ui and non-ui components (in the former case, you can perform visual and/or non-visual tests). The adoption of one or more types of tests and the corresponding tools that will make it possible to run them automatically depends on the project and its natural constraints (team expertise, team size, deadlines, adopted technologies, presence or absence of CI/CD, etc).

In JavaScript world, like in other languages, we have different tools for each type of test (unit, integration, e2e).

A few words about unit tests

As of the writing of this post, we typically use Jest/Karma to perform unit testing (static, isolated, and integration) on non-ui components: data models, data services, facades, state management, etc. And - with Angular - we can use the TestBed object, provided by the Angular framework, to configure Dependency Injection (DI) and ngModules within a test cycle.

On the other hand, we have the harsh reality: UI components unit testing is often problematic, painful, and provides little true ROI. It's not rare to have more lines of testing code in the UI specs files than the UI component code under test itself. But this doesn't mean we don't want to test them. They should be tested as everything else in your code, maybe not at unit level though.

Cypress.io and e2e testing

We often want to test UI components to answer two basic questions:

(1) Does the UI render as we expected; not just DOM structure but also the styling and layouts?
(2) Do the workflows perform as expected?

Cypress.io elegantly provides powerful, intuitive features to do these.

Cypress is a great agnostic javascript testing tool that shines on e2e tests, as an alternative to Selenium (wrapped by Protractor in Angular framework). For aspect (2) above, Cypress.io simulates the user and the 'user' interactions based on custom Cypress scripts (eg steps).

The most exciting aspect is that Cypress.io has brought an incredibly friendly API to the JavaScript testing world. If you're a complete newbie to Cypress.io, it probably won't take more than 10 minutes to go from scratch to having a simple working test. Its documentation is amazingly easy to read with lots of examples.

If we want to use Cypress to test UI component functionality and UI, we do not need a TestBed... we are testing the actual "deployed" Application (instead of only component source) and all the necessary elements to run the tests are already instantiated.

Among all of e2e aspects concerning the adoption of Cypress.io for an Angular codebase, we'll focus on how we can spy or stub an Angular Component method without having a TestBed, by grabbing the available component running instance from the DOM.

Why stub or spy?

During unit or integration tests, you usually search for elements on the DOM, like texts, components attributes, etc, to check if the app is showing/hiding or animating anything. According to what you find on the DOM you get to the conclusion that a piece of the web app is working and the users supposedly see on the screen what you expected them to see. For example, if you find that a certain ui component has a "display: none" attribute, you should trust that it won't be visible or taking any space on the screen. You write your tests based on the trust that the browser is a piece of this puzzle that is already tested by its developers and is doing its job correctly. In other words, you're focused on your code only, so you can write your tests using non-visual (functional) isolated tests.

If you are concerned about how the browser is doing its job (visually) or about whether your CSS classes weren't broken by someone messing around with the design then you'll need some testing tools to compare snapshots of the current browser's rendering results with some known reference snapshots. We are aware that each browser renders things differently from each other. You can add plugins to Cypress.io to test your application design visually.

But if you only want to keep track of the application workflows during an e2e testing cycle, Cypress.io can provide you enough tools out-of-the-box (no need for plugins). Sometimes, inspecting what is inside of a component is just a hard thing to do. For example, if you're using chart.js, it uses canvas to draw the charts - it's not possible to check the canvas content from a functional approach. Instead of trying to inspect what is inside the canvas element you'd better step back and just stick to checking, for example, if the function that generates the data for the chart was successfully called with the right arguments; or whether the event handlers that should be fired as a consequence of user interactions with the canvas elements were really called. In that case, when monitoring these function callings, you want to know three things:

(a) Whether and (b) when a function is being called
(c) Whether it's being called with the right arguments

To do (a) to (c) you must get a reference to your angular component object (the instance of the component's class). For us it's important to keep in mind that we don't have the TestBed available in this scenario, so we have to grab the component instance object by ourselves.

Let's do it

Let's suppose you have the following ComponentUnderTest:

@Component(
  selector: 'comp-to-test',
  template: `
    <button (click)="_methodToBeTested($event)"
            cy-data-button>
      Click me
    </button>
  `
)
export class ComponentUnderTest {
  // This method is fired upon user interaction
  _methodToBeTested(...) { ... }
}

To gain access to the methodToBeTested we'll use the ng global object available from the global window object. From that point on it's simple to do what you need.

The important thing to notice is that you cannot access window or document directly from within your test it() function. You must use the available cy.window() and cy.document() chainable methods to access those objects.

Using `cy.stub`

Your test will probably look like this:

describe('Trying to call some angular component method'), () => {
  it('Should call methodToBeTested' => {
    let angular!: any;
    // You can access the window object in cypress using
    //   window() method
    cy.window()
      .then((win) => {
        // Grab a reference to the global ng object
        angular = (win as any).ng;
      })
      .then(() => cy.document())
      .then((doc) =>{
         const componentInstance = angular
             .getComponent(doc.querySelector('comp-to-test'));

         cy.stub(componentInstance, '_methodToBeTested');

         cy.get('button[cy-data-button]').click();

         // Just put this test to the end of the event loop
         //   in order to make sure angular runtime engine
         //   will have fired the click event that calls the
         //   method calling under test.
         cy.wait(0).then(() => 
           expect(componentInstance._methodToBeTested).to.have.been.called);
      });
  });
});

Using `cy.spy`

Now, the stub approach is fast. But it can potentially hide the side effects that clicking on that button can cause. In the end, by using Cypress, I assume that you're interested in e2e tests, and chances are that you want to observe the thorough behavior of your app. If you wish to through the real side effects caused by the method called when that button is clicked, you must use cy.spy instead of cy.stub. If anything fails you will be able to visually inspect what happened during the test (by the way, Cypress, by default, records all of the application visual behavior, even in headless mode, in mp4 format).

So we need to do a single adjustment to replace cy.stub:

describe('Trying to call some angular component method'), () => {
  it('Should call methodToBeTested' => {
    let angular!: any;
    cy.window()
      .then((win) => angular = (win as any).ng)
      .then(() => cy.document())
      .then((doc) =>{
         const componentInstance = angular
             .getComponent(doc.querySelector('comp-to-test'));

         // Here we had cy.stub before
         cy.spy(componentInstance, '_methodToBeTested');

         cy.get('button[cy-data-button]').click();

         cy.wait(0).then(() => 
           expect(componentInstance._methodToBeTested).to.have.been.called);
      });
  });
});

Conclusion

If you're thinking of sparing some time to learn JavaScript testing tools, it's worth it taking a look at Cypress.io. It's a short-learning-curve and still powerful tool available out there.

If you find something that I left out from this article, in the scope of stubs and spies with Angular, just mention it in the comments and I'll insert it in the text.

Also, I owe a special thanks to Thomas Burleson for dedicating some time to review the text and point some directions concerning the reasons that support Cypress.io integration to angular.

DEV Community: Juliano

Building recursively nested @angular reactive forms: a clean approach

The use case

The pseudo component tree

Action bar

Condition

The wrapper form component

The recursion

Create the form based on incoming data

Final Considerations

Give my schematics library a try

It's something @angular injectors can solve

The use case

Don't mess with the library private properties

@angular Dependency Injection

How can the angular DI solve that stackoverflow problem

The most simple way

Using ViewContainerRef service

Using Injector service

Final Considerations

Prepare your @angular web app to grow: keep it performant and consistent from the beginning

Summarizing...

What could go wrong?

What we'll be talking about

Lazy Loading Modules

State Management

OnPush Change Detection Strategy

Components Architecture (Container-Presentational)

@angular/cli schematics: thinking of DX

Conclusion

Accessing angular components methods from within Cypress

Some Initial thoughts

A few words about unit tests

Cypress.io and e2e testing

Why stub or spy?

Let's do it

Using cy.stub

Using cy.spy

Conclusion

`@angular/cli` schematics: thinking of DX

Using `cy.stub`

Using `cy.spy`