Three Clocks, and Why No Default Works

The Deceptively Simple Task

Take a screenshot of a running application. It sounds like one operation, and in practice it is a timing problem with no universally correct answer, because the only hard question is when is the page finished? — and different applications answer that in incompatible ways.

Clock One: Real Time

Give the page a fixed number of seconds and shoot what is there. The flag sets a ceiling: loading is stopped at that moment if it has not ended sooner, and a page that finishes loading earlier is shot earlier. Either way the clock is blind, because it knows nothing about whether the interface is done. Crude, and correct for a specific class of application: anything that polls continuously. A page that schedules work forever has no moment of quiescence to detect, so a method that waits for the page to go quiet waits indefinitely. For these, a blunt real-time timeout is the dependable way to finish.

Clock Two: Virtual Time

Rather than waiting in real seconds, let the browser run its own clock as fast as it can until a budget of virtual time is exhausted. This is correct for load-once applications, especially those whose startup restores state asynchronously — a session restore that takes an unpredictable real duration but a bounded amount of scheduled work. A fixed real-time wait either cuts these off mid-restore or wastes time on every run to accommodate the worst case.

Pointed at a polling application, the workshop's very first capture hung: its own chat app, which polls status endpoints on a timer, ran for more than five minutes against a nine-second budget, then captured in 3.9 seconds on a real-time timeout. Keep that measurement apart from its explanation. The browser's own contract says virtual time fast-forwards to the next timer whenever nothing else is ready to run and stops once the budget is spent, so recurring timers alone should not keep a budget alive; one of its policies does hold virtual time still while network fetches are pending. The workshop never isolated what held that page — the polling, a fetch left pending, or the wrapper the browser was launched through — and the log's line that the clock never drains is a guess written beside a measurement. The decision did not need the cause: the clock that worked is recorded for that target.

Clock Three: Ask the Page

Some applications defeat both. Interfaces that hydrate in waves are ready in a real sense — nothing is scheduled, real time has passed — but visibly incomplete, showing half-populated rows or skeletons. Neither blind clock can see this, because both are measuring time and the actual question is about state.

The answer is to poll a readiness condition from inside the page and shoot when it reports true. That means each application needs its own definition of ready, which is more work and is the only thing that actually answers the question being asked.

When a resource has no universal readiness signal, the readiness definition belongs to the caller. The temptation is to find one timeout that works everywhere; there isn't one, and the search costs more than accepting per-application knowledge. Encode which clock each target needs, and treat a new target with no entry as a question rather than as a default.

Code

Three strategies, and the property that selects between them·python

class Clock(Enum):
    REAL = "real"        # polls forever -> a blunt timeout reliably finishes
    VIRTUAL = "virtual"  # loads once -> let its own clock run out
    HYDRATED = "ready"   # loads in waves -> ask the page directly


def capture(url: str, out: Path, clock: Clock, ready_js: str | None = None):
    if clock is Clock.REAL:
        args = ["--timeout=8000"]   # a ceiling: shot when loading stops, at the latest here

    elif clock is Clock.VIRTUAL:
        # a polling app hung here once (9 s budget, 5+ min); cause never isolated
        args = ["--virtual-time-budget=20000"]

    elif clock is Clock.HYDRATED:
        # neither blind clock can see a half-populated list
        assert ready_js, "hydration capture needs a readiness predicate"
        wait_until(url, predicate=ready_js, timeout=30)
        args = ["--timeout=500"]

    shoot(url, out, args)


# The clock is a property of the TARGET, not a setting to standardize.
# A new target with no entry here is a question, not a default.

Exercise

Find a wait in your codebase expressed as a fixed sleep before reading some state. Work out what condition that sleep is actually approximating, then replace it with a poll on that condition plus a timeout as a backstop. Note how long the poll actually takes in practice compared to the sleep — usually far less, and occasionally far more, which is the case the sleep was silently getting wrong.

Hint

A fixed sleep encodes two guesses at once: that the condition will be true by then, and that waiting that long is acceptable. Both are usually wrong in opposite directions — too short under load, wastefully long the rest of the time — and separating the condition from the backstop fixes both.

The Deceptively Simple Task

Clock One: Real Time

Clock Two: Virtual Time

Clock Three: Ask the Page

Code

External links

Exercise

Progress

Comments 0