Forem: Duncan Faulkner

Introduction to Vitest and Angular

Duncan Faulkner — Sun, 13 Oct 2024 21:49:59 +0000

The Angular team deprecated Karma a few versions ago and are currently working on ways to provide an alternative 3rd party unit testing frameworks. Currently the options talked about so far are Web Test Runner (likely to be the default), this is a browser based unit test runner similar in many ways to Karma. The other option being discussed is Jest, this can be installed now but can be a little tricky sometimes to get set up and some known issues when Angular is set up to use ES builds (the default in Angular 18 onward).

The Angular team are looking at using the CLI for the installation process of these unit testing frameworks, similar to when selecting a CSS framework when creating a new project. This is all still very early on in the development cycle and may be a little way off before it becomes developer preview (currently still experimental) and no mention (as yet) of how this would work with an existing project.

Now that newer versions of Angular use Vite as a development build server and the default in Angular 18, it is now possible to use Vitest in our Angular projects. The installation process is straight forward to set up and feels less problematic than setting up Jest from my recent experience. The great news here is that Vitest has a similar syntax to Karma and Jest, so the learning curve should be fairly small.

In this post I'm going to walk through setting up and configuring Vitest in an Angular 18 application and replacing Karma . I won't be writing unit tests in this post, I'll leave that for another post, this post is about setting up Angular to use Vitest.

I'm going to start a new project for this post but this will also work on an existing project.

In a directory type the following in the terminal:

ng new my-vitest-app  && cd my-vitest-app && npm i

This will create a new Angular application called my-vitest-app, it'll change into that directory and then run npm install with our application created we can now remove Karma.

From the terminal, type:

npm uninstall karma karma-chrome-launcher karma-coverage karma-jasmine karma-jasmine-html-reporter

We don't need to uninstall @types/jasmine and jasmine-core as Vitest uses Jasmine under the hood, we can use it and describe from Jasmine so we don't need to import anything in our test files. It is possible to use it and describe from Vitest but in doing so we won't be able to use functions like fakeAysnc in our unit tests.

The easiest way to get Vitest installed in our project is to use a plugin and AnalogJS has just what we need to setup and configure Vitest for us.

From the terminal type:

npm i @analogjs/platform -D

Followed by:

ng g @analogjs/platform:setup-vitest --project my-vitest-app

Once complete the following files will be generated:

// vite.config.mts
/// <reference types="vitest" />
import angular from '@analogjs/vite-plugin-angular';
import { defineConfig } from 'vite';

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {
  return {
    plugins: [
      angular(),
    ],
    test: {
      globals: true,
      environment: 'jsdom',
      setupFiles: ['src/test-setup.ts'],
      include: ['**/*.spec.ts'],
      reporters: ['default'],
    },
    define: {
      'import.meta.vitest': mode !== 'production',
    },
  };
});

vite.config.mts will be in the root of the project, this sets up the configuration for Vitest, what environment to use, the default is jsdom, you can change this to happy-dom (you will need to install happy-dom). The test-setup.ts will be in the src directory and this sets up the test environment.

import '@analogjs/vitest-angular/setup-zone';
import {
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting,
} from '@angular/platform-browser-dynamic/testing';
import { getTestBed } from '@angular/core/testing';

getTestBed().initTestEnvironment(
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting()
);

If you are using azoneless application then the test-setup.ts will be slightly different:

import '@analogjs/vitest-angular/setup-snapshots';

import {
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting,
} from '@angular/platform-browser-dynamic/testing';
import { getTestBed } from '@angular/core/testing';

getTestBed().initTestEnvironment(
  BrowserDynamicTestingModule,
  platformBrowserDynamicTesting()
);

In angular.json the test section will be replaced with:

 "test": {
    "builder": "@analogjs/vitest-angular:test"
 }

And finally the tsconfig.spec.json will be update to:

{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "outDir": "./out-tsc/spec",
    "types": [
      "jasmine",
      "vitest/globals" // added
    ],
    "target": "es2016" // added
  },
  "include": [
    "src/**/*.spec.ts",
    "src/**/*.d.ts"
  ],
  "files": [
    "src/test-setup.ts" // added
  ]
}

To run Vitest tests we need to change the scripts section, in our applications package.json file add:

{
 // other scripts
 "test" : "vitest"   
}

Using npm run test will run all of our test files our project.

If you don't want to install Volta you can skip this section.

