Docs/Core Concepts/Smart Waiting

Smart Waiting

Learn how to wait for elements to appear, disappear, or change state using Predicate's intelligent waiting system. No more arbitrary sleep() delays or flaky tests.

Why Smart Waiting Matters

Web pages load asynchronously. Forms submit in the background. Modals fade in. Traditional approaches use fixed delays that are either too short (causing failures) or too long (wasting time).

The Problem with Fixed Delays

# Bad: arbitrary sleep
button.click()
time.sleep(5)  # Too long or too short?
next_element.click()  # Might not exist yet!

The Predicate Solution

# Good: wait for semantic condition
click(browser, submit_btn.id)
result = wait_for(browser, "role=heading text~'Success'", timeout=10.0)

if result.found:
    print("Form submitted successfully!")

Core Waiting Functions

wait_for()

Wait for an element matching a semantic query to appear:

from predicate import wait_for

# Wait for success message
result = wait_for(browser, "role=heading text~'Success'", timeout=10.0)

# Check result
if result.found:
    print(f"Found: {

Parameters:

query - Semantic query string
timeout - Maximum wait time in seconds
wait_for_disappear - Wait for element to disappear (optional)
poll_interval - How often to check (default: 0.5s)

Returns:

found - true if element was found/disappeared
element - The found element (if found=true)
elapsed_time - Time taken

wait_for_condition()

Wait for a custom condition using a predicate function:

from predicate import snapshot, find, wait_for_condition

def has_items_in_cart():
    snap = snapshot(browser)
    cart_count = find(snap, "role=status text~'items'")
    if cart_count:

Common Patterns

Wait for Page Load

from predicate import PredicateBrowser, wait_for

with PredicateBrowser(api_key="sk_...") as browser:
    browser.page.goto("https://example.com")

    # Wait for main content to load
    result = wait_for(browser,

Wait for Form Submission

from predicate import snapshot, find, click, wait_for

# Submit form
snap = snapshot(browser)
submit_btn = find(snap, "role=button text~'submit'")
click(browser, submit_btn.id)

Wait for Loading to Complete

from predicate import click, wait_for

# Click button that triggers loading
click(browser, button.id)

# Wait for spinner to appear
wait_for(browser, "role=status text~'loading'", timeout=2.0)

# Wait for spinner to disappear

from predicate import click, wait_for, find, snapshot

# Open modal
snap = snapshot(browser)
open_btn = find(snap, "role=button text~'open'")
click(browser, open_btn.id)

Wait for Element Count

from predicate import snapshot, query, wait_for_condition

def has_search_results():
    snap = snapshot(browser)
    results = query(snap, "role=article")
    return len(

Best Practices

1. Use Appropriate Timeouts

# Short timeout for expected fast operations
wait_for(browser, "role=alert", timeout=2.0)

# Longer timeout for slow operations
wait_for(browser, "text~'Processing complete'", timeout=60.0)

2. Always Check Return Values

# Good - check if element was found
result = wait_for(browser, "role=button text~'Next'", timeout=5.0)
if result.found:
    click(browser, result.element.id)
else:
    print("Next button not found")

# Avoid - assuming success
result = wait_for(browser, "role=button text~'Next'", timeout=5.0)
click(browser, result.element.id)  # Might crash if not found!

3. Combine with Error Handling

try:
    result = wait_for(browser, "role=heading text~'Success'", timeout=10.0)
    if result.found:
        print("Operation successful!")
    else:
        print("Success message not found")
except Exception as e:
    print(f"Error while waiting: {e}")

4. Use Semantic Queries for Robustness

# Good - semantic query (survives redesigns)
wait_for(browser, "role=button text~'continue'", timeout=5.0)

# Avoid - ID-based (breaks on changes)
wait_for(browser, "id=btn-continue-2024", timeout=5.0)

Configuration Options

wait_for() Options

Parameter	Type	Description	Default
`query`	`string`	Semantic query	Required
`timeout`	`number`	Max wait time (seconds)	Required
`wait_for_disappear`	`boolean`	Wait for disappearance	`false`
`poll_interval`	`number`	Check interval (seconds)	`0.5`

wait_for_condition() Options

Parameter	Type	Description	Default
`condition`	`function`	Predicate function	Required
`timeout`	`number`	Max wait time (seconds)	Required
`poll_interval`	`number`	Check interval (seconds)	`0.5`

Next Steps

Error Handling → - Handle failures gracefully
Wait API Reference → - Complete waiting API documentation
Examples → - See real-world waiting patterns

Action Execution

Error Handling