Linux inspector2

[mahbd]

PR Type

Feature

• Tests for the changes have been added / updated.
• Documentation comments have been added / updated.
• A changelog entry has been made.
• Version number has been updated.
• Required modules have been added to respective "requirements*.txt" files.
• Relevant Test Cases added to this description (below).
• (Team) Label with affected action categories and semver status.

Overview

This pull requests adds new action set for linux. The following linux actions has been added.

• open app
• close app
• click
• enter text
• wait to appear
• wait to disappear
• save attribute
• keystroke keys
• keystroke chars

Test Cases

TEST-12137

Future improvement

Need to have support for flatpak apps. Most actions needs to have more options. New actions needed to have robust testing environment

Documentation

Video

https://drive.google.com/file/d/1t0BgSL-TG6hhZ8YCWVeTM-miC-R12VQe/view?usp=sharing

Example Test

https://qa.zeuz.ai/Home/ManageTestCases/Edit/TEST-12137

Linux inspector setup:

git clone https://github.com/AutomationSolutionz/Zeuz_Python_Node
cd Zeuz_Python_Node
git checkout linux-inspector2
uv run node_cli.py -ild

Available Node commands:

uv run node_cli.py -ild  (This installs all required dependency for linux)
uv run node_cli.py -lsa  (This shows list of available running apps)
uv run node_cli.py -dui  (This generates UI dump. You can use this to automate linux application)
Available Actions:

1. open app
2. close app
3. click
4. text
5. wait to appear
6. wait to disappear
7. save attribute
8. keystroke keys
9. keystroke chars

General guide

1. Launch an application
2. uv run node_cli.py -lsa to get the actual name of the running application
3. uv run node_cli.py -dui app_name > ui.xml This will create a ui dump for the application
4. Use your favorite application to find desired element path and use it in automation

1. Open App

Function: open_app

