Wait Actions Guide

Handle dynamic content and user interactions with wait actions.

Overview

Modern websites load content dynamically using JavaScript, AJAX requests, and single-page application (SPA) frameworks. Simple HTML fetching misses this dynamic content because it doesn't wait for JavaScript execution. Browser7's wait actions solve this by allowing you to specify conditions to wait for before capturing the final HTML.

Wait actions give you precise control over page rendering, enabling you to:

• Wait for specific elements to appear or disappear
• Click buttons and interact with the page
• Wait for text content to load
• Add delays for complex JavaScript execution

Why Use Wait Actions?

Dynamic Content Loading

Most modern websites don't include all content in the initial HTML:

• AJAX Requests: Data fetched after page load
• Lazy Loading: Images and content loaded as you scroll
• React/Vue/Angular: SPAs that render content client-side
• API Calls: Price, availability, and product data fetched asynchronously

Without wait actions, you'll capture incomplete HTML before JavaScript finishes loading content.

User Interactions

Some content only appears after user actions:

• Cookie Banners: Block content until dismissed
• Modals and Popups: Need to be closed to access underlying content
• Dropdowns and Menus: Require clicking to reveal options
• Load More Buttons: Pagination requiring interaction

Wait actions can simulate these interactions automatically.

JavaScript Execution

Complex websites require time for JavaScript to execute:

• Framework Initialization: React, Vue, Angular take time to mount
• Data Processing: Client-side data transformation and rendering
• Third-Party Scripts: Analytics, ads, widgets loading asynchronously
• Animation Completion: Transitions and effects that affect layout

Strategic delays ensure JavaScript completes before capturing HTML.

Accurate Data Extraction

Wait actions ensure you capture the final, complete state:

• Price Updates: Wait for final price after discounts applied
• Availability Status: Wait for "In Stock" or "Out of Stock" to appear
• User Reviews: Wait for review content to load
• Search Results: Wait for results to populate after query

How It Works

When you specify wait actions, Browser7:

1. Loads the Page: Navigates to the URL normally
2. Executes Wait Actions: Runs each action in sequence (max 10 actions)
3. Waits for Completion: Each action must complete successfully or timeout
4. Captures HTML: Returns the final HTML after all actions complete
5. Returns Result: Provides both HTML and metadata about execution

Wait actions are executed sequentially in the order you provide them. If any action times out or fails, the render continues but may return incomplete content.

Wait Action Types

Browser7 supports four types of wait actions:

Delay

Wait for a fixed duration.

When to use:

• After interactions that trigger animations
• When timing is predictable and consistent
• As a fallback when other wait types aren't applicable
• Between actions that need time to settle

Parameters:

• duration (required): Milliseconds to wait (100-60000)

Example:

Browser7.waitForDelay(3000)  // Wait 3 seconds

Pros: Simple, always works, predictable timing Cons: Less efficient than condition-based waits, may wait too long or not long enough

Selector

Wait for a DOM element to match a specific state.

When to use:

• Waiting for specific elements to appear
• Ensuring elements become visible after loading
• Confirming elements are removed or hidden
• Most common and reliable wait type

Parameters:

• selector (required): CSS selector to match
• state (optional): 'visible', 'hidden', or 'attached' (default: 'visible')
• timeout (optional): Maximum wait time in milliseconds (default: 30000)

States:

• visible: Element exists, visible, and non-zero size
• attached: Element exists in DOM (may be hidden)
• hidden: Element is not visible or doesn't exist

Example:

Browser7.waitForSelector('.main-content', 'visible', 10000)

Pros: Condition-based (efficient), works for most dynamic content Cons: Requires knowing the exact selector, may fail if selector changes

Text

Wait for specific text content to appear on the page.

When to use:

• Waiting for specific messages or labels
• Confirming status text loads ("In Stock", "Available", etc.)
• Detecting success messages after interactions
• When you know the text but not the element structure

Parameters:

• text (required): Text content to wait for (exact match, case-sensitive)
• selector (optional): CSS selector to limit search scope
• timeout (optional): Maximum wait time in milliseconds (default: 30000)

Example:

Browser7.waitForText('In Stock', '.availability', 10000)

Pros: Don't need to know element structure, works across page changes Cons: Text must match exactly, case-sensitive, may match unintended elements

Click

Click an element on the page.

When to use:

• Dismissing cookie banners, modals, or popups
• Clicking "Load More" buttons
• Expanding collapsed sections
• Triggering dropdowns or menus
• Any interaction that reveals content

Parameters:

• selector (required): CSS selector of element to click
• timeout (optional): Maximum wait time to find element (default: 30000)

Example:

Browser7.waitForClick('.cookie-accept', 5000)

Behavior: Waits for element to be visible and clickable, then clicks it

Pros: Simulates user interaction, reveals hidden content Cons: May trigger navigation or unexpected behavior, requires precise selector

Best Practices

Order Matters

Wait actions execute sequentially - order them logically:

