Waiting Commands

Waiting commands pause your automation until a specific condition is met. They are essential for handling slow-loading pages, dynamic content, and timing-sensitive interactions. Without proper waits, your automation may try to interact with elements that haven’t loaded yet, causing errors and failed runs.

RTILA X provides five different waiting commands, each designed for a specific waiting scenario. Choosing the right wait command for each situation is one of the most important skills in building reliable automations.

Diagram showing different wait scenarios: page loading, element appearing, file downloading

wait

Pauses the automation for a specified number of milliseconds.

Description

The wait command is the simplest waiting command. It pauses your automation for an exact amount of time, regardless of what’s happening on the page. Use this when you need a fixed delay, such as waiting for an animation to complete or giving a server time to process a request.

Unlike other wait commands, wait does not check any condition. It simply waits for the specified time and then continues.

Parameters

Parameter	Type	Required	Default	Description
`timeout`	number	✅ Yes	`1000`	The number of milliseconds to wait. 1000ms = 1 second.

Examples

Wait 2 seconds:

{
  "command": "wait",
  "params": {
    "timeout": 2000
  }
}

Wait 500 milliseconds:

{
  "command": "wait",
  "params": {
    "timeout": 500
  }
}

Wait 10 seconds for a slow operation:

{
  "command": "wait",
  "params": {
    "timeout": 10000
  }
}

Behavior Notes

The wait is a hard pause. Your automation does nothing during this time.
The timeout is in milliseconds. 1000ms = 1 second, 5000ms = 5 seconds.
Unlike wait_for_selector or wait_for_load_state, this command does not check any condition. It waits the full duration no matter what.
If the page loads faster than your wait time, the automation still waits the full duration.

Tips

Use wait sparingly. Prefer condition-based waits (wait_for_selector, wait_for_load_state) when possible, as they continue as soon as the condition is met.
Use wait for fixed delays like animation timing, rate limiting, or giving servers time to process.
A good rule of thumb: if you’re waiting for something specific to appear, use wait_for_selector instead. If you’re waiting for a fixed amount of time, use wait.
Avoid very long waits (over 30 seconds) unless absolutely necessary. They slow down your automation.

wait_for_load_state

Waits for the page to reach a specific load state, indicating that the page has finished loading to a certain degree.

Description

The wait_for_load_state command waits for the browser’s page load to reach a specific milestone. Different load states represent different stages of page loading, from basic HTML parsing to full network idle.

This is useful after navigating to a new page, submitting a form, or performing any action that triggers a page reload.

Parameters

Parameter	Type	Required	Default	Description
`state`	string	No	`networkidle`	The load state to wait for. Options: `load`, `domcontentloaded`, `networkidle`.
`timeout`	number	No	`30000`	Maximum time to wait in milliseconds. Default is 30 seconds.

Available Load States

State	Description	When to Use
`load`	Waits for the `load` event. All resources (images, scripts, CSS) have finished loading.	When you need all resources fully loaded.
`domcontentloaded`	Waits for the `DOMContentLoaded` event. HTML has been parsed, but images/scripts may still be loading.	When you only need the HTML structure. Faster than `load`.
`networkidle`	Waits until there are no network connections for at least 500ms.	When you need all AJAX/API calls to complete. Best for SPAs.

Examples

Wait for full page load:

{
  "command": "wait_for_load_state",
  "params": {
    "state": "load",
    "timeout": 30000
  }
}

Wait for HTML to be parsed (faster):

{
  "command": "wait_for_load_state",
  "params": {
    "state": "domcontentloaded",
    "timeout": 15000
  }
}

Wait for all network activity to settle (best for SPAs):

{
  "command": "wait_for_load_state",
  "params": {
    "state": "networkidle",
    "timeout": 60000
  }
}

Behavior Notes

networkidle is the most thorough but also the slowest. It waits until there are no network requests for 500ms.
domcontentloaded is the fastest. Use it when you only need the HTML structure and don’t care about images or scripts.
load is a middle ground. It waits for all resources but not for AJAX calls.
If the page doesn’t reach the specified state within the timeout, the command will error.
After a goto command, RTILA X automatically waits for domcontentloaded. You typically only need wait_for_load_state for additional waiting.

Tips

