Angular のテスト環境

Angular のテストでは、Jasmine と Karma を使うのが一般的です。
Angularの公式ドキュメントにも、その組み合わせでテスト環境を構築する手順が記載されています。

Jasmine
- JavaScript のテストフレームワーク
- テストの記述（構文やアサーション）を提供する
Karma
- Google が開発した JavaScript のテストランナー
- Jasmine や Mocha などのテストフレームワークと併用される

ところが、現在 Karma は以下の理由により非推奨となっています。

The web testing space has evolved significantly in the 10+ years since Karma's creation. The web landscape looks very different today and new patterns and tools have emerged in the ecosystem. New test runners offer more performant alternatives, and Karma no longer provides clear unique value.
Based on the current state of the web testing ecosystem, we have made the hard decision to deprecate Karma.
We know Karma is used particularly commonly in the Angular ecosystem, so Angular is adding Jest and Web Test Runner support to provide a migration path off of Karma. See the Angular blog for more details.

引用：https://github.com/karma-runner/karma?tab=readme-ov-file#karma-is-deprecated-and-is-not-accepting-new-features-or-general-bug-fixes

どうやらウェブテスト環境の進化によって Karma 独自の価値が失われたことが理由みたいです。
そこで Karma の代わりとして推奨されているのが Jest です。

Jest

Jest は、Facebook（現 Meta）が開発した JavaScript のテストライブラリです。

次のような特徴があります。

軽量
Karmaと違いブラウザを起動する必要がない
初期設定が容易
充実したモック機能
Angular, React, Vue など幅広いサポート

Jest は、Angular 16 から試験的にサポートされるようになりましたが、18の時点でもまだ正式なサポートには至っていません。

とはいえ現時点でも十分使用できますので、今後のことを考えて Jest を選ぶのは全然有りだと思います。

Angualr で Jest を使うには

Karma を使用している場合は Karma を削除したり、angular.json の設定を変更したりする必要があります。
詳細は以下の記事をご参照ください。

↑こちらの記事では Angular Testing Library というテストを書きやすくするライブラリも合わせて導入しています。
このライブラリは Jasmine や Jest に依存していないため、どちらでも気軽に使うことができます。
非常に便利なため、導入することを強くおすすめします。
本稿でも Angular Testing Library を使います。

Jest を使ってみる

以下のコンポーネントを例にして、 Jest を使ったテストを作成してみましょう。
これ自体は2つの数値を入力してボタンをクリックすると足し算した結果が表示されるだけのものです。

calculator.component.ts

import { Component, Input } from '@angular/core';
import { FormsModule } from '@angular/forms';

@Component({
  standalone: true,
  imports: [
    FormsModule,
  ],
  selector: 'calc',
  template: `
    <div class="container">
        <h1>Calculator</h1>
        <input type="number" [(ngModel)]="val1" placeholder="1つ目の数を入力" />
        <span>+</span>
        <input type="number" [(ngModel)]="val2" placeholder="2つ目の数を入力" />
        <button (click)="sum()" [disabled]="disabled">計算する</button>
        <div id="result">結果: {{result}}</div>
    </div>
  `
})
export class CalculatorComponent {
  @Input() disabled: boolean;

  val1: number;
  val2: number;
  result: number;

  sum() {
    this.result = this.val1 + this.val2;
  }
}

まずはテストファイル（.spec.ts）を作成します。

calculator.component.spec.ts

import { render, screen } from '@testing-library/angular';
import { CalculatorComponent } from 'app-ng/src/app/common/components/calculator.component';

// 1
describe('CalculatorComponent', () => {
  // 2
  test('should pass this basic test', async () => {
    const result = 1 + 2;
    // 3
    expect(result).toBe(3);
  });
});

describe test exect は Jest の関数です。

テストファイルでは、Jest はそれぞれのメソッドとオブジェクトをグローバル環境に配置します。それらを使用するために require または import する必要はありません。