To run Vitest from the terminal we need to install Vitest, we have a couple of options, globally using npm i -g vitest, I tend to use Volta, this is a tool chain manager, similar to Node Version Manager (NVM) but Volta handles other JavaScript tooling other than just Node.

If you currently have a version of node installed, you will need to uninstall this first before install Volta, once Volta is installed we can install multiple versions of node without removing the previous versions.

To install Volta head over to https://volta.sh/ and get the appropriate installer package for your operating system, I'm using Ubuntu and all we need for this is:

# install volta
curl https://get.volta.sh | bash
# install node
volta install node@20.15.0

As a side note, one of the nice features of Volta, is the ability to pin the version of node we are using to our package.json file, meaning that Volta will always select the correct version of Node, this is real handy when working in a team of developers, to pin a version of Node to our package.json file run volta pin node@20.15.0.

With volta and node installed we can now install Vitest:

volta install vitest

With Vitest installed we can run volta ls this will show a list of the tooling that we have installed.

# example listing from Volta
⚡️ Currently active tools:

    Node: v20.15.1 (default)
    Tool binaries available:
        vitest (current @ /home/repo/vitest-app/package.json)

With everything installed we can now run our unit tests, if we want to run a selection of tests (or a specific test) then we need to use the terminal and pass in an additional parameter, this parameter will run any test file that contains this parameter.

# run a range of unit tests
vitest dashboard

We can also specify a file, this will only run a unit test that matches the file name, note that this doesn't support regex or glob patterns.

# run a specific unit test
vitest app.component

The above will run the unit tests and watch for changes, to run the unit test once and not watch for changes we can change the command to:

# run unit test(s) once then stop
vitest run [optionally specify an additional parameter]

If we want to run our unit tests in a CI environment we don't need for them to be in watch mode, so add a test:ci to the script section of the package.json file.

{
 // other scripts
 "test" : "vitest",
 "test:ci" : "vitest run"
}

We need to set up our build pipelines to run our tests, setting up build pipelines is out of scope for this post, so I will assume you know how to do this, if not they are plenty of posts on how to do this.

The next part I want to cover is code coverage, so we've written our unit tests for our various features in our project, but have we written enough? Have we covered the important parts that need testing? This is where code coverage comes to the rescue. Code Coverage tell us how much of our feature is covered by unit tests, whether we've missed a path, for example we've covered the if condition but not the else condition.

Let's add a new script to the scripts section of our package.json file.

{
// other scripts    
"coverage":"vitest run --coverage"
}

With this we can run npm run coverage locally and will create a coverage directory for us in the root of the project and we'll get a table of files along with their code coverage:

File	% Stmts	% Branch	% Funcs	% Lines	Uncovered Line #s
All files	100	100	100	100
app.component.ts	100	100	100	100

When we run this it might prompt to install a supporting package this can be either coverage-v8 (the default) or coverage-instanbul package, if not we can install them manually using:

# For v8
npm i -D @vitest/coverage-v8

# For istanbul
npm i -D @vitest/coverage-istanbul

We can set the provider type in the coverage section in the vite.config.mts file:

export default defineConfig(({ mode }) => {
  return {
    plugins: [angular()],
    test: {
      globals: true,
      environment: "jsdom",
      setupFiles: ["src/test-setup.ts"],
      include: ["**/*.spec.ts"],
      reporters: ["default"],
      coverage: {
        provider: "v8",
        reporter: ["text", "json", "html"],
      },
    },
    define: {
      "import.meta.vitest": mode !== "production",
    },
  };
});

To run code coverage in our CI environment we need to adjust our test:ci script to include a reporter, here I've used junit and junit.xml and there is a handy plugin for Azure Devops to read the junit.xml file which will import the file and create a nice dashboard for us.

script:{
// other scripts
"test:ci": "vitest run --reporter=default --reporter=junit --outputFile=reports/junit.xml",
}

In Azure devops we can add the PublishTestResults task in our build pipelines and would have the task run after our unit tests have completed.

When we run our unit tests the results will be displayed in the terminal (unless running in a CI environment), but if you prefer to see the results in a browser this is also possible, first we need to install the ui tooling:

npm i @vitest/ui

You will need to match the version of @vitest/ui to the same version of vitest installed on your system, once installed we can start it by running vitest --ui from the terminal, if we add the html to the reporters array in our vite.config.ts file, this will create an html directory with all the files.

