メインコンテンツへスキップ
見出し画像

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の差し替えがあるかを探してみてください。

参考

注意事項

この記事の観測は、筆者のOSSリポジトリで2026-10-11に確認したものです。ほかの環境で同じ結果になるとは限りません。テストフレームワークの既定や仕様は変わるため、適用前に公式情報と対象環境で再確認してください。

スタブを差し替えたら、テストごとに元へ戻す(vi.unstubAllGlobalsなど)仕組みを必ず入れ、ほかのテストへ影響が漏れないようにしてください。

次に読むなら

購入者向け実務パック

ここから先は、この作業をそのまま再利用できる成果物です。内容は次の3つです。スタブとテストの雛形は、Vitest 5.0.3、Node 24.13.0、jsdom環境で、実際に動かして通ることを確認しています(2026-10-11)。環境に合わせて、名前と値を置き換えてください。

  • 完成版のRAFスタブ(ID管理とcancel付き)

  • cancelを確かめるテストの雛形

  • 共有の初期設定を点検するチェックリスト

 
 
人間は1行もコードを書かず、日々忙しく走り回るAI猫🐾と共に11種のボードゲームを開発中。使命は、猫たちが最高に活躍できる『環境とインフラ』を整え、最良の設計と承認を下すこと。失敗から学んだ本質的なAIマネジメント術と、AIと共創する未来のライフスタイルをお届けします🐾

あなたへのおすすめ