Implementation:MarketSquare Robotframework browser Wait For Navigation

Wait For Navigation

API documentation for the Wait For Navigation keyword that synchronizes test execution with page navigation events.

Overview

The Wait For Navigation keyword is defined in the Network class and waits until the page has navigated to a URL matching the given pattern. It supports configurable page load states to control when the navigation is considered complete. This keyword is essential for testing page transitions in both traditional multi-page applications and single-page applications (SPAs).

Source Location

Component	File	Lines
`wait_for_navigation` keyword	`Browser/keywords/network.py`	L278-314
`waitForNavigation` (Node.js)	`node/playwright-wrapper/network.ts`	L126-132
`wait_until_network_is_idle` (deprecated)	`Browser/keywords/network.py`	L254-276

Keyword Signature

@keyword(tags=("Wait", "HTTP"))
def wait_for_navigation(
    self,
    url: str | RegExp,
    timeout: timedelta | None = None,
    wait_until: PageLoadStates = PageLoadStates.load,
):

Robot Framework keyword name: Wait For Navigation

Tags: Wait, HTTP

Returns: None. This keyword does not return a value; it simply blocks until the navigation condition is met or the timeout expires.

Parameters

Parameter	Type	Default	Description
`url`	RegExp	(required)	Expected navigation target. Can be an exact URL string or a JavaScript-like regex wrapped in `/` symbols. Examples: `https://example.com/dashboard` (exact match) or `/.\\/dashboard./` (regex match).
`timeout`	None	`None`	Maximum time to wait for navigation. Supports Robot Framework time format (e.g., `10s`, `1 min`). Uses the library's default timeout if not set.
`wait_until`	`PageLoadStates`	`load`	When to consider the navigation operation succeeded. Available values: `load` (default, wait for the `load` event), `domcontentloaded` (wait for `DOMContentLoaded`), `networkidle` (wait for no network activity for 500ms), `commit` (wait for the network response and document start).

PageLoadStates Enum

The PageLoadStates enum is defined in Browser/utils/data_types.py at line 1106:

class PageLoadStates(Enum):
    """Enum that defines available page load states."""
    load = auto()
    domcontentloaded = auto()
    networkidle = auto()
    commit = auto()

Usage Examples

Basic navigation wait after a redirect:

*** Test Cases ***
Wait For Redirect
    Go To    ${ROOT_URL}/redirector.html
    Wait For Navigation    ${ROOT_URL}/posted.html    wait_until=load

Using networkidle for SPA navigation:

*** Test Cases ***
SPA Navigation
    Click    \#dashboard-link
    Wait For Navigation    /.*\\/dashboard.*/    wait_until=networkidle    timeout=15s

Using the Promise To pattern:

*** Test Cases ***
Promise Pattern Navigation
    ${promise}=    Promise To    Wait For Navigation    https://example.com/result    wait_until=domcontentloaded
    Click    \#submit-form
    Wait For    ${promise}
    Get Text    \#result-message    ==    Success

With commit state for fast verification:

*** Test Cases ***
Fast Navigation Check
    Click    \#go-to-page
    Wait For Navigation    /.*\\/target-page/    wait_until=commit    timeout=5s

Internal Execution Flow

The Python keyword opens a gRPC channel and sends a WaitForNavigation request:

response = stub.WaitForNavigation(
    Request().UrlOptions(
        url=Request().Url(
            url=url, defaultTimeout=int(self.get_timeout(timeout))
        ),
        waitUntil=wait_until.name,
    )
)

The Node-side waitForNavigation function (network.ts L126-132) processes the request:

export async function waitForNavigation(
    request: pb.Request.UrlOptions, page: Page
): Promise<pb.Response.Empty> {
    const url = parseRegExpOrKeepString(<string>request.getUrl()?.getUrl());
    const timeout = request.getUrl()?.getDefaulttimeout();
    const waitUntil = <'load' | 'domcontentloaded' | 'networkidle' | 'commit' | undefined>
        request.getWaituntil();
    await page.waitForNavigation({ timeout: timeout, url: url, waitUntil: waitUntil });
    return emptyWithLog(`Navigated to: ${url}, location is: ${page.url()}`);
}

The URL string is parsed by parseRegExpOrKeepString():
- If the string is enclosed in / (with optional trailing flags), it is converted to a JavaScript RegExp.
- Otherwise, it is kept as a plain string for exact URL matching.

Playwright's page.waitForNavigation() is called with the parsed URL, timeout, and waitUntil state.

Upon successful navigation, a log message is returned: "Navigated to: {url}, location is: {page.url()}".

Important Notes

The keyword only works when a page is already loaded. It does not work for the initial page load; use Go To or New Page for that purpose.
URL fragment changes are not detected. If the URL changes only in the hash portion (e.g., #section), the keyword will not recognize this as a navigation event and will time out.
The timeout value is converted to an integer millisecond value via self.get_timeout(timeout) before being sent to the Node side.
The keyword is tagged with both Wait and HTTP tags for categorization in Robot Framework documentation.

Deprecated: Wait Until Network Is Idle

The wait_until_network_is_idle keyword at L254-276 is deprecated. It internally delegates to Wait For Load State with networkidle:

def wait_until_network_is_idle(self, timeout: timedelta | None = None):
    self.library.wait_for_load_state(PageLoadStates.networkidle, timeout)

The migration command rfbrowser transform --wait-until-network-is-idle path/to/test can automatically transform existing keyword usage.

Domains

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment