JavaScript Instructions

​

How JavaScript Instructions work

1. Page loads - The browser renders the initial page content
2. Wait/Wait_for parameters execute - Global wait conditions are processed first
3. JavaScript Instructions execute - Each instruction runs in order, waiting for completion
4. DOM updates - The page responds to interactions, potentially loading new content
5. Final capture - The complete rendered page is captured after all instructions finish

​

Basic usage

# pip install requests
import requests

url = 'https://www.example.com'
apikey = 'YOUR_ZENROWS_API_KEY'
params = {
    'url': url,
    'apikey': apikey,
    'js_render': 'true',
    'js_instructions': """[{"click":".button-selector"},{"wait":500}]""",
}
response = requests.get('https://api.zenrows.com/v1/', params=params)
print(response.text)

​

Available instructions

​

Click interactions

[
    {"click": ".read-more-button"},
    {"click": "#submit-btn"},
    {"click": "button[data-action='load-more']"}
]

• Expanding collapsed content sections to access full article text
• Navigating through pagination to scrape multiple pages of results
• Triggering modal dialogs or popups that contain additional information
• Activating dropdown menus to access navigation options
• Loading additional content dynamically (infinite scroll triggers)
• Accepting cookie consent banners or terms of service

• Always wait for elements to be clickable before clicking
• Use specific selectors to avoid clicking wrong elements
• Combine with wait_for to handle dynamic content loading
  JSON

  Copy

  Ask AI

  # Example: Click through pagination to scrape multiple pages
  
  [
      {"wait_for": ".product-list"},           # Wait for initial content
      {"click": ".pagination .next-page"},     # Click next page
      {"wait_for": ".product-list"},           # Wait for new content to load
      {"click": ".pagination .next-page"},     # Click next page again
      {"wait": 1000}                           # Final wait for stability
  ]
  

​

Wait for selector

[
    {"wait_for": ".dynamic-content"},
    {"wait_for": "#ajax-loaded-section"},
    {"wait_for": "[data-loaded='true']"}
]

• Content loads asynchronously via AJAX or fetch requests
• Elements appear after animations or CSS transitions
• Waiting for user-triggered content to become available
• Ensuring forms are fully rendered before interaction
• After clicking buttons that trigger content loading
• When dealing with single-page applications (SPAs)

​

Wait for specific duration

[
    {"wait": 1000},    # Wait 1 second
    {"wait": 5000},    # Wait 5 seconds
    {"wait": 500}      # Wait 0.5 seconds
]

• Allowing animations to complete before taking screenshots
• Giving time for slow-loading content when no loading indicator exists
• Preventing rate limiting by spacing requests appropriately
• Ensuring page stability after rapid-fire interactions
• Waiting for third-party widgets or ads to load
• Accommodating server processing time for form submissions

# Example: Handle slow-loading content with strategic waits

[
    {"click": ".load-data-button"},    # Trigger data loading
    {"wait": 3000},                    # Wait for server response
    {"wait_for": ".data-table"},       # Wait for table to appear
    {"wait": 1000}                     # Additional stability wait
]

​

Wait for browser events

[
    {"wait_event": "networkidle"},        # Wait until network is idle
    {"wait_event": "networkalmostidle"},  # Wait until network is almost idle
    {"wait_event": "load"},               # Wait for page load event
    {"wait_event": "domcontentloaded"}    # Wait for DOM to be ready
]

• networkidle - No network requests for 500ms (ideal for SPAs with API calls)
• networkalmostidle - No more than 2 network requests for 500ms (less strict timing)
• load - Page load event fired (all resources including images loaded)
• domcontentloaded - DOM parsing completed (faster than load event)

• Ensure all API calls and resource loading have completed
• Wait for specific browser lifecycle events
• Avoid unnecessary waiting by responding to actual browser state
• Use browser events as more accurate timing signals than fixed delays

​

Fill input fields

[
    {"fill": ["#username", "john_doe"]},
    {"fill": ["input[name='email']", "user@example.com"]},
    {"fill": [".search-box", "search query"]}
]

• Text inputs (single-line text fields)
• Email fields (with built-in validation)
• Password fields (securely handled)
• Search boxes (often trigger autocomplete)
• Textarea elements (multi-line text)
• Number inputs (numeric data entry)