export default defineConfig(({ mode }) => {
  return {
    plugins: [angular()],
    test: {
      globals: true,
      environment: "jsdom",
      setupFiles: ["src/test-setup.ts"],
      include: ["**/*.spec.ts"],
      reporters: ["default", "html"], // add html into this array.
      coverage: {
        provider: "v8",
        reporter: ["text", "json", "html"],
      },
    },
    define: {
      "import.meta.vitest": mode !== "production",
    },
  };
});

Conclusion

In this post we looked at installing and setting up Vitest, a unit test runner in for Angular applications based on Vite, we also added code coverage to our test runs to see how much code coverage our unit tests cover, we also learnt how we can set this up in our CI in Azure Devops.

Using Mat-Icon Component – Part Two

Duncan Faulkner — Mon, 27 Jan 2020 13:27:00 +0000

Blog Post #002

Duncan Faulkner – January 2020

I hadn’t intended to write about this just yet, but I got a chance to investigate this sooner than I had thought. I was refactoring part of a project that was using the Mat-Icon component, with an icon.module.ts file as I’d discussed in the previous post.

I wanted to see if I could improve on the code and reduce the amount of repeated code by iterating over a file and registering the icons.

I started with a JSON file and populated it with some image names and added the HttpClientModule to use an http.get() method to read the JSON file. All good so far, the file is reading and looping with image names being returned and passed into the matIconRegistery.addSvgIcon() method.

I thought I might get some issues, but it all seemed to work fine, except the application was erroring, the issue was that the application was loading before the call to the JSON file had returned with the results, so even though I was getting images and registering icons, the app had already tried to use the icons and they weren’t there at that point, and the images were being returned after the app had started.

OK, so may be this is a timing issue and it doesn’t work in the icon.module.ts file, so I moved code to the app.component.ts file. Nope, the results were the same. This was not the result I was expecting and it was a little odd because the icon.module.ts file was loading images before.

I’m going to revisit this at a later date, as I would like to understand what the issue is and why it was behaving the way it did, my guess is it has something to do with the http.get() request and the timing around that.

But as I needed to get this refactoring completed I needed to look for another solution.

After a bit of research I found an answer and that was to create a service to handle the iterating and registering of icons. Instead of a JSON file to store a list of images the solution was an enum, with a key value structure.

export enum Icons {
    add = 'add',
    power = 'power',
    save = 'save'
}

To keep things simple I’ve made the key and the image name the same.

The service is quite simple:

// imports
import { Icons } from '../image.enum';

@Injectable({ providedIn: 'root'})
export class IconService {
  constructor(
     private matIconRegistry: MatIconRegistry,
     private sanitizer: Domsanitizer
){}

registerIcons(): void {
   this.load(Object.values(Icons), 'assets/images/icons');
}

private load(key: string[], url: string): void {
   key.forEach(icon => {
     this.matIconRegistry.addSvgIcon(
       icon, 
       this.sanitizer.bypassSecurityTrustResourceUrl(`${url}/${icon}.svg`)
   ); 
 });
 }
}

And on the app.component.ts file call the registerIcons() function.

// imports
import { IconService } from './icon.service';

export class AppComponent implements OnInit {
   constructor(private iconService: IconService) {
      this.iconService.registerIcons();
   }

}

And that’s it, not what I had in mind when I started this, but it does deliver what I wanted to do, and that was to reduce the amount of code to register icons. Though I guess the enum could get pretty lengthy if there are a lot of images.

I have to thank Stefanos Kouroupis -dev.to – for his article and code on this as I wouldn’t have thought about using a service for this and this has changed my thinking. I wanted to include here it as a follow up to my previous post for completeness, you can see his full article here https://dev.to/elasticrash/using-custom-made-svg-icons-through-the-angular-material-library-2pif.

I will add a github repo of the code in a day or two.

Original article published at: https://anglebrackets.io/index.php/2020/01/25/using-mat-icon-component-part-two/

Angular Materials Mat-Icon component

Duncan Faulkner — Thu, 14 Nov 2019 18:34:22 +0000

Using local SVG images.

Blog post #001

Duncan Faulkner - October 2019

When developing an Angular application with Angular Material, there comes a point when we need to add icons on our components, or buttons etc... Angular Material has the Mat-Icon component for doing this. This component works with web fonts like Font-Awesome for instance, simply by adding the name of the image required and an image is displayed.

