Faking Time and Randomness

### Time is a dependency wearing a disguise A function whose body calls `time.monotonic()` has a collaborator that never appears in its signature. Nothing in `def wait_for(check, timeout)` tells a reader — or a test — that the function reaches into a process-wide clock the caller does not own. The practical consequence is that the only lever a test has over the timing branches is *real elapsed time*. To exercise the timeout path the test has to actually wait out the timeout, which makes the suite slow; and because a loaded machine can cross a 50 ms deadline between two statements the test assumed were adjacent, it also makes the suite intermittent. Padding the sleep until it goes green is the classic wrong fix: it buys a slower suite and the same failure at a worse moment. ### The seam: accept the clock as a parameter The cheapest fix is to make the dependency explicit and give it the real implementation as its default: ```python import time def wait_for(check, timeout, clock=time.monotonic): deadline = clock() + timeout while clock() < deadline: if check(): return True return False ``` Production callers pass nothing and behave exactly as before. A test passes a callable of its own and drives the timeline directly. Note the detail that catches people: the default is `time.monotonic`, the *function object*, not `time.monotonic()`, which would evaluate once when the `def` executes and freeze a single timestamp into the signature for the life of the process. ### Writing the fake A fake clock is any zero-argument callable returning a float. A scripted iterator is usually enough — `ticks = iter([0.0, 0.5, 1.5]); clock = lambda: next(ticks)` — and a tiny class with an `advance()` method is better when several assertions share one timeline. Either way the test runs in microseconds, nothing sleeps, and the timeout branch is reached on demand rather than eventually. Because the fake is an ordinary object you can also count its calls, which matters when the code under test is expected to read the clock once per iteration rather than three times. ### Which clock, and why it matters even to the fake `time.monotonic()` never goes backwards and is unaffected by system clock adjustments, so it is the right source for durations, deadlines and backoff. `time.time()` is the wall clock and can jump — an NTP step, a manual correction — so a deadline computed from it may fire instantly or never. `time.perf_counter()` is also monotonic with the highest available resolution and suits benchmarks; `time.monotonic_ns()` returns an integer nanosecond count, which avoids float rounding in a very long-lived process. The zero point of the monotonic clock is undefined, so only *differences* between readings are meaningful — which is precisely why a fake is free to return any floats it likes. ### Injection versus patching Patching the clock with `unittest.mock.patch` also works, and is sometimes the only option when the call sits deep in code you do not own. But it replaces a global for the duration of the test, fixes only the one module you name, and ties the test to how that module happened to import the name. An injected parameter is visible in the signature, expressible as a type hint (`Callable[[], float]`), composes with `functools.partial`, and works the same no matter how the module is imported. A reasonable rule: if the timing logic *is* the thing under test, inject it; if the clock is incidental to what you are asserting, patching is acceptable. ### Sleep is a dependency too The same argument applies to `time.sleep`. A retry loop that sleeps inline cannot be tested without paying the delays; a loop that accepts a `sleep` callable can be handed a recorder, and the test asserts on the requested schedule — `[0.1, 0.2, 0.4]` — instead of waiting 700 ms to observe it. Faking sleep and faking the clock together lets a test assert both the backoff shape and the total budget in no time at all. ### What a fake clock does not buy you A faked clock proves the logic is correct *given a timeline*. It cannot prove behaviour under real scheduler jitter, real GC pauses or a real slow dependency, and it will happily hide a mistaken assumption about how many times the production code reads the clock. Keep at least one slower, realistic test for the integration behaviour, and assert on clock call counts where the number is part of the contract.