Use networkidle for single-page applications (SPAs) that load data via AJAX.
Use domcontentloaded when you only need the HTML structure and want to proceed quickly.
Use load when you need images and scripts to be fully loaded.
Increase the timeout for slow websites. The default 30 seconds may not be enough for very slow sites.
If networkidle times out frequently, the site may have persistent connections (like WebSockets). Try load instead.

wait_for_selector

Waits for a specific element to appear in the DOM.

Description

The wait_for_selector command pauses your automation until a specific element appears on the page. This is the most commonly used wait command, as it ensures that elements are present before you try to interact with them.

This is especially useful for dynamic content that loads after the initial page load, such as search results, lazy-loaded images, or content loaded via AJAX.

Parameters

Parameter	Type	Required	Default	Description
`selector`	string	✅ Yes	—	The CSS or XPath selector of the element to wait for.
`iframe`	string	No	—	The CSS selector of the iframe containing the element, if applicable.
`timeout`	number	No	`30000`	Maximum time to wait in milliseconds. Default is 30 seconds.

Examples

Wait for a specific element to appear:

{
  "command": "wait_for_selector",
  "params": {
    "selector": "css=.product-list",
    "timeout": 15000
  }
}

Wait for a search results container:

{
  "command": "wait_for_selector",
  "params": {
    "selector": "css=.search-results",
    "timeout": 30000
  }
}

Wait for an element inside an iframe:

{
  "command": "wait_for_selector",
  "params": {
    "selector": "css=.modal-content",
    "iframe": "css=iframe#content-frame",
    "timeout": 10000
  }
}

Behavior Notes

The command waits until at least one element matching the selector exists in the DOM.
The element does not need to be visible. It just needs to exist in the DOM. Use wait_for_state with state: "visible" if you need the element to be visible.
If the element doesn’t appear within the timeout, the command will error.
The selector supports all selector types: css=, xpath=, text=, and variable=.
If the element is inside an iframe, specify the iframe selector in the iframe parameter.

Tips

Use wait_for_selector before every click, fill, or extract_data command that targets a dynamically loaded element.
Increase the timeout for slow-loading content. The default 30 seconds may not be enough.
If you need to wait for an element to be visible (not just present), use wait_for_state with state: "visible" instead.
Use specific selectors to avoid waiting for the wrong element. css=.product-card:first-child is more specific than css=div.
Combine with try_catch to handle cases where the element might not appear.

wait_for_state

Waits for a specific element to reach a specific state (visible, hidden, attached, or detached).

Description

The wait_for_state command is more specific than wait_for_selector. It waits for an element to reach a particular state, not just to exist. This is useful when you need to wait for an element to become visible, hidden, attached to the DOM, or detached from the DOM.

Parameters

Parameter	Type	Required	Default	Description
`selector`	string	✅ Yes	—	The CSS or XPath selector of the element.
`state`	string	No	`visible`	The state to wait for. Options: `visible`, `hidden`, `attached`, `detached`.
`iframe`	string	No	—	The CSS selector of the iframe containing the element, if applicable.
`timeout`	number	No	`30000`	Maximum time to wait in milliseconds. Default is 30 seconds.

Available States

State	Description	When to Use
`visible`	Waits until the element is visible (not hidden by CSS).	When you need to see the element before interacting.
`hidden`	Waits until the element is hidden (display: none, visibility: hidden, or not in DOM).	When waiting for a loading spinner to disappear.
`attached`	Waits until the element exists in the DOM (same as `wait_for_selector`).	When you just need the element to exist.
`detached`	Waits until the element is removed from the DOM.	When waiting for an element to be removed.

Examples

Wait for an element to become visible:

{
  "command": "wait_for_state",
  "params": {
    "selector": "css=.modal-overlay",
    "state": "visible",
    "timeout": 10000
  }
}

Wait for a loading spinner to disappear:

{
  "command": "wait_for_state",
  "params": {
    "selector": "css=.loading-spinner",
    "state": "hidden",
    "timeout": 30000
  }
}

Wait for an element to be removed from the DOM:

{
  "command": "wait_for_state",
  "params": {
    "selector": "css=.toast-notification",
    "state": "detached",
    "timeout": 15000
  }
}

Wait for an element to be attached to the DOM:

{
  "command": "wait_for_state",
  "params": {
    "selector": "css=.dynamic-content",
    "state": "attached",
    "timeout": 20000
  }
}

Behavior Notes