1. `describe(name, fn)`

いくつかの関連するテストをまとめるのに使用します。
必須ではないため、省略することもできます。

2. `test(name,fn, timeout)`

テストメソッドです。
これは必須です。必ず一つは test を実装する必要があります。

import { render, screen } from '@testing-library/angular';
import { CalculatorComponent } from 'app-ng/src/app/common/components/calculator.component';

// describe を使わずに直接 test を書くこともできます
test('should pass this basic test', async () => {
  ...
});

3. `expect`

アサーション関数です。
実際の値が期待する値と一致しているかどうかを確認するために使います。

よく使うアサーションの一覧

関数名	説明
toBe(expected)	厳密な一致を確認する。（値と型が一致している必要がある）例： expect(1 + 2).toBe(3);
toBeNull()	値が null であるか確認する。
toBeUndefined()	値が undefined であるか確認する。
toEqual(expected)	オブジェクトや配列の値が等価であるかを確認する。例： const data = { name: 'John', age: 30 }; expect(data).toEqual({ name: 'John', age: 30 });
toBeTruthy() toBeFalsy()	真偽値を確認する。例： expect(true).toBeTruthy(); expect(false).toBeFalsy();
toBeGreater[Less]Than(expected) toBeGreater[Less]ThanOrEqual(expected)	数値を比較する。例： expect(10).toBeGreaterThan(5); // 10 > 5 expect(10).toBeGreaterThanOrEqual(10); // 10 >= 10 expect(10).toBeLessThan(15); // 10 < 15 expect(10).toBeLessThanOrEqual(10); // 10 <= 10
toContain(expected)	配列や文字列の中身を確認する。例： const fruits = ['apple', 'banana', 'grape']; // 配列に 'banana' が含まれている expect(fruits).toContain('banana'); // 文字列に 'world' が含まれている expect('hello world').toContain('world');
toThrow	エラーであることを確認する。例： const throwError = () => { 　throw new Error('This is an error'); }; // エラーが投げられることを確認 expect(throwError).toThrow(); // エラーメッセージも確認 expect(throwError).toThrow('This is an error');

DOM のテスト

数値を渡して[計算する]ボタンをクリックし、結果が正常に表示されることを確認します。

calculator.component.spec.ts

import { fireEvent, render, screen } from '@testing-library/angular';
import { CalculatorComponent } from 'app-ng/src/app/common/components/calculator.component';

describe('CalculatorComponent', () => {
  test('should render the result as 3', async () => {
    // 1. テストテンプレート上で対象のコンポーネントを呼び出す
    await render(`<calc [a]="1" [b]="2"></calc>`, {
      imports: [
        CalculatorComponent,
      ],
    });
    
    // 2. [計算する]ボタンをクリックする
    fireEvent.click(screen.getByRole('button'));

    // 3. <p>タグに表示される文字列を確認する
    expect(screen.getByRole('paragraph').textContent).toContain('結果: 3');
  });
});

実行結果

render fireEvent screen は Angular Testing Library のメソッドです。

1. `render`

テストアプリのセットアップを行うための関数です。
上記の例では、第一引数にテンプレート文字列を渡しており、そこでテスト対象のコンポーネントを呼び出しています。
イメージとしてはテストメソッドごとに専用のコンポーネントを作成するような感じです。
ここでは <calc> を実行するだけのコンポーネントを作成しています。
この方法だと実際の使われ方と同じようにテストできるため、テンプレート方式を推奨しています。

await render(`<calc [a]="1" [b]="2"></calc>`, {
      imports: [
        CalculatorComponent,
      ],
    });

第二引数にはオプションを設定します。
例では、テスト対象のコンポーネントは standalone のため、render関数の第二引数で imports プロパティにテスト対象を追加しています。

2. `fireEvent`

DOMイベントを発火させるための関数です。
上記の例では、テスト対象のコンポーネントの[計算する]ボタンのクリックイベントを発火しています。