// ✅ Good: Click cookie banner, then wait for content
waitFor: [
  Browser7.waitForClick('.cookie-accept'),
  Browser7.waitForSelector('.main-content', 'visible')
]

// ❌ Bad: Wait for content that's blocked by cookie banner
waitFor: [
  Browser7.waitForSelector('.main-content', 'visible'),  // Will timeout
  Browser7.waitForClick('.cookie-accept')
]

Use Specific Selectors

More specific selectors are more reliable:

// ✅ Specific selector
Browser7.waitForSelector('.product-details .price.final-price', 'visible')

// ❌ Too generic (may match wrong element)
Browser7.waitForSelector('.price', 'visible')

Set Appropriate Timeouts

Balance speed and reliability:

// Fast elements (should appear quickly)
Browser7.waitForSelector('.header', 'visible', 5000)

// Slow elements (AJAX, API calls)
Browser7.waitForSelector('.search-results', 'visible', 15000)

// Very slow (complex JavaScript, heavy computation)
Browser7.waitForSelector('.chart-rendered', 'visible', 30000)

Default timeout: 30000ms (30 seconds)

Combine Wait Types

Use multiple wait types for robust handling:

waitFor: [
  Browser7.waitForClick('.load-more'),           // Click button
  Browser7.waitForDelay(500),                    // Brief delay for animation
  Browser7.waitForSelector('.new-items', 'visible'), // Wait for new content
  Browser7.waitForText('Showing 20 items')       // Confirm load completed
]

Prefer Conditions Over Delays

Use condition-based waits when possible:

// ✅ Better: Condition-based (completes as soon as ready)
Browser7.waitForSelector('.content', 'visible')

// ❌ Worse: Fixed delay (always waits full duration)
Browser7.waitForDelay(5000)

Only use delays when:

• No specific condition to wait for
• After interactions with animations
• As a last resort fallback

Limit Action Count

Maximum 10 wait actions per render. Keep sequences concise:

// ✅ Good: Concise sequence
waitFor: [
  Browser7.waitForClick('.cookie-accept'),
  Browser7.waitForSelector('.content', 'visible'),
  Browser7.waitForDelay(1000)
]

// ❌ Bad: Excessive actions (may fail or be inefficient)
waitFor: [
  Browser7.waitForDelay(1000),
  Browser7.waitForSelector('.header', 'visible'),
  Browser7.waitForDelay(500),
  Browser7.waitForSelector('.nav', 'visible'),
  Browser7.waitForDelay(500),
  Browser7.waitForSelector('.footer', 'visible'),
  Browser7.waitForDelay(1000),
  Browser7.waitForClick('.load-more'),
  Browser7.waitForDelay(2000),
  Browser7.waitForSelector('.results', 'visible')
]

Handle Failures Gracefully

Check timing metrics to detect failures:

const result = await client.render(url, { waitFor: actions });

// Check if wait actions took unusually long (possible timeout)
if (result.timingBreakdown.waitActionsMs > 25000) {
  console.warn('Wait actions took longer than expected');
  // May indicate timeouts or slow loading
}

Common Use Cases

Cookie Banners

Dismiss cookie consent banners before capturing content:

waitFor: [
  Browser7.waitForClick('.cookie-accept'),
  Browser7.waitForSelector('.cookie-banner', 'hidden'),
  Browser7.waitForDelay(500)
]

AJAX-Loaded Content

Wait for content loaded via AJAX requests:

waitFor: [
  Browser7.waitForSelector('.search-results', 'visible', 15000),
  Browser7.waitForText('results found')
]

Single-Page Applications

SPAs take time to initialize and render:

waitFor: [
  Browser7.waitForSelector('#root .app-loaded', 'visible'),
  Browser7.waitForDelay(2000)
]

Infinite Scroll

Load more content by scrolling or clicking:

waitFor: [
  Browser7.waitForClick('.load-more-button'),
  Browser7.waitForDelay(1000),
  Browser7.waitForSelector('.new-results', 'visible')
]

Dynamic Pricing

Wait for price calculations to complete:

waitFor: [
  Browser7.waitForSelector('.price-loader', 'hidden'),
  Browser7.waitForSelector('.final-price', 'visible'),
  Browser7.waitForText('$', '.final-price')
]

Modals and Popups

Close blocking modals before accessing content:

waitFor: [
  Browser7.waitForClick('.modal-close'),
  Browser7.waitForSelector('.modal', 'hidden'),
  Browser7.waitForSelector('.page-content', 'visible')
]

Form Interactions

Fill forms and wait for responses:

waitFor: [
  Browser7.waitForClick('.search-button'),
  Browser7.waitForSelector('.loading-spinner', 'visible'),
  Browser7.waitForSelector('.loading-spinner', 'hidden'),
  Browser7.waitForSelector('.search-results', 'visible')
]

SDK Implementations

See language-specific examples for wait actions:

• Node.js Examples - Wait actions with the Node.js SDK

Python Examples

from browser7 import Browser7, wait_for_click, wait_for_selector, wait_for_text, wait_for_delay

client = Browser7(api_key='b7_your_api_key_here')