For example:

<mat-icon>home</mat-icon>

Note: Requires Angular application and Angular Material is installed/configured and a reference to a web font like Font-Awesome library is all set up

But what about if you have custom icons that are not part of a web font? And would like to makes changes to the icon, for example: change the colour on hover or on a specific condition at run time?

In a recent project I had a bespoke set of SVG icons, the Angular web application was to be installed on a server that didn't have access to the internet, so the images had to be local. I wanted to use the Mat-Icon component out of the box (in an early version of the project I had a custom icon component). I still wanted to be able to change the colours of the icons at various stages throughout the application based on certain conditions as well as on hover. This post covers how I achieved that.

SVG Icons

There are a number of different ways to register an icon with the Mat-Icon component, this post discusses addSvgIcon, the others are addSvgIconInNamespace, addSvgIconLiteral or addSvgIconLiteralInNamespace and are all methods of MatIconRegistry and I might cover these in more detail in a future post.

Setting up an Angular project

Note In this post, I'm not going to step through the creation of an Angular application as there are so many already online. Plus I tend to create Nx workspaces for all my Angular projects as I prefer this project layout. I plan to do a blog post on this very soon, for the moment though see Getting started with Narwhal's Nx Workspaces.

In the newly created Angular project, create a shared directory and add a new file named material.module.ts. I like to separate Angular Material imports into their own module, I also create a separate module for other 3rd party components, just makes it easier to import later, especially using the Nx workspace layout and feature folders.

In the material.module.ts

// Material Module example.
// All other Angular Material component imports here
// but the important ones are...
import {MatIconModule, MatIconRegistry} from '@angular/material/icon';

@NgModule({
    declarations: [],
    imports: [
    // Other material imports removed for brevity,
    MatIconModule],
    exports: [
    // Other material exports removed for brevity,
    MatIconModule, MatIconRegistry
    ],
    entryComponents: [],
    providers: [MatIconRegistry]
})
export  class  MaterialModule  {}

MatIconModule is the module for the component, and the MatIconRegistry is a service to register and display icons. Add a reference to the material.module.ts in the app.module.ts. Don't forget to export it as well, otherwise it won't be available and Angular will not know anything about the Angular Material components.

// Include the material module in app.module.ts
import  {  BrowserModule  }  from  '@angular/platform-browser';
import  {  NgModule  }  from  '@angular/core';
import  {  AppComponent  }  from  './app.component';
import  {  BrowserAnimationsModule  }  from  '@angular/platform-browser/animations';
import  {  MaterialModule  }  from  './shared/material.module';

@NgModule({
declarations:  [AppComponent],
imports:  [BrowserModule,  BrowserAnimationsModule,  MaterialModule],
providers:  [],
bootstrap:  [AppComponent]
})
export  class  AppModule  {}

Now we have the Angular Material components set up and configured we need to register the icons, before we can use them. For the moment we are just going to add these to the app.component.ts to get up and running, we'll look at a better method later on.

// First Example
@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.scss']
})
export class AppComponent {
    constructor (
        private matIconRegistry: MatIconRegistery
    ){
    this.matIconRegistry.addSvgIcon('home','assets/img/icon/home.svg');
    this.matIconRegistry.addSvgIcon('add','assets/img/icon/add.svg');
    }
    // or we could do this, and chain the addsvgIcon methods.
    // we'll use this method going forward in this post
    // {
    //      this.matIconRegistry.addSvgIcon('home','assets/img/icon/home.svg')
    //      .addSvgIcon('add','assets/img/icon/add.svg');
    // }
}

Add this to the app.component.html page, we'll discuss this in more detail in a bit.

<!-- First HTML example -->
<div>
    <mat-icon svgIcon="home"></mat-icon>
    <mat-icon svgIcon="add"></mat-icon>
</div>

At this point we are not going to see much in the browser as we have an issue with the image URL. If you open the browsers console section, you will see the following error:

Error: unsafe value used in a resource URL context.

So what does this error mean? A brief explanation from the Angular Material website says:

To prevent an Cross Site Scripting (XSS), SVG URL's and HTML strings passed to MatIconRegistry must be marked as trusted by the Angular's DomSanitizer service. Icons are fetched via XmlHttpRequest and must have their URL's on the same domain as the containing page or configured to allow cross-domain access.

So lets add the DomSanitizer and fix this issue.

