Waiting Commands

Wait for elements, conditions, and page states

Overview

Waiting commands allow you to pause execution until specific conditions are met, ensuring reliable automation.

wait

Wait for various conditions to be met.

Wait for Element

Wait for an element to be visible.

Parameter	Description
selector	Element selector to wait for

Examples:

# Wait for element by ref
agent-browser wait @e1

# Wait for element by selector
agent-browser wait "#submit-button"

# Wait for element by text
agent-browser wait "text=Welcome"

Wait for Time

Wait for a specific duration.

Parameter	Description
milliseconds	Time to wait in milliseconds

Examples:

# Wait 1 second
agent-browser wait 1000

# Wait 5 seconds
agent-browser wait 5000

Wait for Text

Wait for text to appear on the page.

Option	Description
—text, -t	Text to wait for

Examples:

# Wait for specific text
agent-browser wait --text "Welcome"

# Wait for success message
agent-browser wait -t "Form submitted successfully"

Wait for URL

Wait for URL to match a pattern.

Option	Description
—url, -u	URL pattern to wait for (glob pattern)

Examples:

# Wait for URL containing "dashboard"
agent-browser wait --url "**/dashboard"

# Wait for URL ending with "success"
agent-browser wait -u "**/success"

# Wait for specific URL
agent-browser wait --url "https://example.com/done"

Wait for Load State

Wait for page to reach a specific load state.

Option	Description
—load, -l	Load state: load, domcontentloaded, networkidle

Load States:

State	Description
load	Page load event fired
domcontentloaded	DOM is fully loaded
networkidle	No network activity for 500ms

Examples:

# Wait for page load
agent-browser wait --load load

# Wait for DOM ready
agent-browser wait -l domcontentloaded

# Wait for network idle (recommended for SPAs)
agent-browser wait --load networkidle

Wait for Function

Wait for JavaScript expression to return true.

Option	Description
—fn, -f	JavaScript expression to evaluate

Examples:

# Wait for custom condition
agent-browser wait --fn "window.ready === true"

# Wait for element count
agent-browser wait -f "document.querySelectorAll('.item').length > 0"

# Wait for global variable
agent-browser wait --fn "window.dataLoaded"

Wait for Download

Wait for a file download to complete.

Option	Description
—download, -d	Wait for download
path	Optional: Save download to specific path
—timeout	Optional: Download timeout in milliseconds

Examples:

# Wait for download
agent-browser wait --download

# Wait for download and save to path
agent-browser wait -d "/path/to/file.pdf"

# Wait with custom timeout
agent-browser wait --download --timeout 30000

Workflow Examples

Wait After Navigation

# Navigate to page
agent-browser open example.com

# Wait for page to fully load
agent-browser wait --load networkidle

# Get snapshot
agent-browser snapshot -i

Wait for Dynamic Content

# Click button that loads content
agent-browser click @e1

# Wait for content to appear
agent-browser wait ".results"

# Or wait for specific text
agent-browser wait --text "Results loaded"

Wait for Form Submission

# Submit form
agent-browser click @e5

# Wait for URL change
agent-browser wait --url "**/success"

# Verify success message
agent-browser get text @e1

Wait for AJAX Request

# Trigger AJAX request
agent-browser click @e2

# Wait for network to be idle
agent-browser wait --load networkidle

# Or wait for specific condition
agent-browser wait --fn "window.ajaxComplete === true"

Download File

# Click download button
agent-browser click @e3

# Wait for download to complete
agent-browser wait --download "/path/to/downloads/file.pdf"

Chained Waits

# Navigate and wait
agent-browser open example.com && agent-browser wait --load networkidle

# Click and wait for element
agent-browser click @e1 && agent-browser wait @e2

# Wait for multiple conditions
agent-browser wait --load networkidle && agent-browser wait --text "Ready"

Timeout Handling

The default timeout for wait commands is 25 seconds. Override with the AGENT_BROWSER_DEFAULT_TIMEOUT environment variable:

# Set 45-second timeout
export AGENT_BROWSER_DEFAULT_TIMEOUT=45000
agent-browser wait --load networkidle

Best Practices

Use Network Idle for SPAs

# After navigation, wait for network idle
agent-browser open app.example.com
agent-browser wait --load networkidle

Wait for Specific Elements

# Better than time-based waits
agent-browser wait ".content-loaded"
# Instead of:
# agent-browser wait 3000

Combine Waits

# Wait for load state first
agent-browser wait --load networkidle

# Then wait for specific element
agent-browser wait @e1