visible means the element is in the DOM and not hidden by CSS (display: none, visibility: hidden, or opacity: 0).
hidden means the element is either not in the DOM or is hidden by CSS.
attached is equivalent to wait_for_selector. The element just needs to exist in the DOM.
detached means the element has been removed from the DOM entirely.
If the element doesn’t reach the specified state within the timeout, the command will error.
For hidden and detached, the command succeeds immediately if the element doesn’t exist.

Tips

Use visible when you need to interact with an element (click, fill, etc.).
Use hidden to wait for loading spinners or overlays to disappear.
Use detached when you need to wait for an element to be completely removed.
Use attached when you just need the element to exist (same as wait_for_selector).
Combine wait_for_state with try_catch to handle cases where the element might not appear.

wait_for_download

Clicks an element and waits for a file to finish downloading, then saves it to a specified path.

Description

The wait_for_download command handles file downloads. It clicks an element (typically a download button or link), waits for the browser to start and complete a file download, and then saves the downloaded file to a specified path.

This is a server-side command, meaning it requires the full RTILA X engine and cannot be previewed in the browser extension.

Parameters

Parameter	Type	Required	Default	Description
`selector`	string	✅ Yes	—	The CSS or XPath selector of the element to click to trigger the download.
`save_path`	string	✅ Yes	`downloaded_file`	The file path where the downloaded file will be saved.
`iframe`	string	No	—	The CSS selector of the iframe containing the element, if applicable.
`timeout`	number	No	`30000`	Maximum time to wait for the download to complete, in milliseconds.

Examples

Download a file by clicking a button:

{
  "command": "wait_for_download",
  "params": {
    "selector": "css=button.download-btn",
    "save_path": "output/report.pdf",
    "timeout": 60000
  }
}

Download a file from a link:

{
  "command": "wait_for_download",
  "params": {
    "selector": "css=a.download-link",
    "save_path": "output/data.csv",
    "timeout": 120000
  }
}

Download from inside an iframe:

{
  "command": "wait_for_download",
  "params": {
    "selector": "css=.download-button",
    "iframe": "css=iframe#download-frame",
    "save_path": "output/document.pdf",
    "timeout": 60000
  }
}

Behavior Notes

This command clicks the element first, then waits for the download to start and complete.
The save_path is relative to the RTILA X output directory. Use forward slashes (/) for paths.
If the download doesn’t start within the timeout, the command will error.
If the download takes longer than the timeout, the command will error.
The downloaded file is saved to the specified path. If the file already exists, it will be overwritten.
This is a server-side command. It cannot be previewed in the browser extension’s Quick Preview mode.
The command waits for the download to complete, not just start. Large files may take a long time.

Tips

Increase the timeout for large files. The default 30 seconds may not be enough for large downloads.
Use descriptive file names in save_path to make it easy to find downloaded files.
Use forward slashes (/) in file paths, even on Windows.
If the download button is inside an iframe, specify the iframe selector.
If the download requires a specific user action (like accepting a terms dialog), handle that before the wait_for_download command.
Combine with file_operation to move or rename the downloaded file after download.

Choosing the Right Wait Command

Here’s a quick reference to help you choose the right wait command for each scenario:

Scenario	Recommended Command	Example
Wait for a fixed amount of time	`wait`	Waiting for an animation
Wait for a page to fully load	`wait_for_load_state` with `load`	After navigating to a new page
Wait for HTML to be parsed	`wait_for_load_state` with `domcontentloaded`	When you only need HTML structure
Wait for all AJAX calls to complete	`wait_for_load_state` with `networkidle`	Single-page applications
Wait for an element to appear	`wait_for_selector`	Waiting for search results
Wait for an element to be visible	`wait_for_state` with `visible`	Before clicking a button
Wait for a loading spinner to disappear	`wait_for_state` with `hidden`	After submitting a form
Wait for an element to be removed	`wait_for_state` with `detached`	Waiting for a toast to disappear
Wait for a file to download	`wait_for_download`	Downloading a report

General Tips

Always use waits before interacting with dynamically loaded elements.
Prefer condition-based waits (wait_for_selector, wait_for_state) over fixed waits (wait) when possible.
Increase timeouts for slow websites. The default 30 seconds may not be enough.
Combine waits with try_catch to handle cases where elements might not appear.
Don’t over-use waits. Too many waits slow down your automation unnecessarily.
Test your waits on different network speeds. A wait that works on fast internet may time out on slow connections.