Settle class sealed

How a scenario verb waits for the app to be done before it captures.

Every verb — pumpWidget, tap, enterText, screen — applies the same policy, because which verb settles and which does not is exactly the knowledge the high-level API exists to remove. Set it per scenario (scenario('…', settle: …)) and override it per call (s.tap(target, settle: Settle.none)).

The default is Settle.standard, and it is bounded on purpose: pumpAndSettle never converges on a screen holding an indefinite animation — a spinner, a shimmer, a looping Lottie — and throws pumpAndSettle timed out when its ten fake minutes run out. A loading spinner is the first thing most apps show, so the default must survive one: it gives up quietly, captures the frame, and records settled: false on the step. Use Settle.full where a screen that never settles should be an error.

Frames are all a policy can follow, and a scenario needs one more thing. Work that resolves on the real event loop — an asset read from the engine, and the vector_graphics, Lottie or ImageProvider decode on the other end of it — schedules no frame while it is in flight, so no policy here can wait for it: upTo and frames see a quiet tree and elapse advances a clock that real work does not read. Landing that work is a separate step a verb takes after this one, deliberately not a policy: it is not a choice an author makes, and a policy applied by hand through apply — as a plain widget test does — should keep meaning exactly what it says. What a policy does take is the apply hook that waits for such work between its own frames, because a landing that only happens afterwards fills in the last frame and leaves every earlier one with a hole in it.

This is also the one place a run records motion: a policy that owns its pump loop hands every frame to the ScenarioFrameSink a run passes, and pumps at that sink's finer interval while it does. One seam, and no verb had to learn anything — a panel recording a transition and a film recording a whole scenario arrive here as the same hook.

Under ScenarioTime.real every duration here is a real one: tester.pump(interval) on the live binding waits the interval on the wall clock and then a real frame, so upTo(5s) reads "until quiet, at most five real seconds" and elapse(2s) costs two real seconds. Nothing in the policies changes; only what a second is.