lupin.Open console
Browsers

Wait for page readiness without endless sleeps

Use bounded observations to distinguish a loaded document from an application that has finished presenting the needed information.

Lupin editorialAI-assisted3 min read

Readiness has a task-specific meaning

A document can be ready while its account data is still loading, and a busy network can continue long after the useful content appears. Define readiness in terms of the task: the expected record is visible, the correct form is enabled or the source article text is present. Lupin performs bounded document readiness checks after page mutations, but it cannot infer which business signal your workflow needs. State that signal before running the action. This prevents an agent from treating any returned page as complete or waiting indefinitely for activity that never stops.

Understand the built-in navigation wait

The current implementation checks that a requested navigation loader committed and that document.readyState is no longer loading. That avoids reading the previous complete document immediately after a navigation command. It deliberately does not depend on network-idle semantics that many modern sites never satisfy. Protocol commands, evaluation and the complete action have deadlines, and a navigation can return browser_navigation_timeout when readiness is not reached. These are implementation bounds rather than a speed promise. A slow site or blocked subresource may consume the action budget even though part of the page is visible.

Observe after the meaningful transition

After navigate, click or a form interaction, inspect the returned URL and visible state. If a loading indicator remains, issue a bounded follow-up read against the same tab when policy permits. A read observes the page; it should not be replaced with another click on the button that started loading. Track how many observations and how much runtime the workflow is willing to spend. If you control the application, make the completion state explicit in the UI so automation and humans can both see when data is ready or an operation failed.

Illustrative request; source reviewed, not executed against a live provider.
{"action":"read","tab_id":"TARGET_ID_FROM_TABS"}

Do not use arbitrary delay as evidence

A ten-second sleep does not establish that the expected account record arrived. It simply spends time while preserving uncertainty. Likewise, repeated reloads can restart the application's work or invalidate partially entered state. Use a screenshot when the text snapshot cannot explain an overlay or spinner, and compare it with the next page read. If a response was lost after an action, preserve its operation key and inspect the current state before attempting a replacement. Readiness recovery must not accidentally become repeated submission recovery, especially when the original action could have had an external effect.

Stop waiting when the boundary is clear

A login screen, access-denied page, human-verification challenge or unavailable provider is a different condition from ordinary loading. Report it accurately and hand it to the authorized operator when appropriate. The public research reader skips certain blocked or unusable pages rather than describing their snippets as successfully read sources. In a managed session, save the latest observed evidence and unfinished readiness condition before ending or reconciling the browser. A finite runtime lease and inactivity policy still apply while waiting. Useful automation tells the user what remained unready instead of promising an unbounded background wait.

Sources & verification

Reviewed against the current Lupin route, provider adapter and shared input contracts, plus the linked official references. Examples were not run against live services.

Prepared with AI assistance by Lupin editorial. How we research and maintain these guides.

Put it into practice

Give your agent the right tools.

Review the API, workspace requirements and permissions before enabling a workflow.

Explore browsers