Action Keywords¶
The ActionKeyword class provides methods for interacting with elements, including pressing, swiping, typing, and other user actions.
optics_framework.api.action_keyword.ActionKeyword ¶
High-Level API for Action Keywords
This class provides functionality for managing action keywords related to applications, including pressing elements, scrolling, swiping, and text input.
clear_element_text(element, aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100', event_name=None, index='0') ¶
Clear text from a specified element.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The target element (Image template, OCR template, or XPath). | required |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
event_name | Optional[str] | The event triggering the action. | None |
index | str | Index of the element if multiple matches are found. | '0' |
detect_and_press(element, timeout='30', event_name=None) ¶
Detect and press a specified element.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The element to be detected and pressed (Image template, OCR template, or XPath). | required |
timeout | str | Timeout for the detection operation. | '30' |
event_name | Optional[str] | The event triggering the press. | None |
enter_number(element, number, aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100', event_name=None, index='0') ¶
Enter a specified number into an element.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The target element (Image template, OCR template, or XPath). | required |
number | str | The number to be entered. | required |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
event_name | Optional[str] | The event triggering the input. | None |
index | str | Index of the element if multiple matches are found. | '0' |
enter_text(element, text, aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100', event_name=None, index='0') ¶
Enter text into a specified element.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The target element (Image template, OCR template, or XPath). | required |
text | str | The text to be entered. | required |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
event_name | Optional[str] | The event triggering the input. | None |
index | str | Index of the element if multiple matches are found. | '0' |
enter_text_direct(text, event_name=None) ¶
Enter text using the keyboard.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text | str | The text to be entered. | required |
event_name | Optional[str] | The event triggering the input. | None |
enter_text_using_keyboard(text_input, event_name=None) ¶
Enter text or press a special key using the keyboard.
If the input is a string that includes angle brackets (e.g., '
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
text_input | str | The text or special key identifier to send. | required |
event_name | Optional[str] | Optional event label for logging. | None |
execute_script(script_or_json, event_name=None) ¶
Execute JavaScript/script in the current context.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
script_or_json | str | The JavaScript code/script command, or a JSON string containing {"script": "...", "args": {...}} or {"script": "..."}. Examples: - "mobile:pressKey" (plain script) - '{"script": "mobile:pressKey", "args": {"keycode": 3}}' (JSON with args) - '{"script": "mobile:clear"}' (JSON without args) | required |
event_name | Optional[str] | The event triggering the script execution, if any. | None |
Returns:
| Type | Description |
|---|---|
Any | The result of the script execution. |
get_text(element, index='0', aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100') ¶
Get the text from a specified element.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The target element (Image template, OCR template, or XPath). | required |
index | str | Index of the element if multiple matches are found. | '0' |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
Returns:
| Type | Description |
|---|---|
Optional[str] | The text from the element or None if not supported. |
press_by_coordinates(coor_x, coor_y, repeat='1', event_name=None) ¶
Press an element by absolute coordinates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
coor_x | str | X coordinate of the press. | required |
coor_y | str | Y coordinate of the press. | required |
repeat | str | Number of times to repeat the press. | '1' |
event_name | Optional[str] | The event triggering the press. | None |
press_by_percentage(percent_x, percent_y, repeat='1', event_name=None) ¶
Press an element by percentage coordinates.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
percent_x | str | X percentage of the press (as string, will be converted to float). | required |
percent_y | str | Y percentage of the press (as string, will be converted to float). | required |
repeat | str | Number of times to repeat the press. | '1' |
event_name | Optional[str] | The event triggering the press. | None |
press_checkbox(element, aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100', event_name=None, index='0') ¶
Press a specified checkbox element.
.. deprecated:: Deprecated alias of :meth:press_element — use Press Element directly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The checkbox element (Image template, OCR template, or XPath). | required |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
event_name | Optional[str] | The event triggering the press. | None |
index | str | Index of the element if multiple matches are found. | '0' |
press_element(element, repeat='1', offset_x='0', offset_y='0', index='0', aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100', event_name=None) ¶
Press a specified element.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The element to be pressed (text, xpath or image). | required |
repeat | str | Number of times to repeat the press. | '1' |
offset_x | str | X offset of the press. | '0' |
offset_y | str | Y offset of the press. | '0' |
index | str | Index of the element if multiple matches are found. | '0' |
event_name | Optional[str] | The event triggering the press. | None |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
press_keycode(keycode, event_name=None) ¶
Press a specified keycode.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
keycode | str | The keycode to be pressed. | required |
event_name | Optional[str] | The event triggering the press. | None |
press_radio_button(element, aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100', event_name=None, index='0') ¶
Press a specified radio button.
.. deprecated:: Deprecated alias of :meth:press_element — use Press Element directly.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The radio button element (Image template, OCR template, or XPath). | required |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
event_name | Optional[str] | The event triggering the press. | None |
index | str | Index of the element if multiple matches are found. | '0' |
scroll(direction, event_name=None) ¶
Perform a scroll action in a specified direction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
direction | str | The scroll direction (up, down, left, right). | required |
event_name | Optional[str] | The event triggering the scroll. | None |
scroll_from_element(element, direction, scroll_length, aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100', event_name=None, index='0') ¶
Perform a scroll action starting from a specified element.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The element to scroll from (Image template, OCR template, or XPath). | required |
direction | str | The scroll direction (up, down, left, right). | required |
scroll_length | str | The length of the scroll. | required |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
event_name | Optional[str] | The event triggering the scroll. | None |
index | str | Index of the element if multiple matches are found. | '0' |
scroll_until_element_appears(element, direction, timeout, event_name=None) ¶
Scroll in a specified direction until an element appears.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The target element (Image template, OCR template, or XPath). | required |
direction | str | The scroll direction (up, down, left, right). | required |
timeout | str | Timeout for the scroll operation. | required |
event_name | Optional[str] | The event triggering the scroll. | None |
select_dropdown_option(element, option, timeout='30', event_name=None) ¶
Open a dropdown and select one of its options, scrolling through the list if needed.
Opens the dropdown by pressing element. If option isn't visible right away, diffs the interactive elements captured before and after opening to find the dropdown's list container, then scrolls within that container (never past the page behind it) until option appears or the list stops changing. Raises OpticsError (E0201``) ifoptionis never found withintimeout` seconds.
Falls back to a single-screen check (no scrolling) when page source, or a list-like container, isn't available.
Assumption: opened dropdown list is opened in such a way that the topmost option is visible on the screen
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The dropdown element (Image template, OCR template, or XPath). | required |
option | str | The option to select (visible label, OCR/Image template, or XPath). | required |
timeout | str | Seconds to keep scrolling through the dropdown list before failing. | '30' |
event_name | Optional[str] | The event triggering the selection. | None |
sleep(duration) ¶
Sleep for a specified duration.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
duration | str | The duration of the sleep in seconds. | required |
swipe(coor_x, coor_y, direction='right', swipe_length='50', event_name=None) ¶
Perform a swipe action in a specified direction.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
coor_x | str | X coordinate of the swipe. | required |
coor_y | str | Y coordinate of the swipe. | required |
direction | str | The swipe direction (up, down, left, right). | 'right' |
swipe_length | str | The length of the swipe. | '50' |
event_name | Optional[str] | The event triggering the swipe. | None |
swipe_by_percentage(percent_x, percent_y, direction='right', swipe_length='50', event_name=None) ¶
Perform a swipe action in a specified direction by percentage.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
percent_x | str | X percentage of the swipe. | required |
percent_y | str | Y percentage of the swipe. | required |
direction | str | The swipe direction (up, down, left, right). | 'right' |
swipe_length | str | The length of the swipe. | '50' |
event_name | Optional[str] | The event triggering the swipe. | None |
swipe_from_element(element, direction, swipe_length, aoi_x='0', aoi_y='0', aoi_width='100', aoi_height='100', event_name=None, index='0') ¶
Perform a swipe action starting from a specified element.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The element to swipe from (Image template, OCR template, or XPath). | required |
direction | str | The swipe direction (up, down, left, right). | required |
swipe_length | str | The length of the swipe. | required |
aoi_x | str | X percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_y | str | Y percentage of Area of Interest top-left corner (0-100). Default: 0. | '0' |
aoi_width | str | Width percentage of Area of Interest (0-100). Default: 100. | '100' |
aoi_height | str | Height percentage of Area of Interest (0-100). Default: 100. | '100' |
event_name | Optional[str] | The event triggering the swipe. | None |
index | str | Index of the element if multiple matches are found. | '0' |
swipe_seekbar_to_right_android(element, event_name=None) ¶
Swipe a seekbar to the right.
.. deprecated:: Deprecated; prefer :meth:swipe_from_element / :meth:swipe.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The seekbar element (Image template, OCR template, or XPath). | required |
event_name | Optional[str] | The event triggering the swipe. | None |
swipe_until_element_appears(element, direction, timeout, event_name=None) ¶
Swipe in a specified direction until an element appears.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
element | str | The target element (Image template, OCR template, or XPath). | required |
direction | str | The swipe direction (up, down, left, right). | required |
timeout | str | Timeout until element search is performed. | required |
event_name | Optional[str] | The event triggering the swipe. | None |