Robot Framework Usage Guide¶

This guide demonstrates how to use the Optics Framework with Robot Framework for test automation.

Installation¶

Install the Optics Framework and Robot Framework:

pip install optics-framework robotframework

Quick Start¶

Basic Example¶

*** Settings ***
Library    optics_framework.optics.Optics

*** Test Cases ***
Example Test
    Setup    driver_sources=[{"appium": {"enabled": True, "url": "http://localhost:4723"}}]    elements_sources=[{"appium_find_element": {"enabled": True}}]
    Launch App    com.example.app
    Press Element    submit_button
    Enter Text    username_field    testuser
    Validate Element    welcome_message
    Quit

Library Import¶

Basic Import¶

*** Settings ***
Library    optics_framework.optics.Optics

Import with Alias¶

*** Settings ***
Library    optics_framework.optics.Optics    WITH NAME    Optics

Configuration¶

Configuration from Dictionary¶

*** Settings ***
Library    optics_framework.optics.Optics

*** Variables ***
${CONFIG}    {"driver_sources": [{"appium": {"enabled": true, "url": "http://localhost:4723"}}], "elements_sources": [{"appium_find_element": {"enabled": true}}]}

*** Test Cases ***
Test With Config
    Setup    config=${CONFIG}
    Launch App    com.example.app
    Quit

Configuration from YAML File¶

*** Settings ***
Library    optics_framework.optics.Optics

*** Test Cases ***
Test With YAML Config
    Setup From File    config.yaml
    Launch App    com.example.app
    Quit

config.yaml:

driver_sources:
  - appium:
      enabled: true
      url: "http://localhost:4723"
      capabilities:
        platformName: "Android"
        deviceName: "emulator-5554"

elements_sources:
  - appium_find_element:
      enabled: true

text_detection:
  - easyocr:
      enabled: true

image_detection:
  - templatematch:
      enabled: true

project_path: "/path/to/project"

Configuration with Parameters¶

*** Settings ***
Library    optics_framework.optics.Optics

*** Test Cases ***
Test With Parameters
    Setup    driver_sources=[{"appium": {"enabled": True, "url": "http://localhost:4723"}}]    elements_sources=[{"appium_find_element": {"enabled": True}}]    text_detection=[{"easyocr": {"enabled": True}}]
    Launch App    com.example.app
    Quit

App Management¶

Launching Apps¶

*** Test Cases ***
Launch App Test
    Setup    config=config.yaml
    Launch App    com.example.app
    ${version}=    Get App Version
    Log    App version: ${version}
    ${session_id}=    Get Driver Session Id
    Log    Session ID: ${session_id}
    Quit

App Lifecycle¶

*** Test Cases ***
App Lifecycle Test
    Setup    config=config.yaml
    Launch App    com.example.app
    Press Element    button
    Close And Terminate App
    Quit

Element Interactions¶

Pressing Elements¶

*** Test Cases ***
Press Element Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Press element by ID
    Press Element    submit_button

    # Press with fallback
    Press Element    button1    button2    //button[@id='submit']

    # Press by coordinates
    Press By Coordinates    100    200

    # Press by percentage
    Press By Percentage    50    50

    # Press element with index
    Press Element With Index    button    0

    Quit

Text Input¶

*** Test Cases ***
Text Input Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Enter text
    Enter Text    username_field    testuser
    Enter Text Direct    input_field    text
    Enter Text Using Keyboard    field    text

    # Enter number
    Enter Number    number_field    123

    # Clear text
    Clear Element Text    input_field

    Quit

Gestures¶

*** Test Cases ***
Gesture Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Swipe
    Swipe    100    200    300    400
    Swipe Until Element Appears    target_element    direction=up
    Swipe From Element    source_element    300    400

    # Scroll
    Scroll    100    200    300    400
    Scroll Until Element Appears    target_element    direction=down
    Scroll From Element    source_element    300    400

    Quit

Other Actions¶

*** Test Cases ***
Other Actions Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Press keycode
    Press Keycode    4

    # Get text
    ${text}=    Get Text    element_id
    Log    Element text: ${text}

    # Sleep
    Sleep    2

    # Execute script
    ${result}=    Execute Script    mobile: shell    command=echo hello
    Log    Script result: ${result}

    Quit

