Auto-waiting vs explicit waits

Timing is the hardest part of browser automation. browserlane handles most of it for you, so you only reach for explicit waits when there's a signal it can't infer.

Actions auto-wait

Every interaction command — bl click, bl fill, bl type, bl hover, bl select, and the rest — auto-waits for the target element to be actionable before acting. "Actionable" means visible, stable, able to receive events, enabled, and (for inputs) editable. You usually don't need an explicit wait before an action.

Interaction commands have a default actionability timeout (for example, bl click defaults to 30s, tunable with --timeout, e.g. --timeout 5s). If the element never becomes actionable in that window, the command fails rather than hanging forever.

When to wait explicitly

Add an explicit wait when you're waiting on something that isn't "an element becoming actionable" — most often after an action triggers navigation or asynchronous work. bl wait has a form for each signal:

Every bl wait form accepts --timeout <ms> (default 30000).

A common pattern — click, then wait for the resulting navigation, then verify:

bl click "button[type=submit]"
bl wait url "/dashboard"
bl screenshot -o after-login.png

bl sleep is the last resort

bl sleep 2000   # pause 2 seconds (max 30000ms)

A fixed bl sleep pauses for a set number of milliseconds regardless of what the page is doing. Use it only when there is genuinely no better signal to wait on — it's slower than necessary when the page is ready early, and flaky when it isn't ready yet. The maximum is 30000ms.

Related

• bl wait and bl sleep in the CLI reference.
• Selectors, refs, and the map/act/re-map loop.