• Login automation for accessing protected content
• Search form submission to find specific content
• Filter application to narrow down results
• Contact form completion for lead generation
• Registration form automation for account creation
• Configuration forms for customizing page content

# Example: Complete a contact form

[
    {"wait_for": "#contact-form"},                   # Wait for form to load
    {"fill": ["#name", "John Smith"]},               # Fill name field
    {"fill": ["#email", "john@example.com"]},        # Fill email field
    {"fill": ["#message", "Hello, I need help..."]}, # Fill message
    {"click": "#submit-button"},                     # Submit form
    {"wait": 10000}                                  # Wait 10 seconds
]

​

Checkbox interactions

[
    {"check": "#agree-terms"},           # Check a checkbox
    {"uncheck": "#newsletter-signup"},   # Uncheck a checkbox
    {"check": "input[name='payment'][value='credit']"}  # Select radio button
]

• Accepting cookie consent or privacy policies
• Selecting payment methods or shipping options
• Configuring notification preferences
• Filtering product catalogs by features
• Agreeing to terms of service during registration
• Enabling optional services or add-ons

​

Select dropdown options

[
    {"select_option": ["#country-select", "USA"]},
    {"select_option": [".size-dropdown", "large"]},
    {"select_option": ["select[name='category']", "electronics"]}
]

• The second parameter must match the value attribute of the option, not the displayed text
• Use the actual value from the HTML, which may differ from what users see
• Works with both single and multiple select elements
• Triggers change events that may load additional content

• Selecting countries for shipping calculations
• Choosing product categories for filtered browsing
• Setting language preferences for localized content
• Selecting time zones or date formats
• Choosing sorting options for search results
• Configuring display preferences (items per page, view type)

​

Vertical scrolling

[
    {"scroll_y": 1000},    # Scroll down 1000 pixels
    {"scroll_y": -500},    # Scroll up 500 pixels
    {"scroll_y": 2000}     # Scroll down 2000 pixels
]

• Social media feeds with scroll loading
• E-commerce sites with lazy-loaded product images
• News sites with continuous article loading
• Search results that load more items on scroll
• Long-form content with progressive disclosure
• Image galleries with scroll-triggered loading

​

Horizontal scrolling

[
    {"scroll_x": 800},     # Scroll right 800 pixels
    {"scroll_x": -400},    # Scroll left 400 pixels
    {"scroll_x": 1200}     # Scroll right 1200 pixels
]

• Product image carousels on e-commerce sites
• Data tables with many columns
• Horizontal navigation menus
• Timeline or calendar interfaces
• Wide charts or graphs
• Panoramic image viewers

​

Execute custom JavaScript (evaluate)

[
    {"evaluate": "document.querySelector('.modal').style.display = 'none';"},
    {"evaluate": "window.scrollTo(0, document.body.scrollHeight);"},
    {"evaluate": "document.querySelector('.load-more').scrollIntoView();"}
]

// Scroll to specific element
"document.querySelector('.target-element').scrollIntoView();"

// Modify page styling
"document.body.style.backgroundColor = '#ffffff';"

// Trigger custom events
"document.querySelector('.button').dispatchEvent(new Event('click'));"

// Access page data
"window.dataLayer = window.dataLayer || [];"

// Remove overlays
"document.querySelectorAll('.overlay').forEach(el => el.remove());"

// Trigger infinite scroll
"window.scrollTo(0, document.body.scrollHeight);"

// Click multiple elements
"document.querySelectorAll('.expand-button').forEach(btn => btn.click());"

• Removing cookie banners or overlay advertisements
• Triggering complex JavaScript functions specific to the site
• Modifying page state to reveal hidden content
• Collecting data from JavaScript variables
• Simulating complex user interactions
• Bypassing client-side restrictions

​

CAPTCHA solving

[
    {"solve_captcha": {"type": "recaptcha"}},
    {"solve_captcha": {"type": "cloudflare_turnstile"}},
    {"solve_captcha": {"type": "recaptcha", "options": {"solve_inactive": true}}}
]

• reCAPTCHA v2 - Standard checkbox and image challenges
• reCAPTCHA v3 - Invisible background verification
• Cloudflare Turnstile - Cloudflare’s CAPTCHA system

[
    {"wait": 3000}, // Wait for 3 seconds to allow the page to load
    {"solve_captcha": {"type": "recaptcha"}},
    {"wait": 2000} // Wait 2 seconds to confirm CAPTCHA resolution
]

