`editor.flush()` の簡略化を差し戻し、非同期サイドエフェクト完了まで待機する実装に復元

editor.flush() の実装を getEditorState().read(() => {}) に簡略化したコミットを差し戻し、editor.update() と requestAnimationFrame を組み合わせた元の実装に戻しました。簡略化された形式がエディタの非同期サイドエフェクトの完了を保証できないことが判明したためです。

背景

簡略化されたコミット f01a49a8（"Simplify editor flush to just force a read cycle"）は、editor.flush() を単一の getEditorState().read(() => {}) 呼び出しに削減していました。この変更の意図は「エディタの状態を安定させるためのシグナル」として機能させることでしたが、実際にはその目的を果たせないことが確認されました。

read() 呼び出しは同期的に完了しますが、エディタにはトランスフォームや RAF（requestAnimationFrame）スケジュールされたディスパッチといった非同期サイドエフェクトが存在します。これらの処理が完了する前に flush() が返ってしまうため、テストヘルパーとして「エディタが安定した状態に達した」ことを示すシグナルとして機能しませんでした。

技術的な変更

test/browser/helpers/editor_handle.js の flush() メソッドが、getEditorState().read() による簡略実装から、editor.update() と requestAnimationFrame を組み合わせた実装に差し戻されました。

変更前（簡略化された実装）:

async flush() {
  await this.locator.evaluate((el) => {
    return el.editor.getEditorState().read(() => {})
  })
}

変更後（復元された実装）:

async flush() {
  await this.locator.evaluate((el) => {
    return new Promise((resolve) => {
      el.editor.update(
        () => {},
        { onUpdate: () => requestAnimationFrame(resolve) },
      )
    })
  })
}

復元された実装では、空の editor.update() を発行することで保留中のすべての更新をコミットさせ、さらに onUpdate コールバック内で requestAnimationFrame(resolve) を呼び出すことでDOMとリコンサイラが1フレーム分の処理を完了してから Promise を解決します。

設計判断

「エディタを安定させる」という操作には、同期的な状態読み取りではなくレンダリングサイクルの完了を待機することが必要という判断が、この差し戻しの核心です。

getEditorState().read() は副作用のない純粋な状態スナップショット取得であり、ペンディング中の更新キューやRAFキューには一切触れません。対して editor.update() を発行すると、エディタは保留中のすべてのトランスフォームと更新を処理した上で onUpdate を呼び出します。そこからさらに requestAnimationFrame を挟むことで、DOM反映を含むブラウザの描画サイクル1回分が完了した後に制御が戻ります。

テストヘルパーにおいて「settle the editor」のセマンティクスを正確に表現するには、この2段階の待機（更新コミット → RАФ待機）が欠かせないことが、今回の差し戻しによって明確化されました。

まとめ

今回の差し戻しは、コードの簡略化が「動作する」ことと「意図通りに安定を保証する」ことの違いを示した好例です。editor.flush() が提供すべきセマンティクス（非同期サイドエフェクトを含めたエディタの安定保証）に対して、実装がそれを満たしているかを検証することが、テストヘルパーの信頼性維持において重要だと改めて示しています。