Angularのsignalとeffectをテストで固定するときの落とし穴

effect はスケジューラに登録されるだけで、登録した時点では走らない。

@angular/core 22.2.1 の createRootEffect
function createRootEffect(fn, scheduler, notifier) {
  const node = Object.create(ROOT_EFFECT_NODE);
  node.userFn = fn;
  node.fn = createEffectFn(node, fn);
  node.scheduler = scheduler;
  node.notifier = notifier;
  node.zone = typeof Zone !== 'undefined' ? Zone.current : null;
  node.scheduler.add(node);
  node.notifier.notify(12);
  return node;
}

notify(12) は ApplicationRef.dirtyFlags に 16 を立て、synchronizeOnce() がその旗を見て rootEffectScheduler.flush() を呼ぶ。つまり実行は変更検知の一部であり、set の呼び出しとは別の契機で起きる。テストでこの契機を与えないまま assert すると、effect の中身が1度も走っていない状態で通る。

@angular/core 22.2.1 / TestBed.runInInjectionContext で effect を作り、count を読ませた場合
1) effect 生成直後(tick なし)    : []
2) count.set(1) の直後(tick なし): []
3) TestBed.tick() のあと           : [1]
4) set(2) set(3) のあとの tick 1回 : [1,3]

3行目に 0 が無く、4行目に 2 が無い。この2つがレビューで最初に見る点になる。

effectの初回実行が走る位置

effect の初回実行も、生成時ではなく最初の実行の機会に起きる。したがって set を先に済ませたテストでは、初期値を読んだ実行がそもそも存在しない。上の3行目で記録されたのが 1 だけなのはこのためである。

「初期値で1回、更新で1回」を前提に実行回数を2と期待したテストは、set と TestBed.tick() の並び順で結果が変わる。並び順を直して回数を合わせても、固定できたのは回数だけで、どの値で走ったかは確かめていない。

4行目はもう1つの前提を崩す。set を2回続けてから tick を1回呼ぶと、実行は1回で、読まれる値は最後の 3 である。EffectScheduler が flush() まで登録を溜めるため、間の値は effect からは見えない。中間状態を検査したいなら、set のあいだに TestBed.tick() を挟んで区切る。

Comment
@Reviewer: この検査は `items.set([...])` を2回続けたあとに `TestBed.tick()` を1回呼んでいるので、`effect` は1回しか走らず、1回目の値は読まれません。送信回数を2と期待している箇所が、たまたま別の理由で通っています。各 `set` のあとに `TestBed.tick()` を入れて区切ってください。

実行の機会を同期的に与える呼び出しは TestBed.tick() である。TestBed.flushEffects() は 22.2.1 の型定義で @deprecated use TestBed.tick() instead が付いており、実装も tick() を呼ぶだけになっている。

@angular/core 22.2.1 の TestBedImpl
flushEffects() {
  this.tick();
}
tick() {
  const appRef = this.inject(ApplicationRef);
  try {
    appRef.includeAllTestViews = true;
    appRef.tick();
  } finally {
    appRef.includeAllTestViews = false;
  }
}

ただし tick は唯一の機会ではない。notify を受けた ChangeDetectionSchedulerImpl は、shouldScheduleTick() が真なら変更検知を予約する。予約は requestAnimationFrame と setTimeout の競争で取られるので、テストが await で制御を返した時点で走る。

set のあとに await を挟んだ場合(tick は呼んでいない)
1) effect 生成直後            : []
2) マイクロタスク1つぶん await: []
3) setTimeout(0) を await     : [0]
4) set(1) の直後(同期)      : [0]
5) set のあと setTimeout(0)   : [0,1]

2行目でまだ走っていない点が、この予約の性質を示している。マイクロタスクでは足りず、マクロタスクを1つ消化する必要がある。つまり tick を書き忘れたテストは、同期で assert していれば落ち、途中に await が1つ入っていれば通る。非同期のテストに tick が無いことは、それ自体では誤りにならない。レビューでは、await の位置が確かめたい実行より前にあるかを見る。

コンポーネントの中で作った effect は、同じ effect() の呼び出しでも別の種類のノードになる。注入器に ViewContext があれば createViewEffect が選ばれ、consumerMarkedDirty はビューに旗を立てて notify(13) を呼ぶ。実行はそのビューの変更検知に乗るので、fixture を作って detectChanges() を呼ぶか、TestBed.tick() を呼ぶかのどちらかが要る。

コンポーネントのコンストラクターで作った effect
1) createComponent の直後 : []
2) detectChanges のあと    : ["A"]
3) set して TestBed.tick() : ["A","B"]

tickが関係しない検査

computed は読まれた時点で評価されるため、テストに tick は要らない。

computed(tick を挟まずに読む)
price=100 で total を読む : 200
price.set(200) のあと     : 400

linkedSignal も同じで、リセットの契機は source の更新ではなく読み取りである。