​

Working with iframes

​

Frame instructions

[
    {"frame_click": ["#payment-iframe", ".submit-button"]},
    {"frame_wait_for": ["#content-iframe", ".loaded-content"]},
    {"frame_fill": ["#form-iframe", "#email", "user@example.com"]},
    {"frame_check": ["#options-iframe", "#agree-checkbox"]},
    {"frame_uncheck": ["#settings-iframe", "#notifications"]},
    {"frame_select_option": ["#dropdown-iframe", "#country", "USA"]},
    {"frame_evaluate": ["iframe-name", "document.body.style.color = 'red';"]}
]

​

Revealing iframe content

[
    {"frame_reveal": "#payment-iframe"}
]

<div class="iframe-content-element" style="display: none;" data-id="#payment-iframe">
    <!-- Base64 encoded iframe content -->
</div>

​

Using XPath selectors

[
    {"click": "//button[text()='Submit']"},
    {"wait_for": "//div[@class='content' and @data-loaded='true']"},
    {"fill": ["//input[@placeholder='Enter email']", "user@example.com"]}
]

• Text-based selection - Select elements by their text content
• Complex conditions - Use logical operators and functions
• Hierarchical navigation - Navigate parent/child relationships easily
• Attribute matching - Complex attribute-based selection

​

Debugging JavaScript Instructions

params = {
    'js_render': 'true',
    'js_instructions': """[{"click":".button-selector"},{"wait":500}]""",
    'json_response': 'true'  # Enable debugging information
}

​

Understanding the debug report

{
    "instructions_duration": 5041,
    "instructions_executed": 4,
    "instructions_succeeded": 3,
    "instructions_failed": 1,
    "instructions": [
        {
            "instruction": "wait_for",
            "params": {"selector": ".content"},
            "success": true,
            "duration": 1200
        },
        {
            "instruction": "click",
            "params": {"selector": ".button"},
            "success": true,
            "duration": 150
        },
        {
            "instruction": "wait_for",
            "params": {"selector": ".missing-element"},
            "success": false,
            "duration": 30000
        },
        {
            "instruction": "fill",
            "params": {"selector": "#input", "value": "test"},
            "success": true,
            "duration": 80
        }
    ]
}

​

Common use cases and workflows

def automate_registration_form(signup_url, user_data):
"""
Complete multi-step registration process
"""
instructions = [
    # Step 1: Basic information
    {"wait_for": "#registration-form"},
    {"fill": ["#first-name", user_data['first_name']]},
    {"fill": ["#last-name", user_data['last_name']]},
    {"fill": ["#email", user_data['email']]},
    {"click": ".next-step"},
    
    # Step 2: Account details
    {"wait_for": "#account-details"},
    {"fill": ["#username", user_data['username']]},
    {"fill": ["#password", user_data['password']]},
    {"fill": ["#confirm-password", user_data['password']]},
    {"click": ".next-step"},
    
    # Step 3: Preferences
    {"wait_for": "#preferences"},
    {"check": "#newsletter-signup"},
    {"select_option": ["#country", user_data['country']]},
    {"click": ".submit-registration"},
    
    # Step 4: Confirmation
    {"wait_for": ".registration-success"},
]

return requests.get('https://api.zenrows.com/v1/', params={
    'url': signup_url,
    'apikey': 'YOUR_ZENROWS_API_KEY',
    'js_render': 'true',
    'js_instructions': json.dumps(instructions),
})

​

Troubleshooting

​

Common issues and solutions

​

Debugging selector issues

// Test CSS selector
document.querySelector('.your-selector')

// Test XPath
document.evaluate('//your/xpath', document, null, XPathResult.FIRST_ORDERED_NODE_TYPE, null).singleNodeValue

[
    {"wait_for": ".parent-container"},  // Wait for parent first
    {"click": ".child-element"}         // Then interact with child
]

[
    {"click": "#button-id"},                    // Try ID first
    {"click": "button[data-action='submit']"},  // Try attribute
    {"click": "//button[text()='Submit']"}      // Try XPath with text
]

[
    {"click": ".load-content"},         // Trigger content creation
    {"wait_for": ".dynamic-element"},   // Wait for element to appear
    {"click": ".dynamic-element"}       // Then interact with it
]

​

Pricing

​

Frequently Asked Questions (FAQ)