Optics

Compares two values for equality. Both values are resolved from session elements if they are ``${variable}`` references before comparison. :param output: The actual value or ``${variable}`` reference. :param expression: The expected value or ``${variable}`` reference. :param event_name: The name of the event associated with the comparison, if any. :return: True if equal, False otherwise.

Asserts the presence of elements -- anywhere in the page/DOM, visible or not. :param elements: Comma-separated string of elements to check (Image templates, OCR templates, or XPaths). :param timeout_str: The time to wait for the elements in seconds. :param rule: The rule for verification ("any" or "all"). :param event_name: The name of the event associated with the assertion, if any. :param fail: If True, raise on failure; if False, return False instead. A suite writes this as text, and ``False`` is read case-insensitively. :return: True if the rule is satisfied, False otherwise.

Asserts that elements are actually rendered/visible on screen right now -- distinct from :meth:`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). :param elements: Comma-separated string of elements to check (Image templates, OCR templates, or XPaths). :param timeout_str: The time to wait for the elements to become visible, in seconds. :param rule: The rule for verification ("any" or "all"). :param event_name: The name of the event associated with the assertion, if any. :param fail: If True, raise on failure; if False, return False instead. A suite writes this as text, and ``False`` is read case-insensitively. :return: True if the rule is satisfied, False otherwise.

Clear text from a specified element. :param element: The target element (Image template, OCR template, or XPath). :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100. :param event_name: The event triggering the action. :param index: Index of the element if multiple matches are found.

Tears down the active driver session and flushes all pending events. Behaviour depends on the configured driver: WebDriver-based drivers (Appium, Selenium) call quit(); Playwright closes the page, context, and browser; BLE closes the serial port. All variants flush pending EventSDK events and release the driver reference.

Press an element if it appears within ``timeout``; otherwise do nothing. When the element never appears the press is skipped and the keyword still succeeds (it does not raise), so use it for optional taps such as dismissing a popup that may not show. Use ``press_element`` when the target must be present. :param element: The element to be detected and pressed (Image template, OCR template, or XPath). :param timeout: Seconds to wait for the element to appear. :param event_name: The event triggering the press.

Enter a specified number into an element. :param element: The target element (Image template, OCR template, or XPath). :param number: The number to be entered. :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100. :param event_name: The event triggering the input. :param index: Index of the element if multiple matches are found.

Enter text into a specified element. :param element: The target element (Image template, OCR template, or XPath). :param text: The text to be entered. :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100. :param event_name: The event triggering the input. :param index: Index of the element if multiple matches are found.

Enter text using the keyboard. :param text: The text to be entered. :param event_name: The event triggering the input.

Enter text or press a special key using the keyboard. If the input is a string that includes angle brackets (e.g., '<enter>'), the text between the brackets will be interpreted as a special key name and mapped accordingly. :param text_input: The text or special key identifier to send. :param event_name: Optional event label for logging.

Execute JavaScript/script in the current context. :param script_or_json: 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) :param event_name: The event triggering the script execution, if any. :return: The result of the script execution. :rtype: Any

Forcefully terminates the specified application. :param app_name: The name of the application to terminate. :param event_name: The event triggering the forced termination, if any.

Gets the version of the application. :param app_package: The app package/bundle ID to check, or the current app if None. :return: The version of the application, or None if not available.

Return the current driver session id, if available.

Retrieves a list of interactive elements on the current screen. XPath and text fields are converted to one-line, CSV-friendly form (newlines as \n, tabs as \t, etc.) so output can be pasted into elements.csv or similar. On Appium sources, element bounds are returned in the screenshot's pixel space. :param filter_config: Optional list of filter types (e.g., ["buttons", "inputs"]). :param compact: When True, return only actionable elements (labels folded in, with an ``act`` list) plus standalone visible text (``act: []``), as ``{i, label, cls, bounds:[x1,y1,x2,y2], act, rid?, loc?}`` (``loc``: a unique web locator). Implemented by the Appium and Playwright page sources; sources without it return their full list. :return: A list of interactive elements.

Get the text from a specified element. :param element: The target element (Image template, OCR template, or XPath). :param index: Index of the element if multiple matches are found. :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100. :return: The text from the element or None if not supported.

Go back one screen: browser history on the web, the back button on a phone.

Sets up the environment for the driver module. This method should be called before performing any application management operations. Not exposed on the Optics SDK because it currently performs no operation and doesn't delegate to the driver's own initialise_setup (e.g. AppiumDriver.initialise_setup).

Checks if the specified element is in a given state (e.g., Enabled/Disabled/Visible/Invisible). :param element: The element to be checked (Image template, OCR template, or XPath). :param element_state: The state to verify (visible, invisible, enabled, disabled). :param timeout: The time to wait for the element in seconds. :param event_name: The name of the event associated with the check, if any.

Launches the specified application. :param app_identifier: The app identifier (package name for Android, bundle ID for iOS). :param app_activity: The app activity to launch (Android only). :param event_name: The event triggering the app launch, if any.

Starts another application. :param app_name: The package name of the application. :param event_name: The event triggering the app start, if any.

Press a specified checkbox element. .. deprecated:: Deprecated alias of :meth:`press_element` — use ``Press Element`` directly. :param element: The checkbox element (Image template, OCR template, or XPath). :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100. :param event_name: The event triggering the press. :param index: Index of the element if multiple matches are found.

Press a specified element. :param element: The element to be pressed (text, xpath or image). :param repeat: Number of times to repeat the press. :param offset_x: X offset of the press. :param offset_y: Y offset of the press. :param index: Index of the element if multiple matches are found. :param event_name: The event triggering the press. :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100.

Press a device key by keycode, for system/hardware keys with no on-screen element. On Android the keycode is the numeric KeyEvent code (3 = HOME, 4 = BACK, 66 = ENTER, 187 = RECENTS); TV platform profiles map it to their remote-control key instead. :param keycode: The keycode to be pressed. :param event_name: The event triggering the press.

Press a specified radio button. .. deprecated:: Deprecated alias of :meth:`press_element` — use ``Press Element`` directly. :param element: The radio button element (Image template, OCR template, or XPath). :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100. :param event_name: The event triggering the press. :param index: Index of the element if multiple matches are found.

Capture the current screen and return it as a rendered PNG image. Prefer this over the `optics://session/{session_id}/screenshot` resource when you want the screen rendered inline (the resource returns raw bytes).