Description: Launches a Linux desktop application by name. The function searches for the application in /usr/share/applications/*.desktop files and executes it.

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
app_name	element parameter	Application name (e.g., "brave-browser", "gedit")

Parameters:

• app_name (required): The name of the application to launch. Can be:
  • The desktop file basename (e.g., "brave-browser")
  • The application display name (e.g., "Brave Browser")
  • The executable command (e.g., "/usr/bin/brave-browser")

Examples:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | brave-browser

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | gedit

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | Text Editor

Notes:

• The function performs fuzzy matching on application names
• Applications are launched with nohup to run in the background
• Output is redirected to /dev/null

---

2. Close App

Function: close_app

Description: Closes a running Linux desktop application by terminating its process using kill -9.

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
app_name	element parameter	Application name

Parameters:

• app_name (required): The name of the application to close

Expected Result:

• All processes matching the application name are terminated
• Returns "passed" if all processes are successfully killed
• Returns "zeuz_failed" if no process is found or termination fails

Examples:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | brave-browser

Notes:

• Uses pgrep -f to find process IDs
• Sends SIGKILL signal (kill -9) to forcefully terminate
• Closes all instances if multiple processes are running

---

3. Click

Function: click_element

Description: Clicks on a UI element identified by its path or text content.

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
app_name	element parameter	Application name
path	element parameter	Element path (e.g., "0.1.2.3")
text	element parameter	Text content to search for (alternative to path)
wait	element parameter	Wait timeout in seconds (optional, default: 10)

Parameters:

• app_name (required): The application containing the element
• path (optional): Dot-separated indices representing the element's position in the UI tree
• text (optional): Text content of the element (used if path is not provided)
• wait (optional): Maximum time to wait for the element

Expected Result:

• The element is clicked using its action interface
• Returns "passed" on successful click
• Returns "zeuz_failed" if element is not found or click fails

Examples:

Using path:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | brave-browser
path              | element parameter | 0.1.3.5.2

Using text:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | gedit
text              | element parameter | New Document

With wait timeout:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | brave-browser
text              | element parameter | Login
wait              | element parameter | 15

Notes:

• The function tries various action names: "click", "jump", "press", "open", "activate", "select", "clickAncestor", "link.open"
• If the element doesn't support clicking, it traverses up to parent elements
• Text-based search performs exact matching by default

---

4. Text

Function: enter_text

Description: Enters text into an editable UI element (text field, text area, etc.).

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
app_name	element parameter	Application name
path	element parameter	Element path
text	element parameter	Text to enter
wait	element parameter	Wait timeout (optional)

Parameters:

• app_name (required): The application containing the text field
• path (optional): Path to the text element
• text (required): The text string to enter
• wait (optional): Wait timeout in seconds

Expected Result:

• Text is entered into the specified element
• Returns "passed" on success
• Returns "zeuz_failed" if element is not found or text entry fails

Examples:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | gedit
path              | element parameter | 0.1.2.1
text              | element parameter | Hello, World!

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | brave-browser
text              | element parameter | Search
text              | element parameter | automation testing

Notes:

• First attempts to use the EditableText interface
• Falls back to keyboard simulation using xdotool if EditableText is not available
• The element is activated/focused before typing
• Text entry delay is 50ms between characters

---

5. Wait to Appear

Function: wait_for_element

Description: Waits for a UI element to appear within a specified timeout period.

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
app_name	element parameter	Application name
path	element parameter	Element path
text	element parameter	Element text (alternative to path)
wait to appear	action	Timeout in seconds (default: 10)

Parameters:

• app_name (required): The application containing the element
• path or text (required): Element identifier
• timeout (optional): Maximum wait time in seconds

Expected Result:

• Polls for the element every 1 second
• Returns "passed" when element is found
• Returns "zeuz_failed" if element doesn't appear within timeout

Examples:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | brave-browser
text              | element parameter | Login Success
wait to appear    | action            | 30

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | gedit
path              | element parameter | 0.1.2.3
wait to appear    | action            | 15

Notes:

• Useful for waiting for dynamic content to load
• Checks element presence every 1 second
• Does not interact with the element, only verifies its existence

---

6. Wait to Disappear

Function: wait_for_element

Description: Waits for a UI element to disappear (be removed from the UI tree) within a specified timeout.

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
app_name	element parameter	Application name
path	element parameter	Element path
text	element parameter	Element text
wait to disappear	action	Timeout in seconds (default: 10)

Parameters:

• app_name (required): The application containing the element
• path or text (required): Element identifier
• timeout (optional): Maximum wait time in seconds

Examples:

Left                | Middle            | Right
--------------------|-------------------|------------------
app_name            | element parameter | brave-browser
text                | element parameter | Loading...
wait to disappear   | action            | 20

Left                | Middle            | Right
--------------------|-------------------|------------------
app_name            | element parameter | calculator
path                | element parameter | 0.1.2
wait to disappear   | action            | 10

Notes:

• Useful for waiting for loading indicators, pop-ups, or transient elements to close
• Checks every 1 second if element is still present
• Opposite behavior of "wait to appear"

---

7. Save Attribute

Function: save_attribute

Description: Extracts an attribute value from a UI element and saves it to a shared variable for later use.

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
app_name	element parameter	Application name
path	element parameter	Element path
text	element parameter	Element text
<attribute_name>	save parameter	Variable name to save to

Parameters:

• app_name (required): The application containing the element
• path or text (required): Element identifier
• attribute_name (required): The attribute to extract (e.g., "text", "name", "description", "states", "actions", "x", "y", "width", "height")
• variable_name (required): Name of the shared variable to store the value

Expected Result:

• The attribute value is extracted from the element
• Value is stored in shared variables under the specified name
• Returns "passed" on success
• Returns "zeuz_failed" if element or attribute is not found

Examples:

Save text content:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | brave-browser
path              | element parameter | 0.1.2.3
text              | save parameter    | saved_text

Save element name:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | gedit
text              | element parameter | File Menu
name              | save parameter    | menu_name

Save position:

Left              | Middle            | Right
------------------|-------------------|------------------
app_name          | element parameter | calculator
path              | element parameter | 0.1.0
x                 | save parameter    | button_x_position

Available Attributes:

• text - Text content of the element
• name - Element name
• description - Element description
• states - Element states (comma-separated)
• actions - Available actions (comma-separated)
• x, y - Element position coordinates
• width, height - Element dimensions
• Any custom attributes from the element's attribute dictionary

Notes:

• The attribute name should be lowercase without spaces
• Stored variables can be referenced in subsequent actions using %variable_name% syntax
• Default attribute is "value" if not specified

---

8. Keystroke Keys

Function: send_keystroke

Description: Sends keyboard key combinations (hotkeys) such as Ctrl+C, Alt+F4, etc.

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
keystroke keys	action	Key combination(s)

Parameters:

• keystroke keys (required): One or more key combinations separated by commas

Key Combination Format:

• Modifiers: ctrl, alt, shift, super, meta
• Keys: a-z, 0-9, f1-f12, return, enter, tab, escape, esc, backspace, delete, up, down, left, right, home, end, page_up, page_down, insert, space
• Format: modifier+key (e.g., ctrl+c, alt+f4)

Expected Result:

• The specified key combination(s) are sent to the active application
• Returns "passed" if all keystrokes are sent successfully
• Returns "zeuz_failed" if any keystroke fails

Examples:

Single hotkey:

Left              | Middle            | Right
------------------|-------------------|------------------
keystroke keys    | action            | ctrl+c

Multiple hotkeys:

Left              | Middle            | Right
------------------|-------------------|------------------
keystroke keys    | action            | ctrl+a,ctrl+c

Complex combinations:

Left              | Middle            | Right
------------------|-------------------|------------------
keystroke keys    | action            | ctrl+shift+t

Function keys:

Left              | Middle            | Right
------------------|-------------------|------------------
keystroke keys    | action            | alt+f4

Navigation:

Left              | Middle            | Right
------------------|-------------------|------------------
keystroke keys    | action            | ctrl+home,down,down,return

Notes:

• All keys must be lowercase
• Multiple key combinations are separated by commas
• Uses xdotool to send keystrokes
• Keys are sent to the currently focused window
• No spaces allowed in key combination strings

---

9. Keystroke Chars

Function: send_keystroke

Description: Types individual characters or strings as keyboard input, simulating manual typing.

Data Set Format:

Left (Field)	Middle (Type)	Right (Value)
keystroke chars	action	Characters to type

Parameters:

• keystroke chars (required): The string of characters to type

Expected Result:

• Characters are typed one by one with a 50ms delay between each
• Returns "passed" on success
• Returns "zeuz_failed" on failure

Examples:

Type simple text:

Left              | Middle            | Right
------------------|-------------------|------------------
keystroke chars   | action            | Hello World

Type with special characters:

Left              | Middle            | Right
------------------|-------------------|------------------
keystroke chars   | action            | user@example.com

Type numbers and symbols:

Left              | Middle            | Right
------------------|-------------------|------------------
keystroke chars   | action            | Password123!@#