Keyword Usage¶

This document outlines the available keywords for the Optics Framework, which can be used in the test_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

Swipe¶

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

Parameters:

Example:

Swipe,500,800,down,100,swipe_down

Swipe Until Element Appears¶

Swipes in a specified direction until an element appears.

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.

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.

Validate Element¶

Verifies the specified element is present on the screen.

Parameters:

Example:

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

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

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 Page Source¶

Captures the page source of the current screen.

Parameters:

Example:

Capture Page Source,get_source

Get Interactive Elements¶

Retrieves a list of interactive elements on the current screen.

Parameters:

Example:

Get Interactive Elements,buttons

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¶

Closes and terminates the current application.

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.

Parameters:

Example:

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

Example (with comparison):

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

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.