// Second Example - with the DomSanitizer
@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.scss']
})
export class AppComponent {
    constructor (
        private domSanitizer: DomSanitizer, 
        private matIconRegistry: MatIconRegistery
    ){
    this.matIconRegistry
    .addSvgIcon('home',this.domSanitizer.bypassSecurityTrustResourceUrl('assets/img/icon/home.svg')
    .addSvgIcon('add',this.domSanitizer.bypassSecurityTrustResourceUrl('assets/img/icon/add.svg')
    // add other icons here....;
    }
}

The call to bypassSecurityTrustResourceUrl takes a URL as a parameter and sanitizes it so that an attacker cannot inject a 'JavaScript:` URL for example, see official documentation on DomSanitizer.
Now that we have this in place we should now see two icons in the browser.

If we have a lot of icons to add this means lots of typing and lots of repetitive code, so lets refactor this some more. Start by removing all of this code (including the constructor) from the app.component.ts. This shouldn't really be in the app.component.ts file. Lets create another new module in the shared directory and call it icon.module.ts and then add the following:

typescript // Third Example - icon module import { NgModule } from '@angular/core'; import { DomSanitizer, SafeResourceUrl } from '@angular/platform-browser'; import { MaterialModule } from '../shared/material.module'; import { MatIconRegistry } from '@angular/material/icon'; @NgModule({ declarations: [], imports: [MaterialModule], exports: [], providers: [] }) export class IconModule { private path: string = '../../assets/images'; // change this constructor( private domSanitizer: DomSanitizer, public matIconRegistry: MatIconRegistry ) { this.matIconRegistry .addSvgIcon('home', this.setPath(${this.path}/home.svg)) .addSvgIcon('add', this.setPath(${this.path}/file-plus.svg)); } private setPath(url: string): SafeResourceUrl { return this.domSanitizer.bypassSecurityTrustResourceUrl(url); } }
Overall, that's not too bad, we are only writing out the domSanitizer code once in the private method but more importantly, all the code is out of the app.component.ts file and is now a self contained module. If there are a lot of icons to add then this file will get a bit long, but the typing has gotten shorter (well, a little shorter at least). You could change the constructorto iterate through a .json file of image names, the path wouldn't change and could be a const, which would only mean maintaining a .json file with any new images. I might look at doing that in a follow up post.

Note: Don't forget to add this new icon.module.ts to the app.module.ts otherwise it won't work.

Using the Mat-Icon component

So how do we use the mat-icon component? As seen earlier in this post we add the following code to our app.components.html page.

`html

`
This is a very simple example is showing how to put a home and an add icon on a page/component. This is not too dissimilar to how we would use this component with web fonts, but we are now using the svgIcon input property. The value we give to this input is the first parameter used in our call to register the .addSvgIcon('home', ...) in this case home.

Now we have an icon in place, how do we change the colour of the icon when someone hovers over it for example.

Change the icon colour

A Home icon.
Example icon copy this into a file with the SVG extension.
svg <svg version="1.1" width="24" height="24" viewBox="0 0 24 24"><path d="M10,20V14H14V20H19V12H22L12,3L2,12H5V20H10Z" fill="#00FFFF" /></svg>
In the above XML, I've removed all the namespaces etc... The main part here is the fill="#00FFFF" this sets the colour for the image, in this case to AquaMarine.

If the fill="#00..." property is not there and you want a different colour to the default black, then you can add it to the path as above, it's optional.

I usually add the fill property and set it to white and then change them in SCSS as and when required (but because this example had a white the background I used another colour).

`html
!<-- Second HTML example -->

!&lt;-- other code omitted for brevity --&gt; 
<a>

</a>

`
Add a class to the mat-icon html tag, as above and then add the SCSS, for the class. So when a user hovers over the button the colour of the icon changes.

scss .btn-icon { &:hover { path { fill: rgba(#00ffff, 1); } } }
Note One thing I did forget to add to the app.component.ts above, was the following line:
encapsulation: ViewEncapsulation.None, without this then the hover affect doesn't work.

typescript @Component({ selector: 'mat-icon-demo-root', templateUrl: './app.component.html', styleUrls: ['./app.component.scss'], encapsulation: ViewEncapsulation.None, }) export class AppComponent { title = 'mat-icon-demo'; }
Enjoy!

There is a github repo for this blog post at:
https://github.com/Anglebrackets-io/mat-icon-demo