Waiting & Finding Actions

Actions for waiting for elements, page events, and network activity.

waitForElement

Wait for an element to appear in the DOM. Polls until found or timeout.

Value: string (selector)

{ "waitForElement": ".loading-complete" }

Options

Option	Type	Default	Description
timeout	number	10000	Max wait time in ms
visible	boolean | "all"	false	true = must be visible, "all" = wait for all matches visible
save	string	—	Cache the element reference
iframe	string | string[]	—	Look inside iframe

{
  "waitForElement": ".modal",
  "options": { "visible": true, "timeout": 5000 }
}

find

Alias for waitForElement. Behaves identically.

{ "find": ".search-results" }

{
  "find": "#dynamic-content",
  "options": { "timeout": 15000, "save": "content" }
}

findByText

Find the innermost element containing specific text.

Value: string (text to search for)

{ "findByText": "Add to Cart" }

Options

Option	Type	Default	Description
selector	string	"*"	CSS selector to narrow search scope
exact	boolean	false	true = exact match, false = contains
save	string	—	Cache the element
waitFor	boolean	true	Wait for element
timeout	number	10000	Max wait time
iframe	string | string[]	—	Look inside iframe

{
  "findByText": "Submit Order",
  "options": { "selector": "button", "exact": true }
}

Click a Button by Text

[
  { "findByText": "Sign In", "options": { "selector": "button", "save": "signInBtn" } },
  { "click": "$signInBtn" }
]

findByAttribute

Find an element by its attribute value.

Value: [attribute, value]

{ "findByAttribute": ["data-testid", "submit-button"] }

Options

Option	Type	Default	Description
selector	string	"*"	CSS selector to narrow search
exact	boolean	false	Exact match vs contains
save	string	—	Cache the element
waitFor	boolean	true	Wait for element
timeout	number	10000	Max wait time
iframe	string | string[]	—	Look inside iframe

{
  "findByAttribute": ["aria-label", "Close dialog"],
  "options": { "save": "closeBtn" }
}

waitForEvent

Wait for a specific page event.

Value: "load" or "networkIdle"

{ "waitForEvent": "load" }

{ "waitForEvent": "networkIdle" }

Options

Option	Type	Default	Description
timeout	number	10000	Max wait time in ms

networkIdle waits until there are no active network connections for 500ms, useful for waiting for AJAX-heavy pages to finish loading.

{
  "waitForEvent": "networkIdle",
  "options": { "timeout": 15000 }
}

waitForLoad

Wait for the window.load event. Useful after navigation.

Value: (none)

{ "waitForLoad": true }

Options

Option	Type	Default	Description
timeout	number	10000	Max wait time

waitForResponse

Intercept a network response (fetch or XHR) matching a URL pattern.

Value: string (URL pattern — regex or substring)

{ "waitForResponse": "/api/products" }

Options

Option	Type	Default	Description
method	string	null	Filter by HTTP method: "GET", "POST", etc.
timeout	number	10000	Max wait time

{
  "waitForResponse": "api/search\\?q=",
  "options": { "method": "GET", "timeout": 10000 }
}

Returns: The response body (parsed as JSON if possible).

Example: Wait for Dynamic Content

{
  "actions": [
    { "openNewTab": "https://example.com/dashboard" },
    { "waitForEvent": "networkIdle" },
    { "waitForElement": ".data-table", "options": { "visible": true } },
    { "screenshot": "viewport" }
  ]
}

Example: Intercept API Response

{
  "actions": [
    { "openNewTab": "https://example.com/search" },
    { "fill": ["input#search", "laptop"] },
    { "waitForResponse": "/api/search", "options": { "method": "GET", "timeout": 10000 } },
    { "waitForElement": ".results" },
    { "screenshot": "viewport" }
  ]
}