linkedSignal(options の先頭を初期値にし、b を選んだあと)
set('b') のあと          : b
options を差し替えた直後 : x

2行目は TestBed.tick() を呼んでいない。差し替えた配列の先頭が、次に読んだ時点で入る。この機構はAngularのlinkedSignalがeffectによるリセット実装を置き換える場面にまとめた。

レビューで見るのは、この2つに tick が入っているかではなく、依存を変えたあとに読み直しているかである。computed を1度だけ読んで値を変数に受け、そのあとで依存を変えて同じ変数を assert したテストは、再評価を確かめていない。tick を足しても何も変わらない。

Comment
@Reviewer: `const total = sut.total();` で受けたあとに `price.set(...)` しているので、assert しているのは差し替え前の値です。`computed` は読んだ時点で評価されるため、`sut.total()` をもう一度呼ぶ形に変えてください。`TestBed.tick()` はこの検査には関係しません。

resourceのstatusを通すための待ち合わせ

resource の読み込みは tick では終わらない。loader が返す Promise は tick の外で解決するため、同期的に呼ぶ TestBed.tick() を何回重ねても status は loading のままである。

loader が即座に解決する Promise を返す resource
TestBed.tick() を1回       : status=loading
さらに2回                  : status=loading
whenStable を待ったあと    : status=resolved / value=値

待てる理由は、読み込みが PendingTasks に登録されることである。実装は取得を始める前に this.resolvePendingTask = this.pendingTasks.add() を呼び、解決か失敗で外す。ApplicationRef.whenStable()(fixture があれば fixture.whenStable())はこの登録が残っているあいだ解決しない。tick と whenStable のどちらを呼ぶかではなく、Promise の解決を待つ必要があるかどうかで選ぶ。

status の6値は、テストで通す手順がそれぞれ違う。

status 通す手順 hasValue()
idle params が undefined を返す状態にする 偽
loading 生成した直後、または params を変えた直後 偽
resolved loader を解決してから whenStable を待つ 真
local set() か update() でローカルに書く 真
reloading 値があるところで reload() を呼ぶ 真
error loader を reject してから whenStable を待つ 偽

error 状態で value() を読むと例外になるので、error の検査は value() ではなく error() を読む形になる。文面は Resource is currently in an error state (see Error.cause for details): <元のエラー> で、元の例外は cause に入る。この契約はAngularのResourceでhasValue()を省いた実装をレビューで止めるで扱った。

params が undefined を返すあいだは idle で、loader は呼ばれない。条件付きで取得する resource のテストで、取得しない側の分岐を確かめる位置がここになる。取得を止める意図で書いた分岐が、実際には undefined ではなく空のオブジェクトを返していれば、idle を期待したテストが loading を受け取って落ちる。

httpResourceの要求が出る時点

httpResource の status は生成した直後から loading だが、要求はまだ出ていない。

httpResource と HttpTestingController(jsdom 上で測定)
1) 生成直後            : status=loading / 要求 0件
2) TestBed.tick() の後 : status=loading / 要求 1件
3) flush + whenStable  : status=resolved

この差は、Resource の実装が status と取得を別の仕掛けで持っていることから出る。status の元になる state は linkedSignal で、その計算が params の結果を見て 'loading' を入れる。一方の取得は effect(this.loadEffect) の中で始まる。つまり status は読んだ時点で評価され、要求は前の2節と同じ実行の機会を待つ。

status を assert するだけのテストでは、この差は表に出ない。expectOne を先に書いたテストは、取得の有無ではなく実行の機会の不足で落ちる。

tick を呼ばずに expectOne を書いた場合
Expected one matching request for criteria "Match URL: /api/item", found none.

逆に、要求に応答を返さないまま whenStable() を待つと解決しない。要求が PendingTasks に登録され、flush も error も呼ばれないまま残るためである。

応答を返さずに whenStable を待った場合(1秒で打ち切り)
1) 待った結果     : 時間切れ
2) そのときの要求 : 1件
3) そのときの状態 : status=loading

2行目で要求が1件に増えている。ApplicationRef.whenStable() の実装は isStable を購読するだけで、変更検知を動かすものではない。要求が出たのは、await で制御を返したあいだに予約された変更検知が走ったからである。止まるのは応答を待つところで、テストが時間切れで落ちたときは verify() の前に flush を忘れた箇所を探す。httpResource と手組みの HttpClient の選び分けはAngularのhttpResourceとHttpClientの手組みをどちらで書くかにある。

Comment
@Reviewer: `httpResource` を作った直後に `expectOne('/api/user')` を書いているので、要求が出る前に検査しています。`status()` が `loading` を返すのは要求の有無とは別なので、`TestBed.tick()` を挟んでから `expectOne` してください。応答は `flush` で返し、最後に `verify()` を呼ぶ形に揃えてください。

注入コンテキストとテスト間の持ち越し

effect と resource は注入コンテキストの中でしか作れない。テストでは TestBed.runInInjectionContext で囲むか、injector オプションを渡す。

