Implementation:MarketSquare Robotframework browser Promise To Wait For

Property	Value
Implementation Name	Promise To, Wait For
Type	API Doc
Domains	Test_Automation, Async_Programming
Workflow	Browser_Test_Authoring
Repository	MarketSquare/robotframework-browser

Overview

Concrete tools for running Browser keywords asynchronously and waiting for element states provided by robotframework-browser.

Description

These keywords enable asynchronous execution patterns and element state waiting:

• Promise To: Wraps a Browser library keyword and executes it in a background thread. Returns a Future object immediately while the keyword runs concurrently. The keyword name is resolved by normalizing it (lowercased, spaces and underscores removed) and matching against registered Browser library keywords. Arguments are parsed and type-converted before submission to the thread pool. The method waits until the future is actually running (not just queued) before returning.
• Wait For: Waits for one or more promises (futures) to complete and returns their results. If a single promise is passed, returns its result directly. If multiple promises are passed, returns a list of results. If any promise failed with an exception, that exception is re-raised.
• Wait For All Promises: Waits for all currently unresolved promises to finish. This is a convenience keyword that collects all promises that were started with Promise To but not yet awaited with Wait For.
• Wait For Elements State: Waits for an element to reach a specified state. Supports states: attached, detached, visible, hidden, stable, enabled, disabled, editable, readonly, selected, deselected, focused, defocused, checked, unchecked. Uses Playwright's built-in waiting for DOM states and JavaScript evaluation for logical states (focused, checked, etc.).

Usage

Use Promise To and Wait For together when you need to capture events triggered by user actions (network responses, downloads, navigations). The promise must be created before the triggering action. Use Wait For Elements State when you need to wait for an element to become visible, hidden, enabled, or any other state before proceeding with further interactions.

Code Reference

Source Location

• Repository: robotframework-browser
• Files:
  • Browser/keywords/promises.py Lines 38-73 (promise_to)
  • Browser/keywords/promises.py Lines 226-250 (wait_for)
  • Browser/keywords/promises.py Lines 252-265 (wait_for_all_promises)
  • Browser/keywords/waiter.py Lines 38-139 (wait_for_elements_state)

Signature

# Promise To
@keyword(tags=("Wait",))
def promise_to(self, kw: str, *args) -> Future

# Wait For
@keyword(tags=("Wait",))
def wait_for(self, *promises: Future) -> Any

# Wait For All Promises
@keyword(tags=("Wait",))
def wait_for_all_promises(self) -> None

# Wait For Elements State
@keyword(tags=("Wait", "PageContent"))
def wait_for_elements_state(
    self,
    selector: str,
    state: ElementState = ElementState.visible,
    timeout: timedelta | None = None,
    message: str | None = None,
) -> None

Import

# These are Robot Framework keywords exposed by the Browser library.
# No direct Python import is needed for typical usage.

# Robot Framework usage (in *** Settings ***):
# Library    Browser

I/O Contract

Promise To

Parameter	Type	Default	Description
kw	str	(required)	Name of a Browser library keyword to execute asynchronously.
*args	str	(variadic)	Arguments for the keyword, passed as strings with optional name=value syntax.

Returns	Description
Future	A concurrent.futures.Future object representing the background execution. Pass to Wait For to get the result.

Wait For

Parameter	Type	Default	Description
*promises	Future	(variadic, required)	One or more Future objects returned by Promise To.

Returns	Description
Any	Single result if one promise is provided. List of results if multiple promises are provided. Raises the exception from the promise if it failed.

Wait For All Promises

Parameter	Type	Default	Description
(none)			No parameters. Waits for all unresolved promises.

Returns	Description
None	No return value. Raises exception if any unresolved promise failed.

Wait For Elements State

Parameter	Type	Default	Description
selector	str	(required)	Selector for the element to wait for.
state	ElementState	visible	Target state: attached, detached, visible, hidden, stable, enabled, disabled, editable, readonly, selected, deselected, focused, defocused, checked, unchecked.
timeout	timedelta or None	None	Maximum wait time. Uses library default if not set.
message	str or None	None	Custom error message. Supports {selector}, {function}, and {timeout} format placeholders.

Returns	Description
None	No return value. Raises error if the state is not reached within the timeout.

Usage Examples

*** Settings ***
Library    Browser

*** Test Cases ***
Capture Network Response Triggered By Click
    New Page    https://example.com/api-page
    ${promise}=    Promise To    Wait For Response    matcher=    timeout=3
    Click    \#delayed_request
    ${body}=    Wait For    ${promise}
    Log    Response body: ${body}

Wait For File Download
    New Context    acceptDownloads=True
    New Page       https://example.com/downloads
    ${dl_promise}=    Promise To Wait For Download    /tmp/myfile.pdf
    Click    id=download-button
    ${file_obj}=    Wait For    ${dl_promise}
    Log    Downloaded to: ${file_obj}[saveAs]

Wait For All Promises Without Explicit References
    New Page    https://example.com
    Promise To    Wait For Response    matcher=    timeout=3
    Click    \#submit-button
    Wait For All Promises

Wait For Element To Become Visible
    New Page    https://example.com
    Click    id=show-modal
    Wait For Elements State    id=modal-dialog    visible    timeout=5s

Wait For Element To Disappear
    New Page    https://example.com
    Click    id=close-modal
    Wait For Elements State    id=modal-dialog    hidden    timeout=3s

Wait For Element To Be Enabled
    New Page    https://example.com/form
    Fill Text    id=required-field    some value
    Wait For Elements State    id=submit-btn    enabled    timeout=2s
    Click    id=submit-btn

Wait With Custom Error Message
    New Page    https://example.com
    Wait For Elements State    id=result
    ...    visible
    ...    timeout=10s
    ...    message=Element {selector} did not become {function} within {timeout}

Multiple Promises In Parallel
    New Page    https://example.com/dashboard
    ${resp1}=    Promise To    Wait For Response    url=/api/users    timeout=5
    ${resp2}=    Promise To    Wait For Response    url=/api/stats    timeout=5
    Click    id=refresh-all
    ${results}=    Wait For    ${resp1}    ${resp2}
    Log    Got ${results} responses

Related Pages

Implements Principle

• Principle:MarketSquare_Robotframework_browser_Async_Keyword_Execution