3. `screen`

レンダリングされたテスト対象のDOMツリーにアクセスするためのグローバルオブジェクトです。
DOMにクエリ（要素を検索する等）を実行する際に使います。
上記の例では、screen.getByRole('button') と creen.getByRole('paragraph') でそれぞれ[計算する]ボタンと結果を表示する <p> タグへアクセスしています。
クエリの詳細は公式ドキュメントをご参照ください。

基本的にこの３つの関数を使用してテストを作成していきます。

`@Input` のテスト

先ほどのテストは @Input のテストも兼ねていました。
render の第一引数にテンプレートを渡すと、そのまま実際の使い方と同じように @Input に値を設定できます。

describe('CalculatorComponent', () => {
  test('should render the result as 3', async () => {
    // 1. テストテンプレート上で対象のコンポーネントを呼び出す
    await render(`<calc [a]="1" [b]="2"></calc>`, {
      imports: [
        CalculatorComponent,
      ],
    });
    ...
  });
});

`@Output` のテスト

CalculatorComponent に計算結果を返すアウトプットを追加して、テストを書いてみます。

calculator.component.ts

import { Component, EventEmitter, Input, OnInit, Output } from '@angular/core';
import { FormsModule } from '@angular/forms';

@Component({
  standalone: true,
  imports: [
    FormsModule,
  ],
  selector: 'calc',
  template: `
    <div class="container">
        <h1>Calculator</h1>
        <input type="number" [(ngModel)]="val1" placeholder="1つ目の数を入力" />
        <span>+</span>
        <input type="number" [(ngModel)]="val2" placeholder="2つ目の数を入力" />
        <button (click)="sum()" [disabled]="disabled">計算する</button>
        <p>結果: {{result}}</p>
    </div>
  `
})
export class CalculatorComponent implements OnInit {
  @Input() a: number;
  @Input() b: number;
  @Input() disabled: boolean;
  @Output() calculated = new EventEmitter<number>();

  val1: number;
  val2: number;
  result: number;

  ngOnInit() {
    this.val1 = this.a;
    this.val2 = this.b;
  }

  sum() {
    this.result = this.val1 + this.val2;
    this.calculated.emit(this.result);
  }
}

calculator.component.spec.ts

  test('should emit (calculated) on "Calculate" button click', async () => {
    // モック関数を作成する
    const onCalculatedSpy = jest.fn();
    await render(CalculatorComponent, {
      inputs: {
        a: 1,
        b: 9,
      },
      on: {
        calculated: onCalculatedSpy
      }
    });

    // [計算する]ボタンをクリックする
    fireEvent.click(screen.getByRole('button'));

    // モック関数が正しい引数で呼び出されたことを確認
    expect(onCalculatedSpy).toHaveBeenCalledWith(10);
    // モック関数の呼び出し回数をを確認
    expect(onCalculatedSpy).toHaveBeenCalledTimes(1);
  });

モック関数 `jest.fn()`

Output に設定した関数の振る舞いを監視するには、モック関数を使います。
モック関数を作成するには、jest.fn() を使用します。

まずは[計算する]ボタンのクリック後に実行される関数をモック化します。

const onCalculatedSpy = jest.fn();

作成したモック関数をコンポーネントに設定します。

await render(CalculatorComponent, {
  inputs: {
    a: 1,
    b: 9,
  },
  on: {
    calculated: onCalculatedSpy
  }
});

[計算する]ボタンを押下後にモックの振る舞いを確認します。

// モック関数が正しい引数で呼び出されたことを確認
expect(onCalculatedSpy).toHaveBeenCalledWith(10);
// モック関数の呼び出し回数をを確認
expect(onCalculatedSpy).toHaveBeenCalledTimes(1);

Jestは、モック関数を容易に作成できることが特徴のひとつです。
そのほかの詳細は公式ドキュメントをご参照ください。

