Keyword Usage¶

This document outlines the available keywords for the Optics Framework, which can be used in the modules.csv file to define test steps. Keywords are derived from the framework's Python API, with method names converted to a space-separated format (e.g., press_element becomes Press Element). Each keyword corresponds to a specific action, verification, or control flow operation. Below, each keyword includes detailed parameter explanations to guide their usage.

Keyword data sources¶

• Element-based keywords (Press Element, Assert Elements, Type Text, Validate Element, etc.) use element data from element files (CSV with columns such as element_name / element_id, or YAML with an elements key). Element names in test steps refer to these definitions.
• Invoke API uses API definition data from API YAML files (top-level api or apis). It does not use element files. You reference an API by the identifier collection.api_name.

Action Keywords¶

These keywords handle interactions with the application, such as clicking, swiping, and text input.

Press Element¶

Presses a specified element on the screen.

Parameters:

Example:

Press Element,${Subscriptions_text},2,10,20,0,0,0,100,100,click_event

Press By Percentage¶

Presses at percentage-based coordinates on the screen.

Parameters:

Example:

Press By Percentage,0.5,0.5,,press_center

Press By Coordinates¶

Presses at absolute coordinates on the screen.

Parameters:

Example:

Press By Coordinates,500,800,,tap_event

Detect And Press¶

Detects a specified element and presses it if found.

Parameters:

Example:

Detect And Press,login_button.png,30,detect_login

Select Dropdown Option¶

Opens a dropdown and selects one of its options, scrolling through the list if needed.

Presses the dropdown element to open it. If option is already visible, presses it directly. Otherwise, diffs the interactive elements captured before and after opening to find the dropdown's scrollable list container, then scrolls within that container until option appears or the list stops changing. Raises an error (E0201) if option is never found within timeout seconds, preventing a silent mis-selection. Falls back to a single-screen check (no scrolling) when page source, or a list-like container, isn't available.

Parameters:

Example:

Select Dropdown Option,${country_dropdown},India,30,country_selected

Swipe¶

Performs a swipe action in a specified direction from given coordinates.

Parameters:

Example:

Swipe,500,800,down,100,swipe_down

Swipe By Percentage¶

Performs a swipe action in a specified direction by percentage of the screen (0-100).

Parameters:

Example:

Swipe By Percentage,50,50,up,25,swipe_up

Swipe Until Element Appears¶

Swipes in a specified direction until an element appears. Raises an error if the element does not appear within the timeout.

Parameters:

Example:

Swipe Until Element Appears,next_button.png,down,30,find_next

Swipe From Element¶

Performs a swipe action starting from a specified element.

Parameters:

Example:

Swipe From Element,slider.png,right,50,0,0,100,100,swipe_slider

Scroll¶

Performs a scroll action in a specified direction.

Parameters:

Example:

Scroll,down,scroll_down

Scroll Until Element Appears¶

Scrolls in a specified direction until an element appears. Raises an error if the element does not appear within the timeout.

Parameters:

Example:

Scroll Until Element Appears,footer.png,down,30,find_footer

Scroll From Element¶

Performs a scroll action starting from a specified element.

Parameters:

Example:

Scroll From Element,scrollable_area.png,down,100,0,0,100,100,scroll_area

Enter Text¶

Enters text into a specified element.

Parameters:

Example:

Enter Text,username_field.png,myusername,0,0,100,100,enter_username

Enter Text Direct¶

Enters text directly using the keyboard without targeting a specific element.

Parameters:

Example:

Enter Text Direct,Hello World,type_text

Enter Text Using Keyboard¶

Enters text or presses a special key using the keyboard. Supports special keys like <enter>, <tab>, etc.

Parameters:

Example:

Enter Text Using Keyboard,<enter>,press_enter

Enter Number¶

Enters a specified number into an element.

Parameters:

Example:

Enter Number,phone_field.png,1234567890,0,0,100,100,enter_phone

Press Keycode¶

Presses a specified keycode (useful for Android keycodes like BACK, HOME, etc.).

Parameters:

Example:

Press Keycode,4,press_back

Clear Element Text¶

Clears text from a specified element.

Parameters:

Example:

Clear Element Text,text_field.png,0,0,100,100,clear_field

Get Text¶

Gets the text from a specified element. Currently supports XPath and Text-based elements with Appium.

Parameters:

Example:

Get Text,//android.widget.TextView[@resource-id="title"]

Note: This keyword returns text but does not store it in CSV format. Use with flow control keywords to store results.

Sleep¶

Sleeps for a specified duration.

Parameters:

Example:

Sleep,5

Execute Script¶

Executes JavaScript/script in the current context. Supports both plain script strings and JSON format with arguments.

Parameters:

Example:

Execute Script,{"script": "mobile:pressKey", "args": {"keycode": 3}},execute_back

Verification Keywords¶