Verification¶

Element Validation¶

*** Test Cases ***
Validation Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Validate single element
    Validate Element    welcome_message

    # Assert presence
    Assert Presence    element1    element2    rule=all
    Assert Presence    element1    element2    rule=any

    # Validate screen
    Validate Screen    header    content    footer

    Quit

Screenshots and Page Source¶

*** Test Cases ***
Capture Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Capture screenshot
    ${screenshot}=    Capture Screenshot
    Log    Screenshot: ${screenshot}

    # Capture page source
    ${page_source}=    Capture Page Source
    Log    Page source: ${page_source}

    # Get interactive elements
    ${elements}=    Get Interactive Elements
    Log    Elements: ${elements}

    Quit

Flow Control¶

Conditional Execution¶

*** Test Cases ***
Conditional Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Condition with variable
    Set Test Variable    ${status}    ready
    Condition    ${status} == 'ready'    proceed_keyword

    # Condition with expression
    Set Test Variable    ${count}    15
    Condition    ${count} > 10    handle_large_count

    Quit

Data Operations¶

*** Test Cases ***
Data Operations Test
    Setup    config=config.yaml

    # Read data from CSV
    ${data}=    Read Data    data.csv
    Log    Data: ${data}

    # Invoke API
    ${response}=    Invoke API    GET    https://api.example.com/data
    Log    API response: ${response}

    # Read data from list
    ${data}=    Read Data    item1    item2    item3
    Log    Data: ${data}

    Quit

Loops¶

*** Test Cases ***
Loop Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Run loop
    Run Loop    5    keyword_name

    # Run loop with condition
    Set Test Variable    ${status}    active
    Run Loop    10    process_item    condition=${status} == 'active'

    Quit

Evaluation¶

*** Test Cases ***
Evaluation Test
    Setup    config=config.yaml

    # Evaluate expression
    Set Test Variable    ${var1}    10
    Set Test Variable    ${var2}    20
    ${result}=    Evaluate    ${var1} + ${var2}
    Log    Result: ${result}

    # Date evaluation
    ${future_date}=    Date Evaluate    today + 1 day
    ${past_date}=    Date Evaluate    today - 7 days
    Log    Future date: ${future_date}
    Log    Past date: ${past_date}

    Quit

Element Management¶

Adding Elements¶

*** Test Cases ***
Element Management Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Add element
    Add Element    submit_button    //button[@id='submit']

    # Get element value
    ${element_value}=    Get Element Value    submit_button
    Log    Element value: ${element_value}

    # Use element
    Press Element    submit_button

    # Use element variable
    Press Element    ${submit_button}

    Quit

Element Variables¶

*** Test Cases ***
Element Variables Test
    Setup    config=config.yaml
    Launch App    com.example.app

    # Add multiple elements
    Add Element    username    //input[@name='user']
    Add Element    password    //input[@name='pass']
    Add Element    submit    //button[@type='submit']

    # Use in sequence
    Enter Text    ${username}    testuser
    Enter Text    ${password}    testpass
    Press Element    ${submit}

    Quit

Test Organization¶

Test Suite Structure¶

*** Settings ***
Documentation    Example test suite using Optics Framework
Library    optics_framework.optics.Optics
Resource    keywords.robot

*** Variables ***
${CONFIG_FILE}    config.yaml

*** Test Cases ***
Test Case 1
    [Documentation]    First test case
    Setup    config=${CONFIG_FILE}
    Launch App    com.example.app
    Press Element    button1
    Validate Element    result1
    Quit

Test Case 2
    [Documentation]    Second test case
    Setup    config=${CONFIG_FILE}
    Launch App    com.example.app
    Press Element    button2
    Validate Element    result2
    Quit

Keywords Resource File¶

keywords.robot:

*** Settings ***
Library    optics_framework.optics.Optics

*** Keywords ***
Login
    [Arguments]    ${username}    ${password}
    Enter Text    username_field    ${username}
    Enter Text    password_field    ${password}
    Press Element    login_button
    Validate Element    welcome_message