スナップショットテスト

スナップショットのテストはUI が予期せず変更されていないかを確かめるのに非常に有用なツールです。

引用：https://jestjs.io/ja/docs/snapshot-testing

Jest ではスナップショットのテストを簡単に書くことができます。

  test('renders correctly', async () => {
    const { container } = await render(`<calc [a]="1" [b]="2"></calc>`, {
      imports: [CalculatorComponent]
    });

    expect(container).toMatchSnapshot();
  });

このように toMatchSnapshot() を実行すると、同じフォルダに __snapshots__フォルダが作成されて、その中にスナップショットが作成されます。

calculator.component.spec.ts.snap

// Jest Snapshot v1, https://goo.gl/fbAQLP

exports[`CalculatorComponent renders correctly 1`] = `
<div
  id="root2"
>
  <calc>
    <div
      class="container"
    >
      <h1>
        Calculator
      </h1>
      <input
        class="ng-untouched ng-pristine ng-valid"
        placeholder="1つ目の数を入力"
        type="number"
      />
      <span>
        +
      </span>
      <input
        class="ng-untouched ng-pristine ng-valid"
        placeholder="2つ目の数を入力"
        type="number"
      />
      <button>
        計算する
      </button>
      <p>
        結果: 
      </p>
    </div>
  </calc>
</div>
`;

これでUIに予期せぬ変更が発生した場合、スナップショットのテストでエラーになります。

生成されるスナップショットはコードの変更に追随し、コミットしてコードレビューの対象に含めましょう。

スナップショットを更新する

バグによりスナップショットテストが失敗したときは、原因箇所を修正し、再びスナップショットテストが成功することを確認しましょう。
以下の画像はスナップショットテストに失敗した結果です。

バグではなく、意図的な仕様変更によりスナップショットテストが失敗する場合はスナップショットを更新する必要があります。

jest --updateSnapshot

上記のコマンドを実行すると、失敗するすべてのスナップショットが再生成されます。
特定のスナップショットだけ再生成する場合は以下のコマンドを実行します。

jest --updateSnapshot --testNamePattern=[regex]

実行結果

スナップショットファイルが更新されます。

注意点

スナップショットの乱用を避ける
スナップショットテストは便利ですが、すべてのケースで使用するのは適切ではありません。大規模なスナップショットは、コードレビュー時に変更内容を理解しづらくする可能性があります。スナップショットは小規模で簡潔に保つべきです。
　
アサーションベースのテストとのバランス
スナップショットテストは従来のアサーションベースのテストを完全に置き換えるものではありません。特定のビジネスロジックや動的な動作を確認する場合は、従来のテストが適しています。
　
スナップショットの更新が簡単すぎる
スナップショットを更新するプロセスが簡単であるため、開発者が十分な検証を行わずに更新してしまうリスクがあります。このため、スナップショットの更新が意図的かつ正当であるかをコードレビューで確認することが重要です。
　
変更の意図を明確にする
スナップショットに変化が生じた場合、それが意図的な変更なのか、あるいは意図せずに生じたものなのかを見極める必要があります。これにより、予期しないバグを防ぐことができます。

おわりに

概要は簡単なものになってしまいましたが、少しでも興味を持っていただけるきっかけになれば幸いです。
Jestは日本語ドキュメントも充実しているので、詳細を知りたい方はぜひリンク先をご参照ください。
今回書ききれなかった非同期やもっと複雑なケースについても、いつかまとめたいと思います。

参考
Setup Jest in Angular 18
https://medium.com/ngconf/configure-jest-in-angular-18-79765fdb0fae
Angular After Tutorial#3-1.コンポーネントのテスト
https://zenn.dev/lacolaco/books/angular-after-tutorial/viewer/testing-component
Angular 18 Testing
https://v18.angular.dev/guide/testing
Jest
https://jestjs.io/ja/docs/getting-started
angular-testing-library
https://testing-library.com/docs/