These keywords handle verification and validation operations.

Assert Equality¶

Compares two values for equality. Both values are converted to strings and stripped of leading/trailing whitespace before comparison. Returns true if equal, false otherwise. Either value can be a ${variable} reference.

Usage note: Evaluate writes its result directly into session.elements, so ${var} from Evaluate can be passed straight into Assert Equality.

No expression evaluation: Assert Equality only resolves ${var} references to their stored string value, then compares the two resulting strings as-is — it does not evaluate anything as Python. Quote characters you type are compared literally, not stripped. So a stored value of 9.99 must be compared against the bare literal 9.99 (not '9.99').

Parameters:

Example (direct literal comparison):

Assert Equality,${price_text},9.99,price_verified

Example (chained after Evaluate):

Evaluate,${price},'9.99'
Assert Equality,${price},9.99

Example (chained after Get Text):

Get Text doesn't store its result automatically, so capture the returned text and compare it directly:

Get Text,//android.widget.TextView[@resource-id="price_label"]
Assert Equality,9.99,9.99

Here, the first 9.99 in Assert Equality is the text Get Text returned from the label. You paste in whatever value it gave back, not a fresh literal.

Validate Element¶

Verifies the specified element is present on the screen.

Parameters:

Example:

Validate Element,login_button.png,10,any,verify_login

Is Element¶

Checks if an element is in a given state: visible, invisible, enabled, or disabled. Raises an error if the element's actual state does not match the expected state.

• visible / invisible — asserts presence or absence of the element on screen within the timeout.
• enabled / disabled — locates the element and checks its interactive state via the accessibility tree. Coordinate-based results (e.g. from OCR) are not supported for enabled/disabled checks.

Parameters:

Example:

Is Element,login_button.png,visible,10,check_login_visible
Is Element,//android.widget.Button[@text="Submit"],enabled,5,check_submit_enabled
Is Element,loading_spinner.png,invisible,15,wait_for_load

Assert Presence¶

Asserts the presence of elements. Can check multiple elements with pipe separator (|).

Parameters:

Example:

Assert Presence,login_button.png|signup_button.png,30,any,check_buttons

Assert Visibility¶

Asserts that elements are actually rendered/visible on screen right now — distinct from Assert Presence, which reports found even for elements that exist in the page/DOM but are off-screen (e.g. not yet scrolled into view). Can check multiple elements with pipe separator (|).

Driver support: Appium (Android and iOS). Selenium and Playwright do not yet implement this keyword and raise an error if used — support is pending fixes to unrelated pre-existing bugs in those drivers.

Android note: elements scrolled out of view are omitted entirely from the page source by default on Android, so this keyword can't tell "off-screen" from "doesn't exist" for them unless allowInvisibleElements: true is set under appium:settings — see Appium configuration.

Parameters:

Example:

Assert Visibility,login_button.png|signup_button.png,30,any,check_buttons_visible

Validate Screen¶

Verifies the specified screen by checking element presence. Similar to Assert Presence but does not fail if elements are not found.

Parameters:

Example:

Validate Screen,home_screen.png|menu.png,30,any,verify_home

Capture Screenshot¶

Captures a screenshot of the current screen.

Parameters:

Example:

Capture Screenshot,screenshot_before_action

Capture Pagesource¶

Captures the page source of the current screen.

Parameters:

Example:

Capture Pagesource,get_source

Get Interactive Elements¶

Retrieves a list of interactive elements on the current screen.

Parameters:

Example:

Get Interactive Elements,buttons

Get Screen Elements¶

Captures a screenshot and retrieves interactive elements from the current screen in a single call. Returns a dict with a base64-encoded screenshot and a list of elements.

Parameters:

None.

Example:

Get Screen Elements

App Management Keywords¶

These keywords handle application lifecycle operations.

Launch App¶

Launches the specified application.

Parameters:

Example:

Launch App,com.example.app,MainActivity,launch_main

Start Appium Session¶

Starts an Appium session. This is typically called automatically during setup.

Parameters:

Example:

Start Appium Session,start_session

Launch Other App¶

Starts another application.

Parameters:

Example:

Launch Other App,com.example.otherapp,launch_other

Close And Terminate App¶

Tears down the active driver session and flushes all pending events. The exact behaviour depends on the configured driver (Appium, Selenium, Playwright, BLE) but in all cases the driver reference is released after this call.

Parameters:

None

Example:

Close And Terminate App

Force Terminate App¶

Forcefully terminates the specified application.

Parameters:

Example:

Force Terminate App,com.example.app,terminate_app

Get App Version¶

Gets the version of the application.

Parameters:

None

Example:

Get App Version

Get Driver Session Id¶

Returns the current driver session ID, if available.

Parameters:

None

Example:

Get Driver Session Id

Flow Control Keywords¶