# Wait for an element to become visible
result = client.render('https://example.com', wait_for=[
    wait_for_selector('.main-content', 'visible')
])

# Click a cookie banner then wait for content
result = client.render('https://example.com', wait_for=[
    wait_for_click('.cookie-accept'),
    wait_for_selector('.main-content', 'visible'),
])

# Wait for specific text
result = client.render('https://example.com', wait_for=[
    wait_for_text('In Stock', '.availability')
])

# Fixed delay
result = client.render('https://example.com', wait_for=[
    wait_for_delay(2000)  # Wait 2 seconds
])

# Combined: dismiss banner, wait for content, confirm text loaded
result = client.render('https://example.com', wait_for=[
    wait_for_click('.cookie-accept'),
    wait_for_selector('.product-price', 'visible', 15000),
    wait_for_text('$', '.product-price'),
    wait_for_delay(500),
])

PHP Examples

<?php

use Browser7\Browser7Client;
use Browser7\WaitAction;

$client = new Browser7Client('b7_your_api_key_here');

// Wait for an element to become visible
$result = $client->render('https://example.com', [
    'waitFor' => [
        WaitAction::selector('.main-content', 'visible'),
    ]
]);

// Click a cookie banner then wait for content
$result = $client->render('https://example.com', [
    'waitFor' => [
        WaitAction::click('.cookie-accept'),
        WaitAction::selector('.main-content', 'visible'),
    ]
]);

// Wait for specific text
$result = $client->render('https://example.com', [
    'waitFor' => [
        WaitAction::text('In Stock', '.availability'),
    ]
]);

// Fixed delay
$result = $client->render('https://example.com', [
    'waitFor' => [
        WaitAction::delay(2000), // Wait 2 seconds
    ]
]);

// Combined: dismiss banner, wait for content, confirm text loaded
$result = $client->render('https://example.com', [
    'waitFor' => [
        WaitAction::click('.cookie-accept'),
        WaitAction::selector('.product-price', 'visible', 15000),
        WaitAction::text('$', '.product-price'),
        WaitAction::delay(500),
    ]
]);

Related Guides

• CAPTCHA Solving - Combine wait actions with CAPTCHA solving
• Geo-Targeting - Use wait actions with geo-targeted renders
• Error Handling - Handle wait action failures

Troubleshooting

Wait Action Timeout

If wait actions time out:

• ✅ Increase the timeout parameter: Browser7.waitForSelector('.content', 'visible', 60000)
• ✅ Verify the selector matches elements on the page (use browser DevTools)
• ✅ Check if element appears but in wrong state (visible vs attached)
• ✅ Try a different wait type (selector → text, or add delay)
• ✅ Check result.timingBreakdown.waitActionsMs to see actual time taken

Element Not Found

If selectors don't match any elements:

• Use browser DevTools to verify the correct selector
• Check for dynamic class names (React often adds random suffixes)
• Try more generic selectors or wait for parent elements
• Confirm element exists in rendered HTML (not in Shadow DOM)
• Use text-based wait if structure is unpredictable

Click Not Working

If click actions don't trigger expected behavior:

• Verify element is clickable (not covered by another element)
• Increase timeout to ensure element loads: Browser7.waitForClick('.button', 10000)
• Add delay before click to allow page to settle:

  Browser7.waitForDelay(1000),
  Browser7.waitForClick('.button')

• Check if element requires scrolling into view (Browser7 handles automatically)
• Verify click doesn't trigger navigation away from page

Content Still Incomplete

If content is still missing after wait actions:

• Add longer delays after interactions: Browser7.waitForDelay(3000)
• Wait for loading indicators to disappear:

  Browser7.waitForSelector('.spinner', 'hidden')

• Check network timing - some APIs are very slow (30s+)
• Verify JavaScript execution completes (check browser console for errors)
• Try multiple wait conditions to ensure content is truly ready

Too Many Timeouts

If wait actions frequently timeout:

• Reduce timeout values to fail faster: waitForSelector('.content', 'visible', 5000)
• Use more specific selectors that exist earlier
• Remove unnecessary wait actions
• Check if site has anti-bot protections slowing responses
• Consider using delays instead of condition-based waits for unreliable elements

Performance Impact

Wait actions affect render time:

Wait Type	Best Case	Worst Case (Timeout)	Typical
Delay	Exact duration (e.g., 3000ms)	Exact duration	1-5s
Selector	50-500ms (if element exists)	30s (default timeout)	2-10s
Text	50-500ms (if text exists)	30s (default timeout)	2-10s
Click	50-500ms + page response	30s (default timeout) + page response	1-5s

Total render time = Base render time + Wait actions time

Tips for speed:

• Use shorter timeouts for elements that should load quickly
• Prefer condition-based waits over delays (complete faster when ready)
• Minimize number of wait actions (each adds overhead)
• Remove redundant waits that don't affect content capture

Need Help?

• 📚 API Reference - Complete wait actions API documentation
• 💬 Support - Contact our team
• 🐛 Report Issues - SDK-specific issues