Scroll the current view one step in a direction. ``direction`` names the way you move through the content: "down" reveals content further down. Every driver supports up/down; left/right work only on Selenium (Appium logs and ignores them, Playwright treats anything but "down" as up). The keyword succeeds whether or not the view actually moved. :param direction: up or down (left/right on Selenium only). :param event_name: The event triggering the scroll.

Perform a scroll action starting from a specified element. :param element: The element to scroll from (Image template, OCR template, or XPath). :param direction: The scroll direction (up, down, left, right). :param scroll_length: The length of the scroll. :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100. :param event_name: The event triggering the scroll. :param index: Index of the element if multiple matches are found.

Scroll in a specified direction until an element appears. :param element: The target element (Image template, OCR template, or XPath). :param direction: The scroll direction (up, down, left, right). :param timeout: Timeout for the scroll operation. :param event_name: The event triggering the scroll.

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``) if `option` is never found within `timeout` 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 :param element: The dropdown element (Image template, OCR template, or XPath). :param option: The option to select (visible label, OCR/Image template, or XPath). :param timeout: Seconds to keep scrolling through the dropdown list before failing. :param event_name: The event triggering the selection.

Sleep for a specified duration. :param duration: The duration of the sleep in seconds.

Starts an Appium session. :param event_name: The event triggering the session start, if any.

Start a new optics session and launch the target app. Returns {"session_id", "driver_id"}. Pass the session_id to every keyword tool and state resource. The app is auto-launched on start. Sessions are NOT shared with `optics serve`/`optics live` (separate process); start one here before using any keyword tool. ai_self_heal / llm_provider / llm_model: per-session overrides for AI self-heal. Each falls back to the matching service-level env var the operator set at start-up (OPTICS_AI_SELF_HEAL / OPTICS_LLM_PROVIDER / OPTICS_LLM_MODEL) when left unset, so an already-configured server needs none of them. Because the process is multi-tenant, pass them to opt in/out or pick your own model for just this session instead of being locked to the operator's choice. Note that ai_self_heal=True with no provider configured anywhere still degrades to inert (no LLM to drive it); LLM credentials always come from the provider's own env vars (e.g. GOOGLE_API_KEY), never this tool. strict_element_match: reject fuzzy/partial text and xpath matches on locate (default False, i.e. fuzzy-tolerant). Set True when a near-miss locator string pressing the wrong element is worse than the keyword failing outright.

Swipe from a point in a specified direction. ``direction`` is the way the finger moves: "up" drags bottom to top, which reveals content further down. The keyword succeeds whether or not anything moved. :param coor_x: X pixel coordinate where the swipe starts. :param coor_y: Y pixel coordinate where the swipe starts. :param direction: The finger direction (up, down, left, right). :param swipe_length: Swipe distance in pixels. :param event_name: The event triggering the swipe.

Swipe from a screen position, given in percentages, in a specified direction. ``direction`` is the way the finger moves: "up" drags bottom to top, which reveals content further down. The keyword succeeds whether or not anything moved. :param percent_x: Start X as a percentage of screen width (0-100). :param percent_y: Start Y as a percentage of screen height (0-100). :param direction: The finger direction (up, down, left, right). :param swipe_length: Swipe distance as a percentage of screen height (up/down) or width (left/right). :param event_name: The event triggering the swipe.

Perform a swipe action starting from a specified element. :param element: The element to swipe from (Image template, OCR template, or XPath). :param direction: The swipe direction (up, down, left, right). :param swipe_length: The length of the swipe. :param aoi_x: X percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_y: Y percentage of Area of Interest top-left corner (0-100). Default: 0. :param aoi_width: Width percentage of Area of Interest (0-100). Default: 100. :param aoi_height: Height percentage of Area of Interest (0-100). Default: 100. :param event_name: The event triggering the swipe. :param index: Index of the element if multiple matches are found.

Swipe a seekbar to the right. .. deprecated:: Deprecated; prefer :meth:`swipe_from_element` / :meth:`swipe`. :param element: The seekbar element (Image template, OCR template, or XPath). :param event_name: The event triggering the swipe.

Swipe in a specified direction until an element appears. :param element: The target element (Image template, OCR template, or XPath). :param direction: The swipe direction (up, down, left, right). :param timeout: Timeout until element search is performed. :param event_name: The event triggering the swipe.

Terminate a session and release its driver/resources.

Verifies the specified element. :param element: The element to be verified (Image template, OCR template, or XPath). :param timeout: The time to wait for verification in seconds. :param rule: The rule used for verification ("all" or "any"). :param event_name: The name of the event associated with the verification, if any.

Verifies the specified screen by checking element presence. :param elements: Comma-separated string of elements to verify (Image templates, OCR templates, or XPaths). :param timeout: The time to wait for verification in seconds. :param rule: The rule for verification ("any" or "all"). :param event_name: The name of the event associated with the verification, if any.