
RAFスタブは、cancelまで揃えてはじめてテストの契約になる
こんにちは、ラジャディです🐾
アニメーションや更新の間引きに使うrequestAnimationFrame(以下RAF)は、テストでは本物が動かないので、スタブに置き換えます。ところが、スタブが「呼べば動く」だけだと、止める処理(cancel)が一度も試されないまま、テストが通ってしまうことがあります。
私のゲームエンジン向けOSSのテストを読み返して、まさにその形を見つけました。この記事では、そのとき確認した事実と、RAFスタブを「契約」として扱うための考え方をまとめます。
先に、この記事で使う言葉を簡単に説明します。
RAF: ブラウザの次の描画タイミングで、登録した処理を呼ぶ仕組み
スタブ: テストの間だけ、本物の機能を偽物に差し替えるもの
cancel: 登録済みのRAFを取り消す処理。cancelAnimationFrameがそれにあたる
fake timers: テストフレームワークが、時間を進める操作を肩代わりする機能
結論
RAFスタブは、requestとcancelを必ず対で差し替える
返すIDは、数値にする。本物のRAFが返すのは整数のIDだから
「cancelが、返ったIDで呼ばれたか」を、テストで確かめる
まず、テストフレームワークが持つ組み込みのfake timersで足りないかを見る
何を見つけたか
筆者のOSSの監視クラスは、更新をRAFでまとめて反映します。止めるときは、保存しておいたIDが数値で、かつcancelAnimationFrameが存在すれば、それで取り消します。そうでなければ、clearTimeoutで取り消します。つまり、止める処理は、IDの型によって通る道が変わります。
この監視クラスを使うUI向けパッケージは、React用とVue用の2つあり、それぞれがテストの初期設定でRAFを差し替えています。同じ目的のはずの2つを読み比べると、差がありました。
Vue用: requestAnimationFrameがIDを数えて返し、待機中のタイマーをMapで管理している。cancelAnimationFrameも差し替えて、対応するタイマーを止めている
React用: requestAnimationFrameをsetTimeoutで差し替え、setTimeoutが返す値(タイマーのハンドル)をそのまま返している。cancelAnimationFrameは差し替えていない
React用の組み合わせでは、止める処理がどの道を通るかは、スタブが返す値の型しだいです(実行時にどちらの道を通っているかは、今回は計測していません)。キャンセルの経路が意図どおりに動いているかを、この初期設定だけでは確かめられません。Vue用の初期設定は、その穴を塞いでいました。
さらに、監視クラス自身のテストでも、IDを自前で数えて管理するスタブを使い、cancelAnimationFrameが「返ったIDで」呼ばれたことまで確認していました。経路ごとにテストを分ける必要があると、私は考えました。
(確認日: 2026-10-11。筆者のリポジトリでの観測です。)
なぜ、cancelまで揃えるのか
MDNは、requestAnimationFrameが返す値を、コールバックの登録を一意に識別する「リクエストID」(符号なし整数)と説明しています。そのIDをcancelAnimationFrameに渡すと、登録を取り消せます。
テストでこの契約を守るなら、スタブは次の3つを満たす必要があります。
呼び出しごとに識別できるIDを返す
返したIDを渡すと、そのコールバックが実際に取り消される
IDの具体的な値そのものには、テストを依存させない
固定IDを返すスタブや、cancelを差し替えないスタブは、2つ目(返したIDで実際に取り消される)を満たせません。複数のRAFが並ぶと、どれを取り消したのかさえ、テストでは見分けられなくなります。
まず、組み込みのfake timersを見る
自作のスタブを書く前に、Vitestの組み込み機能で足りるかを確認しました。Vitestのfake timersは、設定の既定で、グローバルに存在する時間関連のAPIをまとめて偽装します。公式の設定では、既定の対象に、requestAnimationFrame、cancelAnimationFrame、performanceが含まれています(nextTickとqueueMicrotaskは除く)。また、次のフレームまで時間を進めるvi.advanceTimersToNextFrameも用意されています。
ただし、fake timersが偽装するのは、グローバルに存在するAPIだけです。素のNode環境にはRAFがないため、jsdomやhappy-domのようなDOM環境で動かす必要があります。私の環境(Vitest 5.0.3、Node 24.13.0、jsdom)では、requestAnimationFrameで登録した処理が、vi.advanceTimersToNextFrameで実行されることを確認しました。素のNode環境で同じテストを動かすと、RAFが未定義で失敗しました。
つまり、単純な「フレームが来たら呼ばれるか」の確認なら、DOM環境の組み込みfake timersで足り、自作のスタブは要らないかもしれません。自作のスタブが必要になるのは、次のような場面です。
cancelが、返ったIDで呼ばれたかを、呼び出しの記録として確かめたい
待機中のRAFの数を、直接数えたい
古い初期設定との互換のため、グローバルを明示的に差し替えている
テストで確かめること
止めたあとに、待機中のフレームが残っていない
cancelAnimationFrameが、requestが返したIDで呼ばれた
止めたあとに時間を進めても、状態が変わらない
時刻を固定しても、結果が変わらない
最小チェックリスト
requestとcancelを、対で差し替えている
返すIDが、整数になっている
cancelが、返ったIDで呼ばれたことを確かめている
組み込みのfake timersで足りる場面は、組み込みを使っている
共有の初期設定と、個別のテストで、前提がずれていない
まとめ
スタブは、動けばいいだけではありません。requestだけを偽物にすると、cancelの経路は誰にも試されないまま残ります。requestとcancelを対にして、返すIDの型まで本物に寄せると、テストが仕様の説明になります。
まずは、いまのテストの初期設定に、cancelAnimationFrameの差し替えがあるかを探してみてください。
参考
MDN「Window: requestAnimationFrame() method」(2026-10-11確認。リクエストIDの説明の確認に使用): https://developer.mozilla.org/en-US/docs/Web/API/Window/requestAnimationFrame
MDN「Window: cancelAnimationFrame() method」(2026-10-11確認。取り消しの確認に使用): https://developer.mozilla.org/en-US/docs/Web/API/Window/cancelAnimationFrame
Vitest「fakeTimers.toFake」(2026-10-11確認。偽装される既定の対象の確認に使用): https://vitest.dev/config/faketimers
Vitest「vi.advanceTimersToNextFrame」(2026-10-11確認。次のフレームまで進める機能の確認に使用): https://vitest.dev/api/vi
注意事項
この記事の観測は、筆者のOSSリポジトリで2026-10-11に確認したものです。ほかの環境で同じ結果になるとは限りません。テストフレームワークの既定や仕様は変わるため、適用前に公式情報と対象環境で再確認してください。
スタブを差し替えたら、テストごとに元へ戻す(vi.unstubAllGlobalsなど)仕組みを必ず入れ、ほかのテストへ影響が漏れないようにしてください。
次に読むなら
テストの期待値を仕様に寄せると、レビューは終わりやすくなる(公開済み): テストを仕様の説明にする考え方
vi.mock の hoisting 罠を避けて、テストを強くする(公開済み): Vitestのモックの落とし穴
購入者向け実務パック
ここから先は、この作業をそのまま再利用できる成果物です。内容は次の3つです。スタブとテストの雛形は、Vitest 5.0.3、Node 24.13.0、jsdom環境で、実際に動かして通ることを確認しています(2026-10-11)。環境に合わせて、名前と値を置き換えてください。
完成版のRAFスタブ(ID管理とcancel付き)
cancelを確かめるテストの雛形
共有の初期設定を点検するチェックリスト