Principle:MarketSquare Robotframework browser Page Navigation and Interaction

Property	Value
Principle Name	Page Navigation and Interaction
Domains	Browser_Automation, UI_Testing
Workflow	Browser_Test_Authoring
Repository	MarketSquare/robotframework-browser
Type	Principle

Overview

Navigating web pages and interacting with elements through selectors provides the fundamental building blocks for browser-based test automation.

Description

The Page Navigation and Interaction principle encompasses the two most fundamental operations in browser testing:

1. Navigation: Directing the browser to load a specific URL and waiting for the page to reach a desired load state.
2. Element Interaction: Locating DOM elements using selectors and performing user-like actions on them (clicking, typing, filling forms).

Navigation involves:

• Directing the browser to a URL via explicit navigation keywords.
• Specifying when navigation is considered "complete" through load state options: domcontentloaded, load, networkidle, or commit.
• Receiving the HTTP status code of the navigation response for verification.

Selectors are the mechanism for locating elements on the page. The Browser library supports multiple selector strategies:

• CSS selectors: css=button.submit or simply button.submit
• XPath: xpath=//button[@id='submit'] or //button[@id='submit']
• Text: text=Submit to find elements by visible text content
• ID shorthand: id=submit as shorthand for #submit
• Chained selectors: css=.form >> css=button to navigate through shadow DOM or iframes

Element Interaction follows a consistent pattern before performing any action:

1. Find: Locate an element matching the selector. If none exists, wait until one is attached to the DOM (up to the configured timeout).
2. Actionability checks: Verify the element is in an actionable state (visible, enabled, stable, not obscured). These checks can be bypassed with force=True.
3. Act: Perform the requested action (click, fill, type, etc.).
4. Post-action waiting: Wait for any triggered navigation to settle.

Fill vs Type represents an important distinction:

• Fill (fill_text): Sets the value of an input field directly, triggering a single input event. This is fast and reliable for most form fields.
• Type (type_text): Simulates individual keystrokes (keydown, keypress/input, keyup per character). This is necessary when the application listens for individual key events (e.g., autocomplete, search-as-you-type).

Usage

Use this principle when:

• You need to navigate to specific pages or URLs in your application under test.
• You need to fill out forms, click buttons, or interact with any visible UI element.
• You need to simulate realistic user input including character-by-character typing.
• You need to verify that navigation succeeds by checking HTTP status codes.

Theoretical Basis

NAVIGATE(url, wait_until):
    SEND navigation request to url
    WAIT UNTIL page reaches wait_until state (load, domcontentloaded, networkidle, commit)
    RETURN http_status_code

INTERACT(selector, action, options):
    # Step 1: Find the element
    element = WAIT_FOR_SELECTOR(selector, timeout)
    IF strict_mode AND selector matches multiple elements:
        RAISE strict mode violation error

    # Step 2: Actionability checks (unless force=True)
    IF NOT options.force:
        WAIT UNTIL element is visible
        WAIT UNTIL element is stable (not animating)
        WAIT UNTIL element is enabled
        WAIT UNTIL element is not obscured by other elements

    # Step 3: Perform the action
    IF action == CLICK:
        SCROLL element into view
        COMPUTE click position (center or specified coordinates)
        DISPATCH mousedown, mouseup, click events
    ELIF action == FILL:
        FOCUS element
        CLEAR existing value
        SET value directly
        DISPATCH input event
    ELIF action == TYPE:
        FOCUS element
        IF clear: CLEAR existing value
        FOR each character IN text:
            DISPATCH keydown event
            DISPATCH keypress/input event
            DISPATCH keyup event
            WAIT delay between keystrokes

    # Step 4: Post-action
    WAIT for any triggered navigation to settle

Related Pages

Implemented By

• Implementation:MarketSquare_Robotframework_browser_Go_To_Click_Fill_Text