Logout
    Press Element    logout_button
    Validate Element    login_screen

Using Resource Keywords¶

*** Settings ***
Library    optics_framework.optics.Optics
Resource    keywords.robot

*** Test Cases ***
Login Test
    Setup    config=config.yaml
    Launch App    com.example.app
    Login    testuser    testpass
    Logout
    Quit

Complete Example¶

*** Settings ***
Documentation    Complete example test suite
Library    optics_framework.optics.Optics

*** Variables ***
${CONFIG_FILE}    config.yaml
${APP_PACKAGE}    com.example.app

*** Test Cases ***
Login Flow Test
    [Documentation]    Test complete login flow
    [Tags]    smoke    login

    # Setup
    Setup    config=${CONFIG_FILE}

    # Launch app
    Launch App    ${APP_PACKAGE}

    # Add elements
    Add Element    username    //input[@id='username']
    Add Element    password    //input[@id='password']
    Add Element    login_button    //button[@id='login']

    # Perform login
    Enter Text    ${username}    testuser
    Enter Text    ${password}    testpass
    Press Element    ${login_button}

    # Verify login
    Validate Element    welcome_message

    # Capture screenshot
    ${screenshot}=    Capture Screenshot
    Log    Screenshot saved: ${screenshot}

    # Cleanup
    Quit

Element Interaction Test
    [Documentation]    Test various element interactions
    [Tags]    interaction

    Setup    config=${CONFIG_FILE}
    Launch App    ${APP_PACKAGE}

    # Press elements
    Press Element    button1
    Press By Coordinates    100    200
    Press By Percentage    50    50

    # Text input
    Enter Text    input_field    test text
    Enter Number    number_field    123

    # Gestures
    Swipe    100    200    300    400
    Scroll    100    200    300    400

    # Verification
    Validate Element    result_element
    Assert Presence    element1    element2    rule=all

    Quit

Best Practices¶

1. Configuration Management¶

Store configuration in YAML files
Use variables for reusable values
Keep configuration separate from test logic

2. Test Organization¶

Use resource files for reusable keywords
Organize tests into logical test suites
Use tags for test categorization

3. Element Management¶

Store elements using Add Element
Use descriptive element names
Leverage element variables

4. Error Handling¶

Use Robot Framework's built-in error handling
Add proper documentation to test cases
Use tags to mark flaky tests

5. Test Data¶

Use variables for test data
Store data in external files when needed
Use data-driven testing for multiple scenarios

Running Tests¶

Basic Execution¶

robot tests/login_test.robot

With Tags¶

robot --include smoke tests/
robot --exclude flaky tests/

With Variables¶

robot -v CONFIG_FILE:config.yaml -v APP_PACKAGE:com.example.app tests/

Generate Reports¶

robot --outputdir results tests/

Library Usage - Python library usage guide
Library Layer Architecture - Detailed architecture documentation
Keyword Usage - Complete keyword reference
Configuration - Configuration guide
REST API Usage - REST API endpoint reference
API Reference - Python API documentation

Robot Framework Usage Guide¶

Installation¶

Quick Start¶

Basic Example¶

Library Import¶

Basic Import¶

Import with Alias¶

Configuration¶

Configuration from Dictionary¶

Configuration from YAML File¶

Configuration with Parameters¶

App Management¶

Launching Apps¶

App Lifecycle¶

Element Interactions¶

Pressing Elements¶

Text Input¶

Gestures¶

Other Actions¶

Verification¶

Element Validation¶

Screenshots and Page Source¶

Flow Control¶

Conditional Execution¶

Data Operations¶

Loops¶

Evaluation¶

Element Management¶

Adding Elements¶

Element Variables¶

Test Organization¶

Test Suite Structure¶

Keywords Resource File¶

Using Resource Keywords¶

Complete Example¶

Best Practices¶

1. Configuration Management¶

2. Test Organization¶

3. Element Management¶

4. Error Handling¶

5. Test Data¶

Running Tests¶

Basic Execution¶

With Tags¶

With Variables¶

Generate Reports¶

Related Documentation¶