robotframework-vibium 0.2.0

Robot Framework library powered by Vibium for AI-native browser automation.

robotframework-vibium

Robot Framework library based on Vibium for AI-native browser automation.

Status: early development (PyPI 0.x, Alpha). The public keyword set may still evolve; pin versions in production suites if you need stability.

Vision

robotframework-vibium brings Vibium's modern browser interaction model into Robot Framework through clean, composable, and maintainable keywords.

Documentation

Use this README as a quick guide and examples, and Libdoc as the source of truth for the complete API.

See keyword documentation for more details.

Installation

pip install robotframework-vibium

Compatibility

Component	Supported Version
Python	>=3.9
Robot Framework	>=5.0
Vibium	>=26.3.18

Although Robot Framework supports older Python versions, this library follows Vibium's runtime requirements and therefore requires Python 3.9 or newer.

Quick Start

*** Settings ***
Library    Vibium

*** Test Cases ***
Basic Navigation
    Open Browser
    Go To    https://example.com
    ${text}=    Get Page Text
    Should Contain    ${text}    Example Domain
    Close Browser

Locator Syntax

Targets passed to Click Element, Fill Element and Find Element use a prefix-based contract that maps directly to Vibium's Page.find(...) API. The : separator is preferred over = deliberately, following SeleniumLibrary's guidance, because = collides with Robot Framework's named-argument syntax.

Single locator

Two forms:

1. CSS selector (default, no prefix) — forwarded as the positional selector argument of page.find. CSS is Vibium's default strategy.
2. Semantic strategy (strategy:value) — forwarded as the matching keyword argument. The prefix is split on the first : only, so values may contain =, [, ] or extra : characters (essential for XPath).

Supported strategies: xpath, role, text, label, placeholder, testid, alt, title, near.

*** Test Cases ***
Single Locator Examples
    Click Element    input[name='q']
    Click Element    role:button
    Click Element    text:Log in
    Click Element    xpath:(//*[@name='q'])[1]
    Click Element    xpath://input[@id='email' and @type='text']

Combining multiple strategies

Every keyword accepts one or more locator tokens as separate Robot Framework arguments. They are merged into a single page.find(...) call—the same idea as combining role plus accessible name in richer browser automation APIs—and matches the Vibium CLI pattern vibium find role button --name "Log in".

Rules:

• At most one CSS-selector positional (Vibium accepts only one).
• Each semantic axis may appear at most once; duplicates raise an error.

*** Test Cases ***
Combined Locators
    Click Element    role:button    text:Log in
    Click Element    role:textbox   label:E-mail
    Click Element    .nav           role:link       text:Home

Fill Element: value rules

Fill Element supports two modes:

1. Ergonomic — the last positional is the value.
2. Explicit — use value=... as a Robot Framework keyword argument.

To prevent silent foot-guns, the ergonomic mode raises an error when the last positional looks like a locator (starts with a known strategy: prefix). Use value=... to disambiguate.

*** Test Cases ***
Fill Examples
    # Ergonomic: value as last positional
    Fill Element    input#email                            [e-mail]
    Fill Element    role:textbox    label:E-mail           [e-mail]

    # Explicit: value= kwarg
    Fill Element    role:textbox                           value=[e-mail]
    Fill Element    input#password                         value=secret

    # Required when the value itself looks like a locator
    Fill Element    input#comment                          value=role:admin

    # Clear a field
    Fill Element    input#search                           value=${EMPTY}

The following is rejected with a clear error (ambiguous last positional):

Fill Element    role:textbox    label:E-mail        # ERROR: looks like 2 locators, value missing

Development

python3.9 -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest

End-to-end checks with real browser (from repository root):

robot --pythonpath src -d reports/acceptance tests/acceptance

Smoke-only run:

robot --pythonpath src -i smoke -d reports/acceptance tests/acceptance

See tests/acceptance/README.md for suite coverage and details.

Project Principles

• Stable and explicit public keyword API
• High-quality error messages for test users
• Clean separation between session management and keyword layers
• Fast feedback loop with unit + acceptance tests

License

Apache-2.0