When a page counts as settled
okyra listens to events the browser pushes. A page is settled when all of these hold:
- The main frame is not loading.
- No request is in flight. A request running longer than 3 seconds, such as a long poll or a stream, stops counting.
- No short timer a user action started is still pending (see below).
- Nothing has happened for a quiet window: no request, no DOM change.
DOM changes come from a MutationObserver in every document. Changes to the style attribute alone are animation noise and do not count. Waiting sleeps only until the moment the answer could change and wakes early on any new event.
Timers a click started
Many pages show a result a moment after a click, through setTimeout(show, 300). okyra counts timers of 1 second or less that start within 1.5 seconds of a user action or the page load, and timers those start, three deep. It waits for them to fire. A chain that never ends, such as a ticker, stops blocking after 3 seconds. Polling loops and timers started by uncounted timers are not counted.
What each action waits for
| Action | Waits for | If it never settles |
|---|---|---|
goto | The load event (up to 30 seconds), then 500 ms quiet, up to 10 seconds | Returns with "settled": false |
click, type, select, upload, press, scroll | 200 ms quiet, up to 10 seconds | Returns normally |
hover | The page to settle, then reads what appeared | Returns what it found |
text, extract, snapshot, eval | Nothing; they read the page as it is |
A page that never goes quiet, with ads or a live ticker, is reported as not settled instead of failing the step. A goto whose load event does not fire in 30 seconds fails with timed out after 30s waiting for page load.
Separately, a target waits up to 5 seconds for its element to appear, so a step right after a click finds content the click is still rendering.
The wait command
You rarely need it. Use wait when something changes the page that okyra did not do, such as a page that refreshes itself, or to ask for a longer quiet window.
| Form | Does |
|---|---|
okyra wait | Waits for the page to settle with 500 ms quiet, up to 10 seconds. |
okyra wait --quiet-ms 800 --timeout-ms 5000 | Same, with your quiet window and timeout. |
okyra wait --ms 250 | Sleeps 250 ms, nothing else. |
okyra wait
{
"waited_ms": 502
}Unlike the waits after actions, wait fails when the page does not settle in time: timed out after 10s waiting for the page to settle. In a plan it is {"action": "wait"} with the same fields, ms, quiet_ms and timeout_ms. Steps in a plan are the same actions, so they wait the same way and a plan needs no sleeps between steps.