Wait API

Wait for elements to appear using semantic conditions. The wait_for() / waitFor() function automatically optimizes polling intervals based on API usage.

Basic Usage

from sentience import wait_for, click

# Wait for button to appear
result = wait_for(browser, "role=button text~'Submit'", timeout=5.0)
if result.found:
    print(f"Found after {result.duration_ms}ms")
    click(browser, result.element.id)

# Wait for clickable element
result = wait_for(browser, "clickable=true", timeout=10.0)

# Wait with custom interval (local processing)
result = wait_for(browser, "role=button", timeout=5.0, interval=0.5, use_api=False)

Parameters

Python:

• browser (SentienceBrowser): Browser instance
• selector (str): Query DSL selector
• timeout (float): Maximum time to wait in seconds (default: 10.0)
• interval (float, optional): Polling interval in seconds. Auto-detects if None:
  • 0.25s for local extension (use_api=False)
  • 1.5s for remote API (use_api=True)
• use_api (bool, optional): Force server API or local extension. Auto-detects if None.

TypeScript:

• browser (SentienceBrowser): Browser instance
• selector (string): Query DSL selector
• timeout (number, optional): Max time in ms (default: 10000)
• interval (number, optional): Polling interval in ms
• useApi (boolean, optional): Force server or local

Returns

WaitResult with:

• found: Whether element was found
• element: Element object (if found)
• duration_ms: Time taken in milliseconds
• timeout: Whether timeout occurred

Semantic Wait Conditions

You can use any query selector to wait for elements:

# Wait for clickable element
wait_for(browser, "clickable=true")

# Wait for important element
wait_for(browser, "importance>100")

# Wait for visible link
wait_for(browser, "role=link visible=true")

# Wait for specific text
wait_for(browser, "text~'Loading complete'")

Auto-Optimized Polling

The wait function automatically adjusts polling intervals based on whether you're using the server API or local extension:

• Local extension (use_api=False): Polls every 0.25 seconds (fast, no credits)
• Server API (use_api=True): Polls every 1.5 seconds (slower, but includes importance ranking)

This ensures efficient waiting while minimizing API calls when using server-side processing.

Complete Example

from sentience import SentienceBrowser, snapshot, wait_for, click

with SentienceBrowser(api_key="sk_...") as browser:
    browser.page.goto("https://example.com")
    
    # Wait for page to load (wait for any clickable element)
    result = wait_for(browser, "clickable=true", timeout=10.0)
    if not result.found:
        print("Page failed to load")
        return
    
    # Take snapshot
    snap = snapshot(browser)
    
    # Wait for specific button to appear
    result = wait_for(browser, "role=button text~'Submit'", timeout=5.0)
    if result.found:
        click(browser, result.element.id)
    else:
        print("Button not found within timeout")