Why can installing a fake clock stop a framework's update scheduling from advancing while a microtask-based flush keeps working?

## What a fake clock actually takes over A fake clock is not a scope around your component. It replaces **shared host entry points** - the functions that register work to run later - for everything running in that process. The product's debounce timer goes through those entry points. So, frequently, does the framework's own batching: many runtimes coalesce a burst of state writes and commit them on a later turn, and the primitive they pick for that later turn is an implementation detail that differs by runtime and by version. The distinction that decides whether faking time breaks your test is whether the framework's deferred work is **time-driven** or not: | Where the framework parks its commit | Frozen by a faked clock? | Symptom in the test | |---|---|---| | the continuation queue, drained after the current task | no | settling works normally; output appears on a yield | | a short timer used to coalesce nearby writes | yes | output never appears until the clock advances | | an animation-frame callback | yes | the same, and often missed because no delay was written anywhere | | an idle callback for low-priority work | yes | low-priority output never lands; high-priority output does | | a host task posted for the next turn | usually yes | behaves like the timer case | Continuation queues are the exception because they are not scheduled *at a time* at all: they drain whenever the call stack empties. Nothing in a clock can hold them, which is why one framework sails through a frozen clock and another goes silent. ## Why the same test passes on one stack and hangs on another A test that does an action, advances the clock and settles encodes an assumption about which mechanism the framework uses. If the runtime drains on continuations, the settle alone is enough and the advance is harmless. If it batches onto a frame callback and the test froze frames, the settle can never succeed - it is waiting for output whose trigger it has disabled. Nothing about the component changed; the test's assumption about the scheduler did. The same effect appears on an upgrade: a runtime that moves its batching from a continuation to a frame callback, or the reverse, silently changes the interleaving your test needed. ## Diagnosing the hang 1. **Run the same test without faking time.** If the output appears, the component is fine and the fake is holding the framework's own work. This single step separates the two hypotheses most reliably. 2. **Ask what is pending on the clock.** Most fake clocks can report how many callbacks are registered and when they are due; a pending entry nobody scheduled from product code is the framework's. 3. **Advance frames and idle callbacks, not just timers.** If output appears once frames are advanced, the commit was frame-parked. 4. **Narrow what you fake.** Take over only the entry point the product's delay uses and leave the rest real; if the hang disappears, the diagnosis is confirmed. 5. **Check the helper you settle with.** A helper that only drains continuations cannot rescue a frame-parked commit, however many times it is called. ## Fixes, and what each costs - **Fake the frame and idle entry points too, and advance them in the settle step.** Fully deterministic, but every settle now has to advance something, so the helper has to be shared or the discipline will not hold. - **Use one helper that advances the clock and drains the queue together.** The best default: tests stop encoding scheduler knowledge, and a version change is absorbed in one place. - **Fake only the timer the product needs.** Simplest, keeps the framework's scheduling alive, and reintroduces a small amount of real waiting for frame-deferred work - usually negligible. - **Do not raise the settle helper's timeout.** The output is not late, it is impossible; a longer timeout only makes the failure slower and teaches the suite that hangs are normal. - **Do not sprinkle extra settles until it passes.** That tunes the test to one scheduler shape and breaks on the next upgrade. ## The wider lesson Faking time is a process-wide intervention, and a framework is a tenant of the same host you just froze. The robust posture is to keep tests ignorant of which primitive the framework uses: assert on committed output, route every advance-and-settle round through one helper, and fake the narrowest set of entry points the behaviour under test actually needs. Then a scheduler change is a one-line fix in the helper rather than a week of intermittent failures spread across the suite.