These keywords handle control flow operations like loops, conditions, and data manipulation. Module execution is performed by the runner when it runs test-case steps; the Optics API does not expose user-facing "Initialise Setup" or "Execute Module" keywords.

Run Loop¶

Runs a loop over a target module, either by count or with variables.

Parameters:

Example (by count):

Run Loop,test_module,5

Example (with variables):

Run Loop,test_module,${username},user1|user2|user3,${password},pass1|pass2|pass3

Condition¶

Evaluates conditions and executes corresponding targets. Supports both module-based and expression-based conditions.

Parameters:

Example (module condition):

Condition,login_success,show_dashboard,login_failed,show_error

Example (expression condition):

Condition,${count} > 10,handle_large_count,handle_small_count

Example (with else):

Condition,${status} == "active",activate,deactivate,default_action

Read Data¶

Reads tabular data from a CSV file, JSON file, environment variable, or a 2D list, applies optional filtering and column selection, and stores the result in the session's elements.

For the programmatic API and full parameter details, see Flow Control in the API reference.

Parameters:

Example (CSV file):

Read Data,${users},users.csv,select=username,email

Example (with filter):

Read Data,${active_users},users.csv,status='active';select=username,email

Example (environment variable):

Read Data,${config},ENV:APP_CONFIG

Example (query with variable):

Read Data,${filtered},users.csv,role=='${expected_role}';select=id,name

Note: Inline list data (e.g. a 2D list) is supported only when calling the Python API; see Library Usage for examples.

Evaluate¶

Evaluates an expression and stores the result in session.elements under the given variable name.

Parameters:

How param2 is evaluated:

• Every ${var} in param2 is first replaced, as plain text, with the variable's stored string value — before anything is evaluated as Python.
• The result of that substitution is then run through a restricted eval(). Only arithmetic (+ - * / % **), comparisons (> < >= <= == !=), boolean logic (and or not), a ternary ... if ... else ..., and literal list/tuple values are allowed. Anything else (function calls, attribute access, imports, f-strings, etc.) is rejected with Code.E0403 Unsafe expression detected.
• Because the substitution is textual and unquoted, a ${var} that holds text must be wrapped in quotes inside the expression (e.g. '${name}'), otherwise the substituted word is treated as a bare Python name and raises a NameError. A ${var} that holds a number does not need quotes.
• The final result is stored via str(result), so even numbers and booleans end up as strings in session.elements (e.g. True → "True").
• param1 must be in ${name} form; if it isn't, a warning is logged and the raw string is used as the variable name as-is.

Example (numeric arithmetic):

Evaluate,${a},5
Evaluate,${b},3
Evaluate,${sum},${a} + ${b}

${sum} → 8

Example (comparison):

Evaluate,${count},15
Evaluate,${is_valid},${count} > 10

${is_valid} → True

Example (string literal):

Wrap plain text in quotes so it's evaluated as a Python string, not as bare identifiers:

Evaluate,${greeting},'hello world'

${greeting} → hello world

Example (concatenating a stored text variable):

${name} holds text, so it must be quoted inside the expression once substituted:

Evaluate,${name},'Alice'
Evaluate,${message},'Hello, ' + '${name}'

${message} → Hello, Alice

Example (ternary if/else):

Evaluate,${score},72
Evaluate,${result},'Pass' if ${score} >= 50 else 'Fail'

${result} → Pass

Example (list literal):

Evaluate,${numbers},[1, 2, 3, 4]

${numbers} → [1, 2, 3, 4]

Date Evaluate¶

Evaluates a date expression based on an input date and stores the result in session.elements.

Parameters:

Example:

Date Evaluate,${tomorrow},04/25/2025,+1 day

Example (with custom format):

Date Evaluate,${next_week},2025-04-25,+7 days,%Y-%m-%d

Add API¶

Adds or updates API definitions in the current session by loading from a file path or a dictionary. Use this when not using the runner's auto-discovery (e.g. when driving the framework programmatically). The supplied data replaces the session's API data.

Parameters:

Example (file path):

Add API,path/to/api.yaml

Example (programmatic): Pass a dict with an api key holding the collection/endpoint definitions. Relative paths are resolved against the project path when a string is given.

Invoke API¶

Invokes an API call based on a definition from the session's API data.

Parameters:

Example:

Invoke API,users.get_user

Data source: API definition YAML

Invoke API does not use element files. It uses API definition YAML files only. The format is different from element CSV/YAML: definitions live under a top-level api (or apis) key, with collections → each collection has base_url, global_headers, and apis → each API has endpoint, request (e.g. method, headers, body), and optionally expected_result, extract, and so on.

How API definitions reach the session:

• CLI/runner: YAML files under the project that contain a top-level api or apis key are auto-discovered and loaded as API data.
• Programmatic: The Add API keyword can load from a file path or a dict to set or replace session API data.