注入コンテキストの外で effect を呼んだ場合
NG0203: effect() can only be used within an injection context such as a constructor,
a factory function, a field initializer, or a function used with `runInInjectionContext`.

TestBed.resetTestingModule() は注入器を破棄し、そこで作った effect の onCleanup を呼ぶ。破棄後に依存の signal を書き換えても effect は走らない。

effect の後片付け(trigger を読む effect)
実行 [0,1] / onCleanup [0]
resetTestingModule のあと : onCleanup [0,1]
破棄後に set して tick     : 実行 [0,1]

後片付けが済む範囲は、注入器に属するものだけである。providedIn: 'root' のサービスはテストごとに作り直されるが、モジュールの直下に置いた signal は同じ実体が残る。

テスト間の持ち越し
1つめのテストでサービスの signal に set(5) : 5
resetTestingModule 後に注入し直して読む     : 0(別の実体)
モジュール直下に置いた signal               : 7(持ち越される)

テストファイルの先頭で const state = signal(...) と書いた共有状態は、beforeEach で初期化しない限り順序に依存する。TestBed の後片付けはここまで届かない。

toSignal に requireSync を渡している箇所は、同期発行が崩れたときのテストを置く位置になる。同期で発行しない Observable を渡すと NG0601 で落ちる。

requireSync を指定した toSignal
of(1) を渡した場合      : 1
Subject を渡した場合    : NG0601: `toSignal()` called with `requireSync` but `Observable` did not emit synchronously.

of と startWith で同期発行を保っている実装は、間に非同期の演算子が1つ入った時点でこの例外に変わる。例外になるだけで値は壊れないので、検査を置く価値があるのは発行の経路を変えた差分のほうである。rxjs との境界の契約はAngularのtoObservableをイベント列として使う実装をレビューで止めるにまとめた。

レビュー観点チェックリスト

signal と effect のテストを確かめる項目
  • effect を使うテストが、set のあとに実行の機会(TestBed.tick() か await)を挟んでいるか
  • set と TestBed.tick() の並び順が、確かめたい実行の回数と値に合っているか
  • await の位置に依存して結果が変わる検査を、tick で明示する形に直せないか
  • 初期値で走る実行を期待している箇所が、set より前に tick を呼んでいるか
  • 連続した set を1回の tick で流していないか(中間の値は読まれない)
  • TestBed.flushEffects() が残っていないか(非推奨。TestBed.tick() に置き換える)
  • コンポーネントの中の effect を、fixture を作らずに検査していないか
  • computed の検査が、依存を変えたあとに読み直しているか
  • linkedSignal の検査が、source を変えたあとに読んでいるか(読まなければリセットは起きない)
  • computed と linkedSignal の検査に、意味のない tick が入っていないか
  • resource の検査が tick ではなく whenStable()(または await)で解決を待っているか
  • idle / loading / reloading / error / resolved / local のうち、仕様に関わる status を通しているか
  • error 状態の検査が value() ではなく error() を読んでいるか
  • httpResource の検査が、expectOne の前に TestBed.tick() を挟んでいるか
  • status() が loading であることを、要求が出た証拠として使っていないか
  • flush を返さないまま whenStable() を待っている箇所がないか(時間切れになる)
  • verify() がテストの最後に置かれているか
  • effect と resource の生成が runInInjectionContext か injector オプションを通っているか
  • onCleanup の呼び出しを確かめる検査が、破棄の契機(resetTestingModule か EffectRef.destroy())を明示しているか
  • テストファイルの直下に置いた signal を、beforeEach で初期化しているか
  • requireSync を指定した toSignal に、同期発行が崩れた場合のテストがあるか

おわりに

effect は登録された時点では走らない。初回実行も変更検知まで来ないため、set を先に済ませたテストでは初期値を読んだ実行が存在しない。連続した set は1回にまとまるので、回数を数える検査は tick を挟む位置で結果が変わる。

機会を同期的に与えるのが TestBed.tick() で、await を挟んだテストでは予約された変更検知が代わりに走る。tick の有無だけでは、その検査が実行後の状態を見ているかは決まらない。

computed と linkedSignal は読まれた時点で評価される。この2つに tick を足しても検査の内容は変わらず、確かめる手は依存を変えたあとに読み直すことだけである。

resource と httpResource では、取得を始める契機と解決を待つ手段が分かれている。変更検知が走って初めて要求が出るので、status が loading であることは要求が出たことを意味しない。expectOne の位置は TestBed.tick() の後になる。解決は Promise の解決を待つ必要があり、whenStable() がそれを PendingTasks 経由で待つ。応答を返さないまま待てば時間切れで落ちる。

TestBed 側の変更検知の前提はAngular 22のzoneless構成のコンポーネントテストで崩れる前提で扱った。テストと検証の項目の全体はAngular 22のSignalと非同期状態をレビューする100観点の「テストと